Developer reference
Use Optimly from a program
Optimly exposes two surfaces. Both authenticate as a brand, and both read and write the same underlying records as the application.
MCP connector
The right door for an agent. One endpoint, twelve tools, and an OAuth flow your client can discover. Use it when a person is driving Claude, Cursor, or another MCP client.
Streamable HTTP · twelve tools · OAuth or an API key
Keyed REST API
The right door for a program you are writing. Plain HTTP, a bearer key, and no session. Use it from a script, a job, or your own agent loop.
13 routes under /api/v2 · bearer key · 60 requests/minute
Which should I use?
An AI client that already speaks MCP
Use the MCP connector. You give the client a URL and it discovers the rest. This is how the in-app setup recipes connect Claude, Cursor, and hosted connectors.
Code you control
Use the keyed REST API. It is the same data with ordinary verbs, so it fits anywhere you would call an HTTP API.
Both at once
They are not exclusive. A single key works on either surface, and the payloads come from the same builders, so a record read over MCP and the same record read over REST agree.
Authentication
Both surfaces take a bearer credential and resolve the brand from the request — named per call, or pinned by a brand-scoped credential. There is no separate login step and no session to keep.
API key
An sk_live_… key created in the application under Connections. It is shown once. A new key reaches every brand in the organization: a REST request names one with an X-Optimly-Brand header and an MCP tool takes a brand argument, both drawn from GET /api/v2/brands (or list_brands). Choosing a single brand when you create the key pins it instead, and then no request names one.
OAuth access token
An oat_ token from the authorization flow, for clients that cannot hold a static key. The MCP connector advertises the whole flow at its resource-metadata URL, which is how a hosted connector sets itself up. A connection covers every brand in the organization, and the person who approved it can revoke it from Connections.
What the surface will not do
Reports are read-only on both surfaces. There is no tool or route that starts a measurement run — measuring is a human act, and the schedules that produce reports are set in the application.
Writing is limited to two things: publishing a brand profile, and acting on a recommendation. Nothing publishes to a customer-facing surface without an owner approving it.