FounderMCPDocs

API reference

API Introduction

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

View Markdown

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. Keys are created under API Access → API Keys. Credit prices are on Credits & costs. The eleven MCP tools, including preview_cost and max_credits, are on MCP.

Base URL

All requests go to:

https://foundermcp.dev/api/v1

Authentication

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

--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. The assistant key is created under Connect your assistant → 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.

{
  "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.

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

Signals & searches

Leads

MCP

  • MCP — POST /mcp

Account