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 when you want Amdahl to figure out the shape for you.

Search — 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.)
Enrich — 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 — 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 ask-door, the reusable agent library, and cron Routines.

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	—
What-if projection	`simulate.run`	`POST /simulate`	`simulate` → `run`	`data:read`	coming soon	—
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: 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:

code

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: 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) and send it as X-API-Key on every request. The base URL is: