Retriever API

The Retriever API gives you programmatic access to the prospecting agent: you send a prompt, Retriever sources, enriches, and qualifies companies or contacts, then you read or export the resulting table.

Quickstart

Your first authenticated call and a real company list in 5 minutes.

MCP

Connect Claude, ChatGPT, Cursor, or Codex through the hosted MCP server at /mcp.

API reference

Every endpoint, its parameters, responses, and errors.

Recipes

Enrich a CRM list, sync exclusions, manage multiple clients.

Errors

Standard format, stable codes, and what to do next.

Base URL

Environment	Base URL
Production	`https://api.retriever.run`
Local	`http://localhost:4320`

Authentication

Every request sends an API key in the Authorization header:

Authorization: Bearer ret_live_xxxxxxxxxxxxxxxx

Create the key in the app: Settings → API keys → Create API key. It is shown only once.
The key acts on behalf of its creator, in the organization the creator belongs to at the time of each request (read Multi-client before using keys for several clients). It can access workspaces, tables, and runs of that organization. Exclusion lists and the credit balance are shared by the organization.

Keep the key on your server. Never put it in a browser, mobile app, or Git repository.

What the API covers

Area	Role
Runs	Hand a prompt to the agent and retrieve its tables or a fixed-format output.
Tables	Read live workspace tables, row by row.
Workspaces	Create workspaces and import your own lists.
Exclusions	Sync companies and people you never want sourced.
Go	One question, one answer in your JSON Schema. The Go agent searches the web and can call every Retriever service (LinkedIn, Sales Navigator, company data, emails, phones).
Services	Call atomic services directly (search, scraping, email…).
MCP	Same API through MCP tools (`POST /mcp`) for host agents — see MCP.

Runs, Go or Services?

You want	Use	Why
A list of companies or people, with columns, sources and qualification	Runs	The agent builds tables in a workspace. You can read them in the app and refine them in the same conversation.
One precise answer in a fixed format, with no table (a funding round, the decision makers of one company with their LinkedIn and email)	Go	The Go agent chooses and chains the searches and services itself. It returns only the answer, and adds nothing to a workspace. Your exclusion list does not apply to Go.
One known operation (find an email, search people on LinkedIn, scrape a page)	Services	You call that service directly and read its raw result.

A run can also return a fixed format (output), but it is heavier: use it when you also want the table. A Go job starts from zero every time: to build on an earlier result, use a run and continue its conversation.

Conventions

/v1/* routes are versioned. /services and /credits do not use a /v1 prefix.
POST requests with a body send Content-Type: application/json.
JSON fields use snake_case, except GET /credits (remainingCredits).
Links returned in links are relative to the base URL and require the same key. Exception: links.app is an absolute URL of the Retriever app and requires a signed-in session, not the key.
API error messages are in English. Wire your code to error.code, never to message.

Get started

Model Context Protocol

Concepts

Recipes

Quickstart

MCP

API reference

Recipes

Errors

Base URL

Authentication

What the API covers

Runs, Go or Services?

Conventions

Quickstart

MCP

API reference

Recipes

Errors

​Base URL

​Authentication

​What the API covers

​Runs, Go or Services?

​Conventions

Base URL

Authentication

What the API covers

Runs, Go or Services?

Conventions