# API Introduction

Turn a company into leads your agent can approach. Base URL, authentication, and every endpoint.

The API turns companies into leads an agent can approach: look a company up, read a signal or its context, find the people in the roles you sell to, read why a lead fits, then enrich a contact. The worked path is [From companies to leads](/docs/api/from-companies-to-leads). Keys are created under **API Access → API Keys**. Credit prices are on [Credits & costs](/docs/api/credits-and-limits). The eleven MCP tools, including `preview_cost` and `max_credits`, are on [MCP](/docs/api-reference/mcp).

## Base URL

All requests go to:

```text
https://foundermcp.dev/api/v1
```

## Authentication

Every request must include your API key as a Bearer token in the `Authorization` header:

```bash
--header "Authorization: Bearer $FOUNDERMCP_API_KEY"
```

Create keys under **API Access → API Keys** in FounderMCP. Keep them secret: never put a key in client-side code or a public repository. Load the key from the environment variable `FOUNDERMCP_API_KEY`. A key starts with `gtk_`. A missing, invalid or revoked key is **401** on every route, including while an API is closed. A valid key while the Company API or the Signals API is closed for your organization answers **404** on those routes, the same body as an unknown path. Connecting an assistant is [Connect your assistant](/docs/getting-started/quickstart). The assistant key is created under **Connect assistant → Other → Create assistant key**.

## Request format

Send a JSON body with `Content-Type: application/json`. Field names are `snake_case`. Unknown fields are rejected with `400` rather than ignored, so a typo never silently drops a filter.

## Response format

Every response is JSON and carries `FounderMCP-Api-Version` (`2026-10-04`; `Simba-Api-Version` is a deprecated alias) and `FounderMCP-Request-Id` (`Simba-Request-Id` is a deprecated alias). Paid endpoints add `credits_used` to the body and `X-Credits-Used` and `X-Credits-Charged` headers with the same number. When the wallet can be read they also send `X-Credits-Remaining`. `GET /usage` adds `balance` and `today.credits_remaining`.

## Error responses

Every error has the same shape. Branch on `error.type`; the message is meant for people and can change.

```json
{
  "error": {
    "type": "invalid_request",
    "message": "`page` must be a whole number from 1 to 100."
  }
}
```

Errors never cost credits.

### HTTP status codes

- **400** `invalid_request` — The body is not valid JSON, a field is unknown or has the wrong type, or a value is not allowed.
- **401** `authentication_error` — The Authorization header is missing, or the key is unknown or revoked.
- **403** `permission_error` — API access is not part of your plan, or your account is suspended.
- **404** `not_found` — The endpoint does not exist.
- **429** `rate_limit_error` — More than 60 requests per minute, or more than 3 at the same time, on one key. Wait for the Retry-After header.
- **429** `daily_limit_reached` — The request could take your organization over its daily credit limit. The limit resets at midnight (Europe/Brussels).
- **402** `insufficient_credits` — The credit balance is lower than this request could cost. Nothing was charged. Add credits, or send a smaller request. The error includes code, fix and a link to the credits docs.
- **502** `upstream_error` — The data source did not answer. Retry later.
- **503** `service_unavailable` — The API is temporarily unavailable. Retry later.
- **500** `internal_error` — Something went wrong on our side.

## Rate limits

- 60 requests per minute and 3 concurrent requests per key.
- A daily credit limit per organization — 1,000 credits unless agreed otherwise — that resets at midnight Europe/Brussels.

Both answer with `429` and a `Retry-After` header. Prices are on [Credits & costs](/docs/api/credits-and-limits).

## Endpoints

People search, people enrich and usage answer for every valid key. Company, signal, watch, monitor and lead routes answer **404** for a valid key while that API is closed, and **401** when the key is missing. `GET` and `DELETE` on `/mcp` answer **405** with `Allow: POST`, before the key is checked and while the API is closed. The pages below document only routes that exist.

### Companies

- **[Look up a company](/docs/api-reference/lookup-company)** — `GET /companies/lookup`
- **[Search Companies](/docs/api-reference/search-companies)** — `POST /company/search`
- **[Enrich Companies](/docs/api-reference/enrich-companies)** — `POST /company/enrich`

### Signals & searches

- **[List signal types](/docs/api-reference/list-signal-types)** — `GET /signals`
- **[Get a signal type](/docs/api-reference/get-signal-type)** — `GET /signals/{signal_type}`
- **[Start a search](/docs/api-reference/start-search)** — `POST /searches`
- **[Get a search](/docs/api-reference/get-search)** — `GET /searches/{search_id}`
- **[List search results](/docs/api-reference/search-results)** — `GET /searches/{search_id}/results`
- **[Cancel a search](/docs/api-reference/cancel-search)** — `POST /searches/{search_id}/cancel`
- **[Resolve a search](/docs/api-reference/resolve-search)** — `POST /searches/{search_id}/resolve`
- **[Preview a search](/docs/api-reference/preview-search)** — `POST /searches/preview`
- **[Create a watch](/docs/api-reference/create-watch)** — `POST /watches`
- **[List watches](/docs/api-reference/list-watches)** — `GET /watches`
- **[Get a watch](/docs/api-reference/get-watch)** — `GET /watches/{watch_id}`
- **[Update a watch](/docs/api-reference/update-watch)** — `PATCH /watches/{watch_id}`
- **[Delete a watch](/docs/api-reference/delete-watch)** — `DELETE /watches/{watch_id}`
- **[List the leads of a watch](/docs/api-reference/watch-leads)** — `GET /watches/{watch_id}/leads`
- **[Create a monitor](/docs/api-reference/create-monitor)** — `POST /monitors`
- **[List monitors](/docs/api-reference/list-monitors)** — `GET /monitors`
- **[Get a monitor](/docs/api-reference/get-monitor)** — `GET /monitors/{monitor_id}`
- **[Update a monitor](/docs/api-reference/update-monitor)** — `PATCH /monitors/{monitor_id}`
- **[Delete a monitor](/docs/api-reference/delete-monitor)** — `DELETE /monitors/{monitor_id}`
- **[Preview a monitor](/docs/api-reference/preview-monitor)** — `POST /monitors/preview`
- **[List mentions](/docs/api-reference/list-mentions)** — `GET /mentions`
- **[Create a webhook endpoint](/docs/api-reference/create-webhook)** — `POST /webhook_endpoints`
- **[List webhook endpoints](/docs/api-reference/list-webhooks)** — `GET /webhook_endpoints`
- **[Get a webhook endpoint](/docs/api-reference/get-webhook)** — `GET /webhook_endpoints/{webhook_endpoint_id}`
- **[Delete a webhook endpoint](/docs/api-reference/delete-webhook)** — `DELETE /webhook_endpoints/{webhook_endpoint_id}`
- **[Test a webhook endpoint](/docs/api-reference/test-webhook)** — `POST /webhook_endpoints/{webhook_endpoint_id}/test`

### Leads

- **[Find people at companies](/docs/api-reference/find-company-leads)** — `POST /leads`
- **[Preview company leads](/docs/api-reference/preview-company-leads)** — `POST /leads/preview`
- **[List the leads of a search](/docs/api-reference/search-leads)** — `GET /searches/{search_id}/leads`
- **[Explain a lead](/docs/api-reference/explain-lead)** — `GET /leads/{lead_id}`
- **[Search People](/docs/api-reference/search-people)** — `POST /person/search`
- **[Enrich People](/docs/api-reference/enrich-people)** — `POST /person/enrich`
- **[Preview an enrichment](/docs/api-reference/preview-enrich)** — `POST /person/enrich/preview`

### MCP

- **[MCP](/docs/api-reference/mcp)** — `POST /mcp`

### Account

- **[Get Usage](/docs/api-reference/usage)** — `GET /usage`