The business app API and AI connections

Every screen of the business app gets its data from one versioned API at /api/v1. The coming phone app and AI apps (over MCP) use the same API, with the same permissions, so they always see and do the same things.

Signing in

The API accepts:

• the web session (the business app uses this);
• Authorization: Bearer <access token> from a signed-in account (the phone app);
• Authorization: Bearer cfk_…, an API key from Settings → API & MCP;
• Authorization: Bearer cfo_…, the connection an AI app gets when you connect it over MCP.

Every request is checked against the person's role in that business and each pipeline's access, the same way as in the app. An API key or AI connection acts as the person who made it, only in that agency's businesses, and needs the write permission to change anything; a read-only key can look but not touch.

AI apps (MCP)

A connected AI app gets 34 tools for The Pantheon (17 for contacts, opportunities and tasks, 6 for automations and 11 for conversations). They use this same API and can only do what the person who connected them can do:

• list businesses it can work in;

• contacts: find contacts, get a contact, create a contact (someone already there with the same email or phone is updated instead), update a contact (name, type, time zone, owner, Additional information, custom fields), tag and untag a contact, add a note to a contact or an opportunity;

• opportunities: list pipelines (with stages and the person's access), find opportunities, get an opportunity, create an opportunity, move an opportunity (to a stage, or won / lost / abandoned / reopened; needs Edit access to the pipeline), update an opportunity (name, value, owner, close date, probability, main contact);

• tasks: list tasks, create a task (with a due time, reminder and repeat), complete a task;

• automations: list automations, get an automation (its draft, a plain summary of every step, and the problems that would stop it being switched on), create an automation (as a switched-off draft), update an automation (its triggers, steps, settings or name), test an automation with one contact (waits skipped, emails only to the tester, nothing billed), and switch an automation on or off (switching on is refused, with the list of problems, while anything is wrong).

• conversations: list conversations, get a conversation, search messages, list saved replies and fill in a saved reply, draft a reply (it waits on the conversation for your team to review — the default), send a reply (only after the person confirms: without that it just shows what would be sent), add a comment, assign, mark read and archive a conversation.

The automation tools follow the same rules as the builder: only people who may build automations in that business can change them.

Emails and phone numbers are changed in the app, not through the AI tools. If the AI app retries a create within 10 minutes, it doesn't make a duplicate.

Addresses

Business data lives under /api/v1/businesses/{businessId}/…, for example …/contacts, …/contacts/{contactId}/timeline (the Activity history), …/companies, …/pipelines, …/pipelines/{pipelineId}/board, …/opportunities, …/tasks, …/tags, …/fields, …/views, …/bulk, …/imports. GET /api/v1/me lists the businesses you can open.

The full list, with what each one accepts, is the OpenAPI document at /api/v1/openapi.json.

Conventions

• Pages: lists answer with items and a nextCursor; pass it back as ?cursor= with ?limit= (up to 200).
• Sync: ?updatedSince=<date> on the contact, company, opportunity and task lists returns everything changed since, including deleted records, so a phone can keep its copy up to date.
• Editing safely: send the record's version (as If-Match, or version in the body). If someone changed it in between you get 409 with This contact changed since you opened it, never a silent overwrite.
• Retrying safely: send an Idempotency-Key header on any POST. A retry with the same key gets the first answer back for 24 hours, and nothing is done twice.
• Errors always look like { "error": { "code": "…", "message": "…", "field": "…" } }, with a plain message.
• Limits: changes are limited to 120 a minute per person.

Changes that would break an existing app go into /api/v2; /api/v1 keeps working.