Base URL
Authentication
Every request needs an organization API key sent as a Bearer token:Manage keys
API keys live in the Tempo web app under Settings → API Keys. Only an organization admin can open that page. If you are building an integration and are not an admin, ask one to issue a key for you.1
Create a key
Click Create Key and give it a name that identifies the integration it is for. One name per integration keeps the list readable later.
2
Copy the secret immediately
Tempo shows the key’s value exactly once, at creation. Copy it straight into your secret store. After you close the dialog, the value cannot be retrieved. The list shows that the key exists, not what it is.
3
Watch usage
The list shows each key’s name, creation date, and Last used date. A key that has not been used in a long time is a candidate for deletion.
4
Delete a key you no longer need
Click the delete control next to the key and confirm Delete key. Tempo rejects a deleted key on its next request.
Rotate a key
Rotate a key by creating its replacement first, then deleting the old one:1
Create a second key
Create a new key on the API Keys page and copy its value.
2
Switch your integrations over
Update every service that authenticates with the old key. Both keys work at once, so you can cut over one service at a time with no downtime.
3
Delete the old key
Once nothing uses it, delete the old key. If a key has leaked, delete it right away and contact support so we can check for unexpected use.
What a key is authorized to do
API keys are organization-owned. 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 visibility. Treat a key as organization-wide access and narrow it deliberately when you do not want that.
To run a request as one member, send the
X-Acting-User header with that member’s user ID or email:
X-Acting-User. The value must name a member of your organization; otherwise the request fails with 403. What the header changes depends on the endpoint. For example, GET /meetings reads the acting member’s calendar, and the Themes endpoints apply the acting member’s role to evidence access. Deal reads on the read endpoints stay organization-wide either way. The query endpoints are organization-bounded and scope to a member through the request body instead, with scope: { as: "user", user: "<id or email>" }.
What’s available
Read
Session context, deals, deal state, action items, meetings, and the sales process.
Deal updates
GET /api/v1/deal-updates lists the CRM field updates Tempo proposed or wrote from evidence. Read-only; review happens in the app.Themes
GET /api/v1/themes and GET /api/v1/themes/{id} browse recurring Themes across the organization, when available.Signal activity
Read where live signals appeared and the observations behind them.
Query
Describe entities, then filter, aggregate, and fetch across opportunities, accounts, and contacts with a typed field catalog.
Agentic search
POST /api/v1/agentic-search/deal-context returns cited deal evidence. Set detail to summary for a prose answer.Read search results
POST /api/v1/agentic-search/deal-context returns the first page of a saved search and its run_id. Evidence is the default. Set detail to summary when you need an answer in prose with citations. Check coverage before treating a partial result as complete.
Read later pages with GET /api/v1/agentic-search/deal-context/runs/{run_id}. Pass catalog.next_cursor as catalog_cursor to continue evidence. Pass answer.next_cursor as answer_cursor to continue the summary. Read an oversized evidence item with its evidence_marker, then follow detail.next_cursor as detail_cursor. These reads use the saved run.
Search effort
Omitbudget_mode to use auto. A request for one deal, named in deal_id or deal_ids, starts at instant. Other requests start at medium (Balanced) and may continue at high when more work is useful. Set instant, medium, or high when you need a specific effort level.
The query API
Most of the surface is straightforward REST. The query endpoints are worth understanding before you use them, because they are 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 custom CRM fields as virtual columns.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.Deal updates
GET /api/v1/deal-updates returns the same payload as the MCP list_deal_updates tool. By default it lists pending updates on open, non-renewal deals touched in the last 30 days, with no-op proposals hidden. Pass status=approved for updates already written to the CRM, deal_state=all to include closed deals, and max_days_since_update to widen the window. Each update carries the proposed and current values, the write mode, and sources that cite the observations and artifacts behind it.
This endpoint never writes to the CRM. Pending proposals can be reviewed in the Tempo app or through the MCP manage_fields tool.
Themes
The Themes endpoints take the same parameters as the MCPsearch_themes and get_theme tools, read from the query string. List parameters such as sources, types, families, statuses, and include accept comma-separated or repeated values. Unknown parameters return 400.
Despite their names, all_time_* counts cover a limited range, not all history. The new status means first seen within that range during the selected period. See Choose a period.
A nonempty query without days, from, to, statuses, or sort=growth defaults to 365 days. first_seen_at, last_seen_at, and themes_through also use the longer range.
Every successful response carries an availability field. It is hidden if Themes is turned off for your organization and unpublished until the first themes are built. While Themes is ready, a theme lookup returns 404 for an unknown or filtered-out ID. A topic lookup also returns 404 in that case when topic grouping is on. When topic grouping is off, a topic lookup returns topic: null with 200. While hidden or unpublished, GET /api/v1/themes/{id} returns a null resource with 200.
Hidden and unpublished responses also include a next_step field that explains why there are no themes to read. A read that cannot finish in time returns 503. Try again later or use a shorter window.
Themes responses can include computed_at, the UTC time when counts were computed. The first page of GET /api/v1/themes without a query or deal_id can reflect counts computed up to six hours earlier. Searches, deal_id lists, later pages, and GET /api/v1/themes/{id} are computed for each call. Pages can have different computation times, so a theme may repeat or be missed when counts change between pages.
Signal activity
These read-only endpoints show where live signals appeared. Use them to build account lists or inspect cited observations without opening each signal in the app.
An organization API key reads signal activity across the whole organization, including deals that other endpoints hide. Add
X-Acting-User to limit signal rows to deals the named member can see. For paged results, follow next_cursor to read more rows. If a cursor is stale, start again from the first page.
Rate limits
Usage limits are described on Usage and limits.Deprecated: Canvas
The Canvas REST surface is deprecated.POST /api/v1/canvas/generate and GET /api/v1/canvas/generate/{runId} still respond, but each response carries a Deprecation: true header and a Link header pointing at the successor route, /api/v1/canvases/{canvasId}/runs. Do not build new integrations on either route. A sunset date will be announced in the changelog.