Agent API
Optimly Agent API
Connect a custom agent harness to Optimly's versioned, brand-scoped API.
The Optimly Agent API is the versioned interface for custom agent harnesses. It exposes the same brand-scoped evidence and governed actions as Optimly MCP without requiring an MCP client.
Base URL
https://app.optimly.ai/api/v1/agentThe API is available only to eligible paid accounts. Keys are scoped to one organization and brand; free accounts cannot generate or use Agent API or MCP credentials.
Authenticate
Send the selected brand's osk_ key in the X-API-Key header:
X-API-Key: osk_your_brand_scoped_keyStore the key in an encrypted secret manager or managed egress gateway. Never print, inspect, log, or place it in browser code. A worker that serves multiple clients must resolve the credential from the active client context, not from a shared core-worker slot.
Discover capabilities first
Every run begins with capability discovery:
curl https://app.optimly.ai/api/v1/agent/capabilities \
-H "X-API-Key: $OPTIMLY_API_KEY"Confirm the returned organization and brand before continuing. Treat the returned capability, method, and endpoint records as the contract for that credential. Do not hard-code an operation that is not advertised and do not switch to another client's credential after a denial.
Capabilities can include:
| Capability | Purpose |
|---|---|
brand.read | Read the authorized Business Profile and verified brand facts |
reports.read | Read available reports and measured evidence |
evidence.read | Read citations and supporting evidence |
website.read | Read authorized website context and activity |
work.manage | Read or maintain recommendations, drafts, feedback, and checklist work |
actions.read | Read action, approval, and execution state |
actions.propose | Create an immutable proposed action |
approvals.request | Request approval for an exact action payload |
approvals.decide | Record an authorized approver's explicit decision |
brand.correct | Execute an approved Business Profile correction |
brand.publish | Execute an approved BrandVault publish |
coverage.manage | Maintain supported off-site coverage work |
The actual /capabilities response is authoritative. Availability varies by plan, permissions, and brand configuration.
Read safely
Choose an advertised operation with no side effect and call the returned method and path. Reads remain constrained to the organization and brand resolved from the credential. Never accept a caller-supplied tenant identifier as a way to escape that scope.
Handle failures
| Status | Meaning | Required behavior |
|---|---|---|
401 | Missing, invalid, expired, or revoked key | Stop and repair the selected client's credential |
403 | Plan, permission, approval, or mutation envelope is insufficient | Do not bypass governance or retry as another client |
409 | Action state or idempotency conflict | Read the existing action and reconcile before retrying |
429 | Request limit reached | Honor retry guidance and back off |
Do not fall back to MCP when an Agent API capability is absent. Failing clearly preserves the credential, capability, and governance boundaries the caller expects.
Execute mutations through governance
A correction, publish, website update, or off-site action requires an immutable proposal, explicit approval, a complete mutation envelope, and a stable idempotency key. Authentication by itself never authorizes a mutation.