API
Connecting to the brain
There is one brain and a few doors: AI clients use the MCP connector, code uses the REST API, apps hand over episodes and listen to webhooks, and outside services connect through Connections. This page says which one to use when.
Which door you need depends on who is connecting, and which way the information goes.
Into the brain
| You want to | Use | Sign in with |
|---|---|---|
| Work with the brain from an AI client: Claude, Claude Code, Cursor or anything that speaks MCP | The MCP connector | OAuth, per person |
| Read or write from your own code, a pipeline or a script | The REST API | An organisation's API key |
| Hand over something that happened: a meeting, a published post, a result | POST /api/v1/episodes, which is safe to send twice | An API key |
| Build a tool that sits in the suite's menu | A manifest at /.well-known/epic-tool.json on your own domain | Your people sign in with Epic Context; actions arrive signed |
Out of the brain
| You want to | Use |
|---|---|
| Hear when context changes | A webhook on a profile, signed the Standard Webhooks way |
| Keep a copy of a part of the context | A profile bundle, with an ETag |
| Take everything with you | The export: a ZIP of markdown files with the links, messages, images and documents, or JSON; the full history on request |
From the brain to an outside service
An outside API that knows nothing about Epic Context connects through Connections, in Settings › Organisation. It works in three steps:
- A connector describes the service: its address, how it signs in, and what it can do. Some are built in. For anything else, an AI session writes one from the service's documentation with
define_connection, or you paste it in. - A person adds the key, in Settings. It is stored encrypted and nobody can read it back. A key never goes through a chat.
- Actions run through one gateway. An AI session finds them with
list_tool_actionsand runs them withcall_tool_action, with a reason. Every run is logged, and a job that takes a while is followed withcheck_run.
A connector looks like this:
{
"id": "acme-images",
"name": "Acme Images",
"description": "Makes product images. Work goes here for a visual.",
"base_url": "https://api.acme.example",
"auth": {
"fields": [{ "key": "token", "label": "API key" }],
"name": "Authorization",
"template": "Bearer {token}"
},
"actions": [
{
"name": "create_image",
"description": "Start an image. It costs credits and takes a while.",
"method": "POST",
"path": "/v1/images",
"input": { "type": "object", "required": ["prompt"], "properties": { "prompt": { "type": "string" } } },
"spends": true,
"job": { "status_path": "/v1/images/{id}", "id_field": "id", "state_field": "status", "done": ["ready"], "failed": ["error"] }
}
]
}
- In a
path,{name}takes one argument and{name*}may hold slashes. Other arguments go in the query or the JSON body. - A connector reaches public
httpsaddresses only. Redirects are refused and answers are bounded. - Changing the address, the sign-in or the actions of a connector drops its key, so a key can never do something new without a person looking and entering it again.
Data sources: LinkedIn and Microsoft Advertising
Some services need a login, not a key. LinkedIn and Microsoft Advertising are data sources: an owner or admin signs in once for the whole organisation under Settings › Organisation › Connections › Data sources, and then chooses per project which ad account and company page it reads. A project without its own choice reads the organisation's default.
Epic Context keeps the login and reads the numbers itself. Nothing gets a token:
- An AI session asks with
list_data_sources,query_linkedinandquery_microsoft_ads, for the project of the call. - Analytics' sources (Google Analytics, Search Console, Google Ads, Ahrefs, an organisation's own measurement) are connected in Settings › Organisation › Connections, and what they read is chosen there too, under the connection: for the organisation, and per workspace where one differs. An AI session asks them with
get_website_figures,query_google_analytics,query_search_console,query_google_adsandquery_ahrefs;list_data_sourcesnames them too. - A suite app asks with its own identity:
GET /api/v1/suite/orgs/{org}/sourcesfor what is connected,POST …/sources/{source}/reportfor a dashboard, andPOST …/sources/{source}/queryfor an AI's question.
A service's own rules hold at every door. LinkedIn's AI policy allows an AI numbers only (ads, campaigns, page counts, per-post numbers, lead counts), never member data, post text or the page's name. Microsoft Advertising is read through a fixed list of read operations. Reading only: nothing changes a campaign.
The models behind the brain
A model provider is a connection too. An organisation can run the brain's own thinking on another model: anything that speaks the chat-completions shape, such as Mistral, Azure OpenAI or your own AI gateway. A choice can be made per agent, per role or for everything, and the most specific one wins. A chosen model is a promise: if it cannot be reached the call fails, and it never falls back to another vendor.
An installation of its own (planned, see Hosting, security and data) sets MODEL_PROVIDER, MODEL_BASE_URL and MODEL_DEFAULT once, and every organisation there follows. That address may be on your own network.
Next
- Endpoints: episodes, bundles and webhooks in detail.
- Add a tool to the suite
- Hosting, security and data
Last updated: