# Talent-Ray API

> Programmatic access to the Talent-Ray hiring platform. Authenticate with an API key and call platform endpoints. This file links to the agent-optimized Markdown version of every documentation page.

## Instructions for LLM agents

- The base URL is the customer's Talent-Ray instance. The shared platform is `https://app.talent-ray.com`; customers with a dedicated deployment use their own subdomain (e.g. `https://acme.talent-ray.com`). API paths and contracts are identical across instances — only the host changes.
- Authenticate with the header `Authorization: Bearer tr_...`. The `x-api-key: tr_...` header is an accepted fallback. Never send the key as a URL query parameter.
- API keys are **owner-scoped**: a key can never exceed the role/org access of the user it was minted for (its ceiling). Keys may *additionally* carry **per-key scopes** that gate the `/api/v1/*` endpoints. A scope only narrows access; it never grants anything the owner lacks. A key with no scopes authenticates but cannot call scope-gated `/api/v1` endpoints.
- Scope names are `resource:action`, e.g. `candidates:read`, `candidates:write`, `roles:read`, `tests:read`, `sourcing:write`, `pipeline:read`, `cv-screening:read`. A missing scope returns `403` with `error: "insufficient_scope"` and `requiredScopes`/`grantedScopes` arrays — read those to self-correct. Do not invent scopes outside the documented taxonomy.
- The `/api/v1/*` endpoints return **stable, curated** response shapes: lists use a `{ data, pagination }` envelope; single resources return a curated object. Changes are additive only.
- On HTTP `429`, honor the `Retry-After` response header and back off. The default limit is 600 requests per minute per key.
- All timestamps are ISO 8601 in UTC. Page `/api/v1` lists with `page` (0-indexed) + `pageSize` (max 100); API-key usage logs paginate cursor-based via `before`/`nextBefore`.
- Only the endpoints listed below are documented. Do not call undocumented internal routes.
- The machine-readable OpenAPI 3.1 spec covers every documented endpoint — API keys, career portal, and the full `/api/v1` Hiring Pipeline surface: https://www.talent-ray.com/docs/api/openapi.json. Each operation's required scope is in its description and the `x-required-scopes` extension.
- The full documentation as a single Markdown file: https://www.talent-ray.com/llms-full.txt

## Documentation

### Overview
- [Talent-Ray API](https://www.talent-ray.com/docs/api/index.md): Programmatic access to the Talent-Ray hiring platform for backend systems and AI agents.

### Authentication
- [Authentication](https://www.talent-ray.com/docs/api/authentication.md): Authenticate every request with a Talent-Ray API key.

### Conventions
- [Conventions](https://www.talent-ray.com/docs/api/conventions.md): Base URL, rate limits, pagination, and timestamp formats shared across all endpoints.

### Endpoints
- [Create an API key](https://www.talent-ray.com/docs/api/endpoints/create-api-key.md): Mint a new API key on behalf of a user — for example, to set up a SAP or HRIS integration.
- [List API keys](https://www.talent-ray.com/docs/api/endpoints/list-api-keys.md): Retrieve all API keys with their owner and usage metadata.
- [Get API key usage](https://www.talent-ray.com/docs/api/endpoints/get-api-key-usage.md): Read a cursor-paginated forensic log of requests made with a key — useful for audits.
- [Revoke an API key](https://www.talent-ray.com/docs/api/endpoints/revoke-api-key.md): Permanently revoke a key so it can no longer authenticate requests.
- [Get a career portal](https://www.talent-ray.com/docs/api/endpoints/get-career-portal.md): List an organization's public career portal — branding and all open roles. No authentication.
- [Get a public job](https://www.talent-ray.com/docs/api/endpoints/get-job.md): Fetch a single open, public role with its organization metadata. No authentication.
- [Apply to a public job](https://www.talent-ray.com/docs/api/endpoints/apply-to-job.md): Generate a candidate signup invite link for a public role. No authentication.
- [Get the authenticated principal](https://www.talent-ray.com/docs/api/endpoints/get-me.md): Resolve the current user and, for API-key callers, the key id and its granted scopes.

### Hiring Pipeline
- [List candidates](https://www.talent-ray.com/docs/api/pipeline/candidates-list.md): Page through candidates in a stable, curated shape. Scope: candidates:read.
- [Get a candidate](https://www.talent-ray.com/docs/api/pipeline/candidates-get.md): Fetch one candidate in the curated v1 shape. Scope: candidates:read.
- [Update a candidate](https://www.talent-ray.com/docs/api/pipeline/candidates-update.md): Update a curated set of candidate fields. Scope: candidates:write.
- [Get a candidate's pipeline progress](https://www.talent-ray.com/docs/api/pipeline/candidate-steps.md): A candidate's step progress across all their roles. Scope: pipeline:read.
- [List roles](https://www.talent-ray.com/docs/api/pipeline/roles-list.md): Page through roles (jobs) in a stable, curated shape. Scope: roles:read.
- [Get a role](https://www.talent-ray.com/docs/api/pipeline/roles-get.md): Fetch one role in the curated v1 shape. Scope: roles:read.
- [Update a role](https://www.talent-ray.com/docs/api/pipeline/roles-update.md): Update a curated set of role fields. Scope: roles:write.
- [Get a role's pipeline template](https://www.talent-ray.com/docs/api/pipeline/role-steps.md): A role's ordered pipeline steps (the template). Scope: pipeline:read.
- [List tests](https://www.talent-ray.com/docs/api/pipeline/tests-list.md): Page through assessment tests in a stable, curated shape. Scope: tests:read.
- [Get a test](https://www.talent-ray.com/docs/api/pipeline/tests-get.md): Fetch one test's metadata in the curated v1 shape. Scope: tests:read.
- [Update a test](https://www.talent-ray.com/docs/api/pipeline/tests-update.md): Update a curated set of test metadata fields. Scope: tests:write.
- [List potential candidates](https://www.talent-ray.com/docs/api/pipeline/sourcing-list.md): Page through sourced/CV-screened leads. Scope: sourcing:read.
- [Create a potential candidate](https://www.talent-ray.com/docs/api/pipeline/sourcing-create.md): Create a sourced lead in an organization. Scope: sourcing:write.
- [Get a potential candidate](https://www.talent-ray.com/docs/api/pipeline/sourcing-get.md): Fetch one sourced lead in the curated v1 shape. Scope: sourcing:read.
- [Update a potential candidate](https://www.talent-ray.com/docs/api/pipeline/sourcing-update.md): Update a curated set of lead fields. Scope: sourcing:write.
- [Delete a potential candidate](https://www.talent-ray.com/docs/api/pipeline/sourcing-delete.md): Permanently delete a sourced lead. Scope: sourcing:write.
- [Get a CV-screening batch](https://www.talent-ray.com/docs/api/pipeline/cv-screening-batch.md): Batch processing status plus per-member screening results. Scope: cv-screening:read.

### Reference
- [Errors](https://www.talent-ray.com/docs/api/errors.md): Error response format and the status codes the API returns.