# Talent-Ray API

Programmatic access to the Talent-Ray hiring platform for backend systems and AI agents.

The Talent-Ray API lets backend systems and AI agents authenticate with an **API key** and call platform endpoints over HTTPS. It powers integrations such as syncing hires into an HRIS, auditing key usage, and automating recruiting workflows.

## Base URL

The base URL is **your Talent-Ray instance**:

```
https://app.talent-ray.com
```

`app.talent-ray.com` is the **shared platform**. Customers with a **dedicated deployment** call their own subdomain instead — for example `https://acme.talent-ray.com`. The API paths and contracts are identical on every instance; only the host changes.

<Notice type="info" title="Which host do I use?">
If you sign in at `app.talent-ray.com`, use that host. If your team has a dedicated Talent-Ray instance, use the same subdomain you sign in with. The examples in these docs use `app` — replace it with your subdomain if you have a dedicated deployment.
</Notice>

## How it works

1. An administrator mints an **API key** for a specific user (see [Authentication](/docs/api/authentication/)).
2. You send that key on every request via the `Authorization: Bearer` header.
3. The key acts as its owner — it has exactly that user's role and organization access.

<Notice type="info" title="Owner-scoped keys, plus per-key scopes">
An API key can never exceed the permissions of the user it was minted for — that's its ceiling. A key may *additionally* be granted **per-key scopes** (e.g. `candidates:read`) that gate the versioned `/api/v1/*` endpoints. A scope only narrows access; it never grants anything the owner lacks. See [Authentication](/docs/api/authentication/#scopes).
</Notice>

## For AI agents

This documentation is built to be consumed by AI agents:

- **OpenAPI 3.1 spec** (every documented endpoint — API keys, career portal, and the full `/api/v1` Hiring Pipeline surface): [`/docs/api/openapi.json`](/docs/api/openapi.json). Each operation lists its required scope (in its description and an `x-required-scopes` extension).
- **Machine index:** [`/llms.txt`](/llms.txt) — a curated map of every page with behavioral instructions
- **Full docs in one file:** [`/llms-full.txt`](/llms-full.txt)
- **Any page as Markdown:** append `.md` to its URL (e.g. `/docs/api/authentication.md`)

## Endpoint groups

- **[Endpoints](/docs/api/endpoints/create-api-key/)** — API-key management, the public career portal, and the `/api/v1/me` identity check. Stable.
- **[Hiring Pipeline](/docs/api/pipeline/candidates-list/)** — the stable, scoped `/api/v1` surface: candidates, roles, tests, sourcing, pipeline steps, and CV-screening batches. Each endpoint requires a specific scope (e.g. `candidates:read`) and returns a curated, versioned shape.

## Next steps

- [Authentication](/docs/api/authentication/) — how API keys work and how to send them
- [Conventions](/docs/api/conventions/) — base URL, rate limits, pagination, timestamps
- [Errors](/docs/api/errors/) — error format and status codes