> ## Documentation Index
> Fetch the complete documentation index at: https://docs.findtempo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> Programmatic access to Deal Brain over HTTP, for integrations that aren't AI agents.

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](/integrations/mcp) is the better fit — it exposes a broader capability surface, including Signals, Agents, Playbook, and Canvas configuration. See [which surface to use](/developers).

## Base URL

```text theme={null}
https://findtempo.co/api/v1
```

## Authentication

Every request needs an API key sent as a Bearer token:

```bash theme={null}
curl https://findtempo.co/api/v1/deals \
  -H "Authorization: Bearer YOUR_API_KEY"
```

<Warning>
  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.
</Warning>

### 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

### 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:

<Steps>
  <Step title="Create a second key">
    Create a new key on the **API Keys** page and copy its secret.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  **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](/support) — swapping your integrations to a new key does not contain the exposure on its own.
</Warning>

### 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:

| Request                  | Runs as           | Sees                                              |
| ------------------------ | ----------------- | ------------------------------------------------- |
| Key alone                | Your organization | Org-wide surfaces — your organization's full book |
| Key plus `X-Acting-User` | The named member  | What that member can see                          |

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:

```bash theme={null}
curl -X POST https://findtempo.co/api/v1/canvas/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Acting-User: rep@acme.com" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

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

<CardGroup cols={2}>
  <Card title="Read" icon="list">
    Deals, deal state, action items, meetings, sales process, and session context.
  </Card>

  <Card title="Query" icon="magnifying-glass">
    Describe entities, then filter, aggregate, and fetch across them with a typed field catalog.
  </Card>

  <Card title="Agentic search" icon="brain">
    Natural-language questions answered over deal memory.
  </Card>

  <Card title="Canvas generation" icon="file-lines">
    Render a [Canvas](/canvas) template as an async job, then poll for the result.
  </Card>
</CardGroup>

## 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**:

<Steps>
  <Step title="Discover what you can query">
    `GET /api/v1/query/describe` returns every queryable entity and the users you can scope to.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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.