Skip to main content

Talent-Ray API

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

View as Markdown OpenAPI spec

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.

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.

How it works

  1. An administrator mints an API key for a specific user (see 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.

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.

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. Each operation lists its required scope (in its description and an x-required-scopes extension).
  • Machine index: /llms.txt — a curated map of every page with behavioral instructions
  • Full docs in one file: /llms-full.txt
  • Any page as Markdown: append .md to its URL (e.g. /docs/api/authentication.md)

Endpoint groups

  • Endpoints — API-key management, the public career portal, and the /api/v1/me identity check. Stable.
  • Hiring Pipeline — 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 — how API keys work and how to send them
  • Conventions — base URL, rate limits, pagination, timestamps
  • Errors — error format and status codes