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.
Not sure whether the API is the right interface? Compare MCP, the Agent API, and the Optimly Agent in Slack.
The latest REST API is v1. Work-management operations currently use a separate governed contract version, 3.0.0. The work contract version does not change the REST base URL to v3.
Base URL
https://app.optimly.ai/api/v1/agentThe API requires paid access. Optimly Platform provides read and non-action capabilities. Governed action workflows require the AI Brand Execution Program, the relevant brand permissions, and explicit approval. Keys are scoped to one organization and brand; free accounts cannot generate or use Agent API or MCP credentials.
Follow the agent-assisted access, payment, authorization, and verification flow.
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.
The synchronized complete capability contract is:
| Capability | Methods and path | Access | Side effect | MCP tools |
|---|---|---|---|---|
brand.read | GET /api/v1/agent/brand-vault | free; read_brand | none | brand_status, brand_vault_profile |
reports.read | GET, PATCH /api/v1/agent/brand-vault | signal_pro; read_reports | none | delta_report, delta_report_details, delta_report_history, brand_sources, competitive_analysis, brand_monitor, brand_publication_match, get_whitespace_candidates, get_retrieval_opportunities |
whitespace.manage | PATCH /api/v1/agent/brand-vault/whitespace-candidates/:candidateId/status | signal_pro; write_brand | mutation | update_candidate_status |
evidence.read | GET /api/v1/agent/evidence | free; read_brand | none | get_ai_representation, get_site_retrievals, get_site_readiness, get_actions, get_attribution_evidence |
website.read | GET, POST /api/v1/agent/website | signal_pro; read_reports | none | inspect_website, get_agent_activity, get_agent_content_gaps, inspect_agent_view, simulate_agent_preview |
website-analytics.read | GET /api/v1/agent/website-analytics/installation | enterprise; read_reports | none | get_website_analytics_installation, get_website_analytics_installation_status |
website-analytics.install | POST /api/v1/agent/website-analytics/installation | enterprise; write_brand | mutation | prepare_website_analytics_installation, activate_website_analytics |
research.guidance | POST /api/v1/agent/research/guidance | signal_pro; read_reports | none | get_recommendation_guidance |
work.read | GET /api/v1/agent/work | enterprise; view_actions | none | get_agent_work, get_agent_work_changes, get_agent_work_context, get_work_status |
work.manage | POST, PATCH /api/v1/agent/work | enterprise; record_actions | mutation | save_recommendation, save_draft, record_agent_feedback, record_checklist_progress, request_customer_input, record_customer_response, record_work_verification, record_work_outcome, assign_recommendation, start_recommendation, dismiss_recommendation, preview_recommendation_adaptation, confirm_recommendation_adaptation, discard_recommendation_adaptation, record_customer_completion, verify_recommendation_now, submit_recommendation_implementation |
actions.read | GET /api/v1/agent/operations | enterprise; view_actions | none | get_action_status, list_pending_approvals, check_action_idempotency |
actions.propose | POST /api/v1/agent/operations/actions | enterprise; record_actions | proposal | create_execution_action, create_brand_vault_publish_action |
actions.execute | POST /api/v1/agent/operations/actions/:actionId/transition | enterprise; record_actions | mutation | transition_execution_action |
approvals.request | POST /api/v1/agent/operations/approvals/request | enterprise; request_approvals | approval | request_action_approval |
approvals.decide | POST /api/v1/agent/operations/approvals/:approvalId/decision | enterprise; record_approval_decisions | approval | record_approval_decision |
brand.correct | POST /api/v1/agent/brand-vault/update-section | free; execute_brand_vault_actions | mutation | brand_update |
brand.publish | POST /api/v1/agent/brand-vault/publish | enterprise; execute_brand_vault_actions | mutation | brand_update, brand_publish |
coverage.manage | GET, POST /api/v1/agent/coverage | enterprise; manage_brand_vault | mutation | coverage_list, coverage_add, coverage_add_many |
The actual /capabilities response is authoritative. Availability varies by plan, permissions, and brand configuration.
To inspect the complete tenant-free contract without a credential, use the public schema:
curl https://app.optimly.ai/api/v1/agent/schemaThe current schema contains 18 capabilities mapped to 61 API-backed MCP tool names. The Scout MCP server also exposes customer discovery, consumer, experiment, and administrative tools that do not have one-to-one Agent API endpoints.
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.