# 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, then enrich a contact. The worked path is [From companies to leads](/docs/api/from-companies-to-leads). Keys are created under **Connect assistant → API keys**. Credit prices are on [Credits & costs](/docs/api/credits-and-limits). The tools of the Signals MCP server, including `preview_cost` and `max_credits`, are on [MCP](/docs/api-reference/mcp).

## Base URL

All requests go to:

```text
https://mysdr.app/api/v1
```

## Authentication

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

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

Create keys under **Connect assistant → API keys** in mySDR. Keep them secret: never put a key in client-side code or a public repository. Load the key from the environment variable `MYSDR_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 **403** `api_not_enabled` on those routes, with what the key can do instead. 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 and unknown query parameters are rejected with `400` rather than ignored, so a typo never silently drops a filter: the error names the parameter in `param`, says what the endpoint takes, and suggests the name you probably meant.

## Response format

Every response is JSON and carries `mySDR-Api-Version` (`2026-10-04`; `FounderMCP-Api-Version` is a deprecated alias) and `mySDR-Request-Id` (`FounderMCP-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.
- **403** `api_not_enabled` — The key is valid, but the Signals API or the Company API is not enabled for your organization yet. The error says what this key can do.
- **404** `not_found` — The endpoint, or the object you asked for (a search, a row, a campaign), does not exist.
- **405** `method_not_allowed` — The path exists, but not with this HTTP method. The Allow header and the error name the methods it takes.
- **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, the technology data (a company's tech stack, companies using a technology, and finding a technology) and usage answer for every valid key. Company search and enrich, signal, monitor and lead routes answer **403** `api_not_enabled` for a valid key while that API is closed, and **401** when the key is missing. A method a path does not take answers **405** `method_not_allowed` with an `Allow` header, before the key is checked (on `/mcp`: `Allow: POST`); a path that does not exist answers **404**. The pages below document only routes that exist.

### Enrichment

**Company to 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`
- **[Search People](/docs/api-reference/search-people)** — `POST /person/search`
- **[Search Companies](/docs/api-reference/search-companies)** — `POST /company/search`
- **[Look up a company](/docs/api-reference/lookup-company)** — `GET /companies/lookup`
- **[Find Companies Using a Technology](/docs/api-reference/find-companies-using-technology)** — `POST /technologies/companies`
- **[Find Technologies](/docs/api-reference/find-technologies)** — `GET /technologies`

**People enrichment**

- **[Enrich People](/docs/api-reference/enrich-people)** — `POST /person/enrich`
- **[Preview an enrichment](/docs/api-reference/preview-enrich)** — `POST /person/enrich/preview`
- **[Find Phone](/docs/api-reference/find-phone)** — `POST /person/phone`
- **[Reverse Email Lookup](/docs/api-reference/reverse-email-lookup)** — `POST /person/reverse-email`

**Company enrichment**

- **[Enrich Companies](/docs/api-reference/enrich-companies)** — `POST /company/enrich`
- **[Get Company Tech Stack](/docs/api-reference/company-tech-stack)** — `POST /company/tech-stack`

### Signals

- **[Funding rounds](/docs/api-reference/signals/funding-rounds)** — Companies that just raised, and who decides there.
- **[New in a role](/docs/api-reference/signals/new-in-a-role)** — People who just started a job you sell to.
- **[Technology](/docs/api-reference/signals/technology)** — Companies that use or just adopted a tool.
- **[LinkedIn engagement](/docs/api-reference/signals/linkedin-engagement)** — People reacting to a competitor's posts.
- **[Social listening](/docs/api-reference/signals/social-listening)** — People posting about a topic or your brand.
- **[Events](/docs/api-reference/signals/events)** — People posting about a conference.

**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`
- **[List searches](/docs/api-reference/list-searches)** — `GET /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`
- **[Preview a search](/docs/api-reference/preview-search)** — `POST /searches/preview`

**Monitors**

- **[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`

**Webhooks**

- **[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`

**Your own signals**

- **[List your own signals](/docs/api-reference/list-agent-signals)** — `GET /agent-signals`
- **[Register your own signal](/docs/api-reference/save-agent-signal)** — `POST /agent-signals`
- **[Get your own signal](/docs/api-reference/get-agent-signal)** — `GET /agent-signals/{key}`
- **[Update your own signal](/docs/api-reference/update-agent-signal)** — `PATCH /agent-signals/{key}`
- **[Delete your own signal](/docs/api-reference/delete-agent-signal)** — `DELETE /agent-signals/{key}`
- **[Report a check of your own signal](/docs/api-reference/log-signal-hits)** — `POST /agent-signals/{key}/hits`

### Outreach

**A safe layer between your agent and LinkedIn**

- **[Get LinkedIn status](/docs/api-reference/linkedin-status)** — `GET /outreach/linkedin`
- **[Start a LinkedIn sequence](/docs/api-reference/start-linkedin-sequence)** — `POST /outreach/linkedin/sequences`
- **[Get a LinkedIn campaign](/docs/api-reference/get-linkedin-campaign)** — `GET /outreach/linkedin/campaigns/{id}`
- **[List LinkedIn events](/docs/api-reference/list-linkedin-events)** — `GET /outreach/linkedin/events`
- **[Stop a LinkedIn sequence](/docs/api-reference/stop-linkedin-sequence)** — `POST /outreach/linkedin/stop`

**Activity**

- **[Log activity](/docs/api-reference/log-activity)** — `POST /outreach/activity`
- **[List activity](/docs/api-reference/list-activity)** — `GET /outreach/activity`
- **[Check before sending](/docs/api-reference/check-before-sending)** — `POST /outreach/check`

**Campaigns**

- **[List campaigns](/docs/api-reference/list-campaigns)** — `GET /outreach/campaigns`
- **[Create a campaign](/docs/api-reference/create-campaign)** — `POST /outreach/campaigns`

**Exclusions**

- **[List exclusions](/docs/api-reference/list-exclusions)** — `GET /exclusions`
- **[Add exclusions](/docs/api-reference/add-exclusions)** — `POST /exclusions`
- **[Remove an exclusion](/docs/api-reference/remove-exclusion)** — `DELETE /exclusions/{id}`

**Agenda and stages**

- **[Get the agenda](/docs/api-reference/agenda)** — `GET /agenda`
- **[List stages](/docs/api-reference/list-stages)** — `GET /stages`
- **[Set stages](/docs/api-reference/set-stages)** — `POST /stages`
- **[List the team](/docs/api-reference/list-team)** — `GET /team`

**Leads table**

- **[List the Leads table](/docs/api-reference/list-table-leads)** — `GET /tables/leads`
- **[Save people to the Leads table](/docs/api-reference/save-table-leads)** — `POST /tables/leads`
- **[Get one lead](/docs/api-reference/get-table-lead)** — `GET /tables/leads/{id}`
- **[Update a lead](/docs/api-reference/update-table-lead)** — `PATCH /tables/leads/{id}`
- **[Remove a person from the Leads table](/docs/api-reference/remove-table-lead)** — `DELETE /tables/leads/{id}`

**Companies table**

- **[List the Companies table](/docs/api-reference/list-table-companies)** — `GET /tables/companies`
- **[Save companies to the Companies table](/docs/api-reference/save-table-companies)** — `POST /tables/companies`
- **[Get one company](/docs/api-reference/get-table-company)** — `GET /tables/companies/{id}`
- **[Update a company](/docs/api-reference/update-table-company)** — `PATCH /tables/companies/{id}`
- **[Remove a company from the Companies table](/docs/api-reference/remove-table-company)** — `DELETE /tables/companies/{id}`

### MCP and usage

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