Developer reference

Build with Optimly

Two paths, one question: are you reading public brand information, or working with a brand your organization owns? Pick the path that matches, and start there. Neither requires an SDK.

At a glance

PathAuthenticationCan readCan write
The Optimly Index None Published brand profiles, their sections and sources, categories, the bulk feed Nothing
BrandVault over MCP Organization API key, brand-scoped key, or OAuth access token Your organization's brands, vault, versions, recommendations, reports, attribution Publish the vault, act on a recommendation, create a brand (trusted users)
BrandVault over REST Organization or brand-scoped API key The same records as MCP The same writes as MCP, using ordinary HTTP verbs

Authentication, in one paragraph

The public index takes no credential. Anyone can read /brands.json, search brands, and fetch a brand's HTML, JSON, or markdown. This is the "no key" path, and it is read-only.

BrandVault surfaces take a bearer credential: an sk_live_… API key minted under Connections, or an oat_ OAuth access token for a client that cannot hold a static key. The credential resolves your organization; the brand is either pinned by a brand-scoped credential or named per request. There is no separate login step and no session to keep.

Which path should I use?

I need to answer a question about a company

Use public brand data. Search the Optimly Index, fetch the profile, and keep each section's source and date in your answer. This works for any published brand without asking its owner for anything.

I manage the brand and want to read or update it

Use your own BrandVault. It reaches only the brands in your organization, and it is the only path that can publish a profile or act on a recommendation.

I need both

Use both. They are separate surfaces with separate credentials. A public read never grants access to private reports, and a BrandVault credential never widens into another organization's data.

What is not available yet

These are product gaps, not hidden features. Do not build around them as if they shipped.

  • No public-index MCP server. The MCP connector is authenticated and organization-scoped; it exposes BrandVault data for your own brands, not the public index. Public brand data is HTTP-only today.
  • No general product or intent search. /brands/search?q= matches brand names and exact canonical URLs/domains. It does not search products, categories, or free-text profile sections.
  • No SDK. Both surfaces are plain HTTP and JSON. Use your language's HTTP client.
  • No API-triggered measurement. Reports are read-only over MCP and REST. Measurement runs on schedules set in the application.
  • No public add or claim. Adding or claiming a brand happens in the signed-in application, not through the public index.

Reference

The MCP connector — endpoint, authentication, client setup and the full tool list. The keyed REST API — the route list under /api/v2, conventions and errors.