Authentication

All /api/v1/* requests require a workspace API key in the Authorization header.

Authorization: Bearer cs_live_<your-key>
Content-Type: application/json

Where to get a key

Step	Detail
Prerequisite	Be an approved employer on Cutshort (see Introduction)
In the product	Settings → Integrations → API Key
Generate	Choose Eval access or Production access, then click Generate API key

When generating a key you choose:

Option	Availability	Scopes
Eval access (limited quotas)	All approved employers	`search:read`, `candidates:read`, `applications:read`, `jobs:read`
Production access (all scopes)	Workspace has production API enabled	Adds job posting (`jobs:write`) and candidate messaging (`messages:write`), with higher quotas

Production self-serve requires Cutshort to enable access on your workspace. Email hello@cutshort.io to request it.

Key properties

Property	Value
Prefix	`cs_live_`
Scope	One workspace
Storage	Treat like a password — do not commit to git or share in chat logs

Keys minted in Settings → Integrations can be Revealed again later from the same page. Keys provisioned externally by Cutshort may not support Reveal — use the copy you received at creation.

Scopes

Each key carries a set of scopes that control which endpoints it can call. If a key lacks a scope, the API returns 403 with error_code: insufficient_scope.

Endpoint	Scope
`GET /search/candidates`	`search:read` (eval + production)
`GET /candidates/{talentCardId}`	`candidates:read` (eval + production; auto-unlock is metered by the workspace unlock quota)
`GET /jobs`	`jobs:read` (eval + production)
`GET /jobs/{jobId}/stages`	`jobs:read` (eval + production)
`POST /jobs`	`jobs:write` (production keys)
`POST /invite-to-apply`	`messages:write` (production keys)
`POST /messages`	`messages:write` (production keys)
`POST /applications/{id}/move-stage`	`stages:write` (production keys)
`GET /usage`	Any valid key

Errors

HTTP	`error_code`	Meaning
401	`invalid_api_key`	Missing, malformed, revoked, or unknown key
403	`insufficient_scope`	Key cannot call this endpoint
403	`approved_employer_required`	Only approved employers can manage keys in Settings
403	`beta_access_required`	Workspace does not have production API access enabled

API support

Email engineering@cutshort.io for API questions, integration help, or quota issues. Send the mail from the email address on your Cutshort account so we can identify your workspace.

Getting started

Guides

Where to get a key

Key properties

Scopes

Errors

API support

​Where to get a key

​Key properties

​Scopes

​Errors

​API support

Where to get a key

Key properties

Scopes

Errors

API support