Developer reference · BrandVault
Connect your own BrandVault
This path reaches the brands your organization owns. Read the vault and reports, publish changes, act on recommendations, and create a brand — over MCP or the keyed REST API. The data is private to your organization.
Two ways in, one entitlement
MCP connector
The shorter path for an agent. One endpoint, 14 tools, and OAuth discovery for hosted clients.
Streamable HTTP · OAuth or API key · brand named per call
Keyed REST API
Ordinary HTTP for a program you control. The same records and writes as MCP, under /api/v2.
14 routes · bearer key · brand header
Both surfaces resolve the same organization and the same brand. The payload builders are shared, so a record read over MCP and the same record read over REST agree. A single key works on either surface.
Authentication and scopes
Send a bearer credential. There is no session and no separate login step.
API key
An sk_live_… key minted under Connections. Any member can mint a key for themselves; an admin sees the organization's keys. The raw key is shown once — the store keeps only its hash.
- Organization scope (the default): reaches every brand in the organization. A REST request selects one with the
X-Optimly-Brand: <brand-id>header; an MCP tool takes abrandargument.GET /api/v2/brands(orlist_brandson MCP) enumerates the ids. - Brand scope: pins one brand. No request needs to name it, and a selector naming a different brand is ignored rather than obeyed.
OAuth access token
An oat_ token from the authorization flow, for MCP clients that cannot hold a static key. A connection covers the organization and is attributable to the person who approved it; they can revoke it from Connections. The connector discovers the flow from its 401 response, which points at https://app.optimly.ai/.well-known/oauth-protected-resource. PKCE with S256 is required.
How the brand is resolved
MCP resolves a brand argument by id, then slug, then case-insensitive unique name, always inside the caller's organization. An ambiguous name returns the candidates rather than guessing. A brand-bound credential refuses a sibling — including one that does not exist — instead of silently reading or writing somewhere else. A write must name its brand on an organization-wide credential, and the tool descriptions ask the model to confirm it with the user first.
What you can access
| Surface | Read | Write |
|---|---|---|
| Brand identity | Name, canonical domain, slugs, claim state | — |
| Vault | Active vault, sections with publish_state, competitors, disambiguation, version history | PUT /api/v2/vault / publish_vault |
| Recommendations | All recommendations, with status and effort filters | PATCH /api/v2/recommendations/{rec_id} / act_on_recommendation |
| Reports | List, detail, question analysis, sources, attribution | — (read-only) |
| Brands | List the organization's brands | POST /api/v2/brands / create_brand (see below) |
Nothing on this path exposes another organization's data, the public index's search, or a measurement trigger.
Creating a brand
Brand creation is the one write that does not address an existing brand. It exists so a trusted integration can onboard a brand without a signed-in session.
Required permissions
- Organization-scoped credential. A brand-scoped key or connection already pins a brand and cannot create another; it answers
403with codeorg_scoped_credential_required. - A trusted owner. The person who minted the key, or who approved the OAuth connection, must be a trusted user. A credential has no live mailbox to prove domain ownership, so trust is the authorization. An untrusted or ownerless credential answers
403with codetrust_required.
Required fields
Send name and website_url. A missing field is a 400 validation error. The URL is normalized before the match.
curl -sS -X POST 'https://app.optimly.ai/api/v2/brands' \
-H "Authorization: Bearer $OPTIMLY_KEY" \
-H 'Content-Type: application/json' \
-d '{"name": "Example Company", "website_url": "https://example.com"}'
Existing matches
An exact canonical-URL match already in the organization returns the existing brand instead of creating a duplicate. The status code tells you which happened:
| Outcome | Status | Body |
|---|---|---|
| A new brand was created | 201 | {"created": true, ...brand} |
| The exact URL already existed | 200 | {"created": false, ...brand} |
The match is per organization and excludes archived brands, so re-adding a URL the organization archived creates a new brand. A new brand queues the site prefill scrape; the interactive interview and any report run are deliberately not started.
The same rules apply to the MCP create_brand tool, which takes name and website_url instead of brand.
Verify the connection
A server that answers is not the same as a credential that resolved your organization and brand. Verify in this order:
REST
# 1. The key reaches the organization and lists its brands.
curl -sS 'https://app.optimly.ai/api/v2/brands' \
-H "Authorization: Bearer $OPTIMLY_KEY"
# 2. The brand selector resolves to the brand you expect.
curl -sS 'https://app.optimly.ai/api/v2/brand' \
-H "Authorization: Bearer $OPTIMLY_KEY" \
-H "X-Optimly-Brand: $BRAND_ID"
Check that the second response's name and canonical_domain are the brand you meant.
MCP
Run claude mcp list after adding the connector. The entry should show the endpoint and a successful connection. Then, in the client, call list_brands and get_brand:
List my Optimly brands with list_brands, then call get_brand for the
brand I mean and tell me the name and canonical domain it returns.
Do not describe the connection as working until get_brand returns the expected brand. The MCP reference has the endpoint, client configuration, and full tool list.
Limits and behaviour to expect
- Rate limit: 60 requests per minute per token, shared with the keyed API. Responses carry
X-RateLimit-Limit,-Remaining, and-Reset; over the limit answers429. - Reports are read-only: no route or tool starts a measurement run. Schedules are set in the application.
- Writes are versioned: publishing the vault creates a new version and records its origin (
api), so an API-authored change is distinguishable from one made in the application. - Partial vault updates: sections you omit copy forward. Omitted competitor and disambiguation sets are preserved; send the complete set to replace it.
- No cross-organization access: a credential can never name its way into another organization's brand.
- No delegated REST OAuth: the OAuth authorization server exists for the MCP connector. Use an API key for the keyed REST API.
Not the public index
This path cannot search the public Optimly Index, and the public index cannot reach these records. If you need public brand information, use the public data quickstart; it needs no credential and grants no write access.
There is no public-index MCP server yet. That is a product gap, not a configuration detail.