> ## Documentation Index
> Fetch the complete documentation index at: https://docs.freshtalent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Search the talent graph, manage pipelines, and integrate monitoring events into your systems.

FreshTalent's REST API lets you find people, organize them into Lists, run Targets, and consume profile-change events. Start with [Build your first integration](/guides/first-integration) for a complete search → List → events workflow.

## Base URL and authentication

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://api.freshtalent.ai/v1
```

Send a server-side API key in `Authorization: Bearer YOUR_API_KEY`. `X-Api-Key` is also accepted; send only one authentication method. Organization-owned resources are scoped to the key's organization. Most data endpoints also require active organization access; [Get account](/api-reference/account/me) reports access and quotas.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export FRESHTALENT_API_KEY='YOUR_API_KEY'
curl --fail-with-body --max-time 30 --fail-with-body "https://api.freshtalent.ai/v1/me" \
  -H "Authorization: Bearer $FRESHTALENT_API_KEY"
```

Use `Content-Type: application/json` for JSON request bodies. Keep keys out of browser bundles, URLs, logs, and source control. See [Authentication](/authentication).

## Requests and responses

Endpoint pages define their exact request and response shapes. Most successful reads return `data`; collection endpoints may add `meta`. A successful delete returns `204` with **no body**, so do not call `response.json()` on it.

People search also returns the effective structured `query`. For example, an empty result can look like this:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [],
  "query": { "company": "palantir", "role_family": "forward-deployed-engineer" },
  "meta": { "count": 0, "limit": 25, "offset": 0, "has_more": false, "total": 0 }
}
```

Persist that query with [Save query](/api-reference/queries/save) and reuse it on people search. Target discovery uses a different schema and is not an exact replay of the graph search. See [Search query compatibility](/api-reference/targets/create#search-query-compatibility). Neither Target `app_query` nor its provider-oriented `query` accepts the echoed graph-search object unchanged.

* **Full versus compact:** people search defaults to `view=full`. `view=compact` changes field names and structure, not just payload size. See [Person response shapes](/api-reference/people/schema).
* **Null versus omitted:** `null` means a field has no value; optional fields can be absent. Neither implies `false`, zero, or an empty string. Tolerate additional response fields.
* **Identifiers:** person routes use a LinkedIn slug. Lists resolve by UUID or case-insensitive name; use the returned UUID after resolution. Targets use UUIDs. URL-encode path values.
* **Pagination:** follow the contract on each endpoint. People search uses offsets; events use older-page cursors. Not every collection is paginated, and counts are not interchangeable with totals.
* **Examples:** cURL, JavaScript, and Python snippets are direct HTTP calls, not SDKs. Set `FRESHTALENT_API_KEY`; replace sample identifiers with values returned by your account. JavaScript examples use Node.js 22+; Python examples use the standard library.

## Errors, limits, and safe retries

Branch on HTTP status first. Application errors usually return `{ "error": { "type": "…", "message": "…" } }`, while framework validation and rate limiting can return `{ "statusCode": 429, "error": "Too Many Requests", "message": "…" }`.

* The Gateway currently allows **300 requests per minute per client IP as it sees it**, not per key. See [Rate limits and quotas](/rate-limits).
* Retry transient read failures with bounded backoff and jitter. Honor `Retry-After` on `429`.
* A timed-out mutation may already have succeeded. Reconcile the resource before replaying it; repeated List-member writes can overwrite stage and notes.
* Event polling needs overlap windows and event-ID deduplication. A page cursor is not the checkpoint for the next poll.

See [Errors](/errors) for handling both error shapes and [List events](/api-reference/events/list) for the polling contract.

## Endpoint map

### Account and discovery

| Method | Path               | Operation                                           |
| ------ | ------------------ | --------------------------------------------------- |
| `GET`  | `/me`              | [Get account](/api-reference/account/me)            |
| `GET`  | `/people`          | [Search people](/api-reference/people/search)       |
| `GET`  | `/people/{slug}`   | [Get person](/api-reference/people/get)             |
| `GET`  | `/companies`       | [Search companies](/api-reference/companies/search) |
| `GET`  | `/companies/{key}` | [Get company orbit](/api-reference/companies/orbit) |

### Lists and saved queries

| Method   | Path                                 | Operation                                                |
| -------- | ------------------------------------ | -------------------------------------------------------- |
| `GET`    | `/lists`                             | [List lists](/api-reference/lists/list)                  |
| `POST`   | `/lists`                             | [Create list](/api-reference/lists/create)               |
| `GET`    | `/lists/{id}`                        | [Get list](/api-reference/lists/get)                     |
| `DELETE` | `/lists/{id}`                        | [Delete list](/api-reference/lists/delete)               |
| `POST`   | `/lists/{id}/members`                | [Add list members](/api-reference/lists/add-members)     |
| `PATCH`  | `/lists/{id}/members/{membershipId}` | [Update list member](/api-reference/lists/update-member) |
| `GET`    | `/queries`                           | [List saved queries](/api-reference/queries/list)        |
| `POST`   | `/queries`                           | [Save query](/api-reference/queries/save)                |
| `GET`    | `/queries/{id}`                      | [Get saved query](/api-reference/queries/get)            |

### Targets, events, and notifications

| Method   | Path                    | Operation                                                                    |
| -------- | ----------------------- | ---------------------------------------------------------------------------- |
| `GET`    | `/targets`              | [List targets](/api-reference/targets/list)                                  |
| `POST`   | `/targets`              | [Create target](/api-reference/targets/create)                               |
| `GET`    | `/targets/{id}`         | [Get target](/api-reference/targets/get)                                     |
| `PATCH`  | `/targets/{id}`         | [Update target](/api-reference/targets/update)                               |
| `DELETE` | `/targets/{id}`         | [Delete target](/api-reference/targets/delete)                               |
| `POST`   | `/targets/{id}/retry`   | [Retry target](/api-reference/targets/retry)                                 |
| `GET`    | `/targets/{id}/members` | [List target members](/api-reference/targets/members)                        |
| `POST`   | `/targets/{id}/members` | [Accept target members](/api-reference/targets/admit)                        |
| `GET`    | `/events`               | [List events](/api-reference/events/list)                                    |
| `GET`    | `/signals/preferences`  | [Get notification preferences](/api-reference/signals/get-preferences)       |
| `PUT`    | `/signals/preferences`  | [Update notification preferences](/api-reference/signals/update-preferences) |
| `POST`   | `/signals/test`         | [Send test digest](/api-reference/signals/test)                              |

This map covers the operations documented in this reference, not every dashboard route. In particular, the dashboard's `/monitoring` and filtered `/signals` feeds are not interchangeable with the integration event stream.

## Other integration surfaces

* [MCP](/mcp-setup): connect compatible assistants at `https://api.freshtalent.ai/mcp`.
* [ATS and CRM architecture](/connect/ats-crm): turn events into idempotent downstream updates.
* Machine-readable product guidance: `https://freshtalent.ai/llms.txt`.