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.
Build with public brand data
Find a brand by name or domain, fetch its structured profile, and use it in a source-attributed answer. No account, no key, and no claim.
Keyless HTTP · search, JSON, markdown, bulk feed · read-only
Connect your own BrandVault
Work with the brands your organization owns: read the vault and reports, publish changes, and act on recommendations over MCP or REST.
Bearer key or OAuth · 14 tools · 14 routes · your organization only
At a glance
| Path | Authentication | Can read | Can 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.