Skip to main content
The Deal Brain API gives you HTTP access to deals, action items, meetings, and Deal Brain’s query engine. Use it for dashboards, ETL, internal tools, and scheduled jobs. If you’re building an AI agent, the MCP server is the better fit — it exposes a broader capability surface, including Signals, Agents, Playbook, and Canvas configuration. See which surface to use.

​
Base URL

​
Authentication

Every request needs an API key sent as a Bearer token:
Treat your API key like a password. A key belongs to your organization, not to the person who created it — anyone holding it acts for the whole organization. Keep it server-side, never ship it in a browser bundle or mobile app, and never commit it.

​
Create a key

You create and list API keys in the Deal Brain web app, under Settings → API Keys. Only an organization admin can use that page, so if you’re building an integration and aren’t an admin, ask one to issue a key for you.
1

Open the API Keys settings page

Sign in to Deal Brain as an organization admin. The page lists the keys your organization has already created.
2

Create a key

Create a new key and give it a name that identifies the integration it’s for. A name per integration makes the list readable later.
3

Copy the secret immediately

Deal Brain shows the key’s secret exactly once, at creation. Copy it straight into your secret store. Once you leave the page, the secret can’t be retrieved — the list shows the key exists, not what it is.

​
Replace a key

Deal Brain has no revoke, delete, or rotate operation today. Rotating a key means creating a replacement and moving your integrations over to it:
1

Create a second key

Create a new key on the API Keys page and copy its secret.
2

Switch your integrations over

Update every service that authenticates with the old key. Because both keys work at once, you can cut over one service at a time with no downtime.
The old key stays valid. You can’t revoke, delete, or disable a key through the UI today, so creating a replacement does not turn off the previous one. Assume any key you have ever issued still works. If a key leaks, contact support — swapping your integrations to a new key does not contain the exposure on its own.

​
What a key is authorized to do

API keys are organization-owned, and the identity a request runs as depends on whether you narrow it: A bare key is an organization principal. It is not a stand-in for the user who created it, and it is not limited by that user’s own visibility. Treat a key as organization-wide access, and scope it down deliberately when you don’t want that. To narrow a request to one member, send the X-Acting-User header with that member’s user ID or email:
The value must name a real member of your organization. Which endpoints accept X-Acting-User, and how each one responds to a member it can’t resolve, is documented per endpoint in the reference — POST /api/v1/canvas/generate is the one that documents it today.

​
What’s available

Read

Deals, deal state, action items, meetings, sales process, and session context.

Query

Describe entities, then filter, aggregate, and fetch across them with a typed field catalog.

Agentic search

Natural-language questions answered over deal memory.

Canvas generation

Render a Canvas template as an async job, then poll for the result.

​
The query API

Most of the surface is straightforward REST. The query endpoints are worth understanding before you use them, because they’re the most capable part. The pattern is describe, then query:
1

Discover what you can query

GET /api/v1/query/describe returns every queryable entity and the users you can scope to.
2

Get an entity's fields

GET /api/v1/query/describe/{entity} returns a typed field catalog, including EAV virtual columns — so custom CRM fields are queryable, not just standard ones.
3

Search, aggregate, or fetch

POST /api/v1/query/{entity} filters to matching IDs. /aggregate does group-by with measures. /fetch retrieves rows by ID with optional relational expansion.
Describe first rather than hardcoding field names. Field catalogs differ per organization, because they reflect your CRM.

​
Async jobs

Canvas generation doesn’t return a document directly. POST /api/v1/canvas/generate starts a job and returns a run_id; poll GET /api/v1/canvas/generate/{runId} until it completes.

​
Reference

Full endpoint reference, including request and response schemas, is in the pages that follow.