Skip to content

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 toUseSign in with
Work with the brain from an AI client: Claude, Claude Code, Cursor or anything that speaks MCPThe MCP connectorOAuth, per person
Read or write from your own code, a pipeline or a scriptThe REST APIAn organisation's API key
Hand over something that happened: a meeting, a published post, a resultPOST /api/v1/episodes, which is safe to send twiceAn API key
Build a tool that sits in the suite's menuA manifest at /.well-known/epic-tool.json on your own domainYour people sign in with Epic Context; actions arrive signed

Out of the brain

You want toUse
Hear when context changesA webhook on a profile, signed the Standard Webhooks way
Keep a copy of a part of the contextA profile bundle, with an ETag
Take everything with youThe 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:

  1. 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.
  2. A person adds the key, in Settings. It is stored encrypted and nobody can read it back. A key never goes through a chat.
  3. Actions run through one gateway. An AI session finds them with list_tool_actions and runs them with call_tool_action, with a reason. Every run is logged, and a job that takes a while is followed with check_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 https addresses 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_linkedin and query_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_ads and query_ahrefs; list_data_sources names them too.
  • A suite app asks with its own identity: GET /api/v1/suite/orgs/{org}/sources for what is connected, POST …/sources/{source}/report for a dashboard, and POST …/sources/{source}/query for 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

Last updated: