API overview

Everything a developer needs to find first: how API keys and their scopes work, where the endpoint reference lives, how organization webhooks are signed, how agents publish their A2A identity, and how Akili relates to MCP.

Updated October 2026Developers1 of 1

Short answer

The Akili API is the same REST surface the web app uses, served under the /api prefix on the backend host. Authenticate with a platform key (prefix ak_) in Authorization: Bearer or x-api-key; create one with POST /api/api-keys/create while signed in. Scoped keys cover flows and social publishing, organization webhooks are HMAC-signed, and the endpoint-by-endpoint reference lives under /build/docs.

API keys and scopes

A platform key is created for your own account while you are signed in, carries a name, an optional set of scopes and an expiry (90 days unless you pass one), and is shown once. Akili stores a hash. There is no rotation call; create a new key and delete the old one.

Authenticate a request

# either header works
Authorization: Bearer ak_...
x-api-key: ak_...

The request that creates a key, with a worked example, is in Getting Started under /build/docs. The scopes a key can carry:

flows:read — List flows and read runs.
flows:run — Trigger a flow run.
flows:write — Create, edit and publish flows. Implies flows:read.
social:read — Read publishing channels, posts and the queue.
social:write — Create, schedule and publish posts. Implies social:read.

Write implies read. flows:write satisfies a route that asks for flows:read.
Scopes are enforced where they are declared. Flow and social-publishing routes check them. A route without a declared scope accepts any valid key of the account.
No scopes means full access. A key created with an empty scope list acts as its owner on every route. Prefer the narrowest scopes for automation.

Heads up:Keys are created in Settings → API keys (?settings=api-keys), where each one is listed with its prefix, scopes and dates and can be revoked. The key itself is shown once, right after it is created: store it then. The request above does the same from code, as the alternative for scripts.

The developer reference

The full developer documentation lives at /build/docs, in English, in these sections:

Developer documentation sections
Section	Path	Covers
Getting Started	/build/docs/getting-started	Keys, base URL and a first request.
Agent Development	/build/docs/agent-development	Building agents that run on the platform.
Integration Development	/build/docs/integration-development	Integrations and their actions, including search.
API Reference	/build/docs/api-reference	Endpoints, request and response shapes, errors.
Marketplace Guidelines	/build/docs/marketplace-guidelines	What a listing must meet before review.

Requests from the browser go through the app’s /backend proxy with a short-lived session token; from your own code call the backend host with the /api prefix and a key. Rate limits (a 429 with the error code rate_limit.exceeded and the X-RateLimit-* headers), error shapes and every endpoint are described there, not repeated here.

Organization webhooks

Owners add webhooks under Settings, Webhooks, or through /api/org-webhooks with the organization.settings:write permission. Each hook has a URL, a selection of events and a secret that is shown once; Rotate issues a new secret and Test sends a webhook.test event.

Webhook events
Event	When
social.post.published	A scheduled or immediate post went out.
social.post.failed	A post could not be published.
social.post.awaiting_approval	A post is waiting for an approver.
social.channel.reconnect	A channel needs to be reconnected.
social.post.metrics_updated	Engagement metrics for a post were refreshed.
flow.run.completed	A flow run finished successfully.
flow.run.failed	A flow run ended in error.
flow.notify	A notify node in a flow fired.
webhook.test	Sent by the Test button.

Verify a delivery

Delivery headers

X-Akili-Event: flow.run.completed
X-Akili-Delivery: <delivery id>
X-Akili-Attempt: 1
X-Akili-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with your secret>

Recompute the HMAC over the timestamp, a dot and the raw body, compare it to v1 in constant time, and reject timestamps older than five minutes. A delivery that does not get a 2xx is tried up to five times in all, with exponential backoff starting at ten seconds, and a hook that fails twenty times in a row is paused until you re-enable it.

Agent-to-agent (A2A)

Every agent publishes an agent card and a JSON Web Key Set so other systems can discover it and verify what it signs. Both are public, rate-limited to 120 requests per minute per address, and served on the backend host without the /api prefix:

A2A discovery

https://<backend host>/agents/<agentId>/.well-known/agent.json
https://<backend host>/agents/<agentId>/.well-known/jwks.json

See Share and publish an agent for the agent-side settings.

MCP

Akili is an MCP client. Chats, agents and flows call tools on MCP servers you connect, whether a catalog app or your own server over Streamable HTTP; see Apps and connectors. Akili does not expose your agents or chats as a general MCP tool server. The one server it can host is a context server at /mcp/context (profile, memories, recent chats, with OAuth discovery metadata), which an operator turns on per installation and which is off by default.

Bring your own provider keys

Model provider keys are configured per organization, not per person, under Settings, Organization providers, by someone with the organization.providers:write permission. OpenAI, Azure OpenAI, Anthropic, Google and Google Vertex, Mistral, xAI, Perplexity, OpenRouter and Ollama are supported, alongside search and media providers. See Organization.

Good to know

Two key families. ak_ keys are platform keys for your account; akl_ keys are Marketplace developer keys managed at /build/api.
Expiry is enforced, not warned. A request with an expired key is rejected; nothing emails you beforehand. Record the date when you create one.
Webchat is not an API-key surface. The public agent chat endpoint used by the embedded widget authenticates with a webchat session, not a key. See Embed the webchat widget.
Flows are the automation API. A webhook-triggered flow plus a flows:run key covers most integration needs without custom endpoints.

Frequently asked questions

Is there a key with chat or knowledge scopes?

Not as named scopes. The scope list covers flows and social publishing. A key created without scopes keeps its owner’s full access, which is the way to call routes that have no scope of their own; treat such a key like a password.

Where do I create an Akili API key?

In Settings → API keys (?settings=api-keys): name the key, tick the scopes you want (none means full access), pick an expiry of 30, 90 or 365 days and copy the key when it is shown, which happens once. From code, POST /api/api-keys/create through the auth service while signed in creates the same key.

Is there an OpenAPI or Swagger document?

No. The API Reference under /build/docs is the maintained description of the endpoints.

Does Akili host an MCP server I can point my IDE at?

Not as a general tool server. Akili consumes MCP servers. An operator can enable a narrow context server that exposes your profile, memories and recent chats to an MCP client; it is off by default.

What are the akl_ keys on the /build/api page?

Marketplace developer keys. They read your publisher data (subscribers, revenue, listings) through /api/marketplace/v1 and are managed from /build/api. They are separate from the ak_ platform keys on this page.