# Endpoints

The synchronous endpoint surface - Search, Enrich, and Lookalike - plus the async Agents door, and how the verbs chain into one motion

Amdahl's public API is a small set of **endpoints**: synchronous primitives that answer in one blocking call, plus the async **Agents** door for anything that needs a real investigation. Reach for an endpoint when you already know the shape of the answer — a filtered slice, a similarity ranking, a brief on one subject — and for [Chat](chat.md) when you want Amdahl to figure out the shape for you.

- **[Search](endpoints/search.md)** — `search.query`, one routed door over your warehouse with a typed-filter lane, an NL→SQL lane, and a meaning-based semantic lane, plus the `search.fields` vocabulary catalog. (The plain-language fast lane, `search.run`, has [its own guide](search.md).)
- **[Enrich](endpoints/enrich.md)** — `enrich.company` / `enrich.person` / `enrich.topic`, tiered: a cached brief instantly, your own first-party evidence on a miss while the full fused brief rebuilds in the background, or `mode: "full"` to block for the deep version.
- **[Lookalike](endpoints/lookalike.md)** — `lookalike.find` + `lookalike.similar_themes`, "more like this one" over your own conversation corpus, honest about coverage while centroids materialize.
- **Agents** — the async surface: the [Chat](chat.md) ask-door, the reusable [agent library](agents.md), and cron [Routines](routines.md).

## Every endpoint at a glance

| Endpoint | Operation | REST | MCP tool + action | Scope | Stability | Typical latency |
| --- | --- | --- | --- | --- | --- | --- |
| Fast NL search | `search.run` | `POST /search` | `search` → `run` | `data:read` | beta | ~6s |
| Routed search | `search.query` | `POST /search/query` | `search` → `query` | `data:read` | beta | ~2s |
| Field catalog | `search.fields` | `GET /search/fields` | `search` → `fields` | `data:read` | beta | sub-second |
| Enrich a company | `enrich.company` | `POST /enrich/company` | `enrich` → `company` | `data:read` (¹) | beta | ~2s fast path |
| Enrich a person | `enrich.person` | `POST /enrich/person` | `enrich` → `person` | `data:read` (¹) | beta | ~2s fast path |
| Enrich a topic | `enrich.topic` | `POST /enrich/topic` | `enrich` → `topic` | `data:read` (¹) | beta | ~2s fast path |
| Nearest entities | `lookalike.find` | `POST /lookalike` | `lookalike` → `find` | `data:read` | beta | ~1s |
| Nearest themes | `lookalike.similar_themes` | `POST /lookalike/themes` | `lookalike` → `themes` | `data:read` | beta | ~2s |
| Score against ground truth | `evals.run` | `POST /evals` | `evals` → `run` | `data:read` | [coming soon](endpoints/evals.mdx) | — |
| What-if projection | `simulate.run` | `POST /simulate` | `simulate` → `run` | `data:read` | [coming soon](endpoints/simulate.mdx) | — |
| Start a Chat | `chat.start` | `POST /chat` | `agents` → `start_chat` | `conversations:write` | stable | async (handles now) |
| Agent library CRUD | `agents.*_agent` | `/agents[...]` | `agents` → `*_agent` | `agents:read` / `agents:write` | stable | sub-second |
| Routines CRUD + fire | `routines.*` | `/routines[...]` | `agents` → `*_routine` | `routines:read` / `routines:write` | stable | sub-second |

(¹) The paid enrich tiers — the background refresh and `mode: "full"` — additionally need `external_search:execute`, and **degrade instead of failing** without it (`refresh_omitted: "missing_scope"`).

The **eval** and **simulate** endpoints are not live yet: their pages document the planned shapes so you can design against them, and they are deliberately absent from the OpenAPI spec and tool catalog until launch.

Every synchronous endpoint shares the same contract style: past parameter validation it returns `success: true` with typed fields for every degradation (a missing scope, an unmaterialized index, an empty corpus) — partial and honest beats a 500. The only non-2xx you should plan for are the [gate codes](api-reference/errors.md): `feature_disabled`, `not_on_public_api`, and `quota_exceeded`.

## How the endpoints chain

Each endpoint is one blocking call, which makes them composable — the canonical chain is the **expansion motion**:

```
1. structured search   POST /search/query      "closed-won deals this year, largest first"
        │                                       → real pipeline company ids
        ▼
2. lookalike           POST /lookalike          seed = your best closed-won company
        │                                       → the accounts that TALK like it
        ▼
3. enrich              POST /enrich/company     one fast tiered call per match
        │                                       → cached brief or first-party evidence now,
        │                                         deep briefs rebuilding behind you
        ▼
4. semantic search     POST /search/query       mode=semantic + company_id IN (matches)
                                                → the objections those accounts already raised
```

Four synchronous calls, no agent run — a briefed expansion list with the evidence attached. When a step's answer needs judgment rather than retrieval ("which of these should we actually pursue and why"), hand the thread to [Chat](chat.md): the async lane exists precisely for the asks the endpoints cannot settle in one call.

Two more chains worth knowing:

- **Discovery-first search**: `GET /search/fields` → compose typed filters → `POST /search/query`. The catalog is derived from the same schema the compiler validates against, so it cannot drift — and a wrong field name comes back as a typed `invalid_argument` naming the allowed set.
- **Warm-the-cache enrichment**: fast-enrich tomorrow's accounts this afternoon; each cache miss queues a background refresh (`refresh_enqueued: true`), so by meeting time the same calls land on `tier: "cached"`.

## Prerequisites

### Your workspace must be on Agent Platform v2

Everything on this page is gated **per workspace** by the `agent_v2` flag:

- **On REST:** a gated call on a flag-off workspace returns `403` with `error.code: "feature_disabled"`.
- **On MCP:** if your connected session lists a `search` tool and an `agents` tool (the newest surface also carries `enrich` + `lookalike`), you are on v2. If it still lists `blueprints` / `pages` and no `search` / `agents`, ask your Amdahl admin to enable Agent Platform v2 for the workspace.

### An API key with the right scopes

Mint a key in the console (**Settings → Developer**, see [Authentication](authentication.md)) and send it as `X-API-Key` on every request. The base URL is:

```
https://app.amdahl.co/api/platform/v1
```

Per family:

| Family | Scope |
| --- | --- |
| `search.run` / `search.query` / `search.fields` | `data:read` |
| `enrich.*` | `data:read` (+ `external_search:execute` for the paid tiers; degrades without it) |
| `lookalike.*` | `data:read` |
| Start / rename a Chat | `conversations:write` |
| Read a Chat / poll a run | `conversations:read` |
| Answer a pause / cancel a run | `workflows:write` |
| Agent library read / write | `agents:read` / `agents:write` |
| Routines read / write | `routines:read` / `routines:write` |

A read-only key can call every synchronous endpoint on this page (enrich serves its cache + first-party tiers and reports `refresh_omitted: "missing_scope"` instead of queueing the paid refresh) and read Chats — but cannot start a Chat, answer a pause, or write an agent or routine.

## See also

- [Search — the routed endpoint](endpoints/search.md), [Enrich](endpoints/enrich.md), [Lookalike](endpoints/lookalike.md) — the per-endpoint guides.
- [Evals](endpoints/evals.mdx) and [Simulate](endpoints/simulate.mdx) — the coming-soon endpoints, documented ahead of launch.
- [Search (fast lane)](search.md) and [Chat](chat.md) — the two "ask Amdahl" doors.
- [Tool catalog](api-reference/tool-catalog.md) — the generated per-operation reference.