API resource reference

The live OpenAPI document at /api/v1/openapi.json defines the exact request and response schema. This page helps you choose the right resource and scope before opening the generated reference.

Harly API reference showing job endpoints, authorization, query parameters, and a JSON response. — Generated OpenAPI reference with resources, scopes, and request examples.

API key format

API keys have the format harly_{type}_{env}_{secret}:

Part	Values	Meaning
`type`	`sk` (secret), `pk` (publishable)	Key type — secret keys hold all scopes, publishable keys are browser-safe
`env`	`live`, `test`	Environment
`secret`	43-char base64url	Cryptographically random, stored only as a SHA-256 hash

Example secret key: harly_sk_live_AbCdEf123... Publishable keys (pk) are limited to jobs:read and applications:write — the subset safe to expose in a browser. Even with applications:write, a publishable key can only create applications; moving, rejecting, hiring, and bulk-creating require a secret key. Use secret keys for all server-side integrations.

Resources

Area	Common operations	Required scopes
Jobs	List, read, publish, close	`jobs:read`, `jobs:write`
Candidates	List, create, update, delete, notes, tags, files	`candidates:read`, `candidates:write`, `notes:read`, `notes:write`, `tags:read`, `tags:write`, `files:read`
Applications	List, create, move, reject, hire, bulk create	`applications:read`, `applications:write`
Interviews	List, create, update, cancel, complete	`interviews:read`, `interviews:write`
Offers	Draft, send, decide, withdraw	`offers:read`, `offers:write`
Scorecards	Create, read	`scorecards:read`, `scorecards:write`
Tasks	List, create, update	`tasks:read`, `tasks:write`
Talent pool	List, create, assign	`pool:read`, `pool:write`
Activity events	Read timeline	`activity:read`
Stages	List, create, update, reorder, archive, delete pipeline stages	`stages:read`, `stages:write`
Webhooks	CRUD endpoints, view deliveries, replay	`webhooks:read`, `webhooks:write`
API keys	List, create, rotate, delete	`api_keys:read`, `api_keys:write`
Automations	Withdrawn (HTTP 410)	Dashboard only until automations v2

Mutation examples

List jobs

curl --fail-with-body \
  -H 'Authorization: Bearer harly_sk_live_YOUR_KEY' \
  -H 'Accept: application/json' \
  'https://hiring.example.com/api/v1/jobs?limit=25'

{
  "data": [
    {
      "id": "job_01j1abc",
      "title": "Product Designer",
      "status": "open",
      "department": "Design",
      "location": "Remote"
    }
  ],
  "meta": {
    "pagination": {
      "hasMore": true,
      "limit": 25,
      "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA3LTI3VDEyOjAwOjAwWiIsImlkIjoiam9iXzAxajFhYmMifQ"
    }
  }
}

Create a candidate

curl --fail-with-body -X POST \
  'https://hiring.example.com/api/v1/candidates' \
  -H 'Authorization: Bearer harly_sk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
    "firstName": "Test",
    "lastName": "Candidate",
    "email": "test@example.com"
  }'

Move an application

Use toStageId (not stageId) and always include an idempotency key on mutations:

curl --fail-with-body -X POST \
  'https://hiring.example.com/api/v1/applications/app_01j1abc/move' \
  -H 'Authorization: Bearer harly_sk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: move-app_01j1abc-2026-07-27T12:00:00Z' \
  --data '{"toStageId":"stage_interview"}'

Reject an application

curl --fail-with-body -X POST \
  'https://hiring.example.com/api/v1/applications/app_01j1abc/reject' \
  -H 'Authorization: Bearer harly_sk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"reason":"Not a fit at this time"}'

Rotate an API key

curl --fail-with-body -X POST \
  'https://hiring.example.com/api/v1/api-keys/key_01j1abc/rotate' \
  -H 'Authorization: Bearer harly_sk_live_YOUR_KEY'

A rotation issues a new raw key value and invalidates the previous one. The response includes key — the new raw value, shown once.

Pipeline stages

Stages belong to one job. Each stage has a kind (applied, screening, interview, offer, hired, rejected, withdrawn, or custom) that decides what happens to an application that enters it. The name is display text only: renaming a stage never changes its outcome.

Operation	Endpoint	Notes
List	`GET /api/v1/jobs/{id}/stages`	Active stages in order. Add `?includeArchived=true` to include archived ones.
Create	`POST /api/v1/jobs/{id}/stages`	`position` is the index among active stages. Default: before the first `hired`, `rejected` or `withdrawn` stage.
Update	`PATCH /api/v1/jobs/{id}/stages/{stageId}`	Rename, recolor, change `emailConfig` or `kind`.
Reorder	`POST /api/v1/jobs/{id}/stages/reorder`	`stageIds` must list every active stage exactly once.
Archive	`POST /api/v1/jobs/{id}/stages/{stageId}/archive`	Moves its applications to `mergeIntoStageId` and keeps history.
Delete	`DELETE /api/v1/jobs/{id}/stages/{stageId}`	Only for a stage that has never held an application.

Rules that keep pipelines consistent:

A job always keeps at least one active stage that is not hired, rejected or withdrawn, and active stage names are unique (ignoring case).
Changing kind is refused when the stage holds applications and the change crosses an outcome (to or from hired, rejected or withdrawn). Archive the stage with a merge target of the right kind instead.
Archiving a stage that holds applications requires mergeIntoStageId. An active stage merges into an active stage. An outcome stage merges only into a stage of the same outcome, so no application’s status changes.
Deleting is refused when the stage has applications, appears in stage history, scorecards, document requirements or an automation. Archive it instead.

A merge does not send candidate emails and does not emit application.stage_changed webhooks, because the application’s status does not change. Example: archive a screening stage and move its applications into interview.

curl --fail-with-body -X POST \
  'https://hiring.example.com/api/v1/jobs/job_01j1abc/stages/stage_screening/archive' \
  -H 'Authorization: Bearer harly_sk_live_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: archive-stage_screening-2026-07-27T12:00:00Z' \
  --data '{"mergeIntoStageId":"stage_interview"}'

Stage endpoints use the stages:read and stages:write scopes.

All scopes

jobs:read          jobs:write
candidates:read    candidates:write
applications:read  applications:write
interviews:read    interviews:write
offers:read        offers:write
scorecards:read    scorecards:write
tasks:read         tasks:write
notes:read         notes:write
tags:read          tags:write
stages:read        stages:write
activity:read
pool:read          pool:write
files:read
webhooks:read      webhooks:write
api_keys:read      api_keys:write
automations:read   automations:write

Errors

Status	Meaning	Client action
`400`	Malformed request	Fix the request before retrying
`401`	Missing or invalid key	Rotate or replace the key
`403`	Missing scope or workspace access	Request the narrowest required scope
`404`	Resource not found in the workspace	Reconcile IDs and workspace
`409`	Conflict or idempotency collision	Inspect the error before retrying
`422`	Valid JSON with invalid fields	Show validation details to the operator
`429`	Rate limited	Back off and respect `Retry-After`

Use synthetic data in examples and integration tests. Never place a real resume or candidate email in a public README or issue.

Public jobs and applications

These routes are intended for career sites, custom application forms, and the Harly embed widget. They are CORS-enabled and do not require a secret key, but each request must be scoped to a workspace with ?workspace=<slug> or a publishable key (pk_). See the public API guide for request and response examples.

Method	Path	Workspace selector	Purpose
`GET`	`/api/public/v1/jobs`	`workspace` or `pk_`	List open, published jobs
`GET`	`/api/public/v1/jobs/{slug}`	`workspace` or `pk_`	Fetch a public job and application configuration
`POST`	`/api/public/v1/jobs/{slug}/applications`	`workspace` or `pk_`	Submit an application
`POST`	`/api/public/v1/resume/presign`	`workspace` or `pk_`	Create a resume upload URL
`POST`	`/api/public/v1/image/presign`	`workspace` or `pk_`	Create a profile-image upload URL
`POST`	`/api/public/v1/image/normalize`	`workspace` or `pk_`	Convert an uploaded profile image to a stable format

Publishable keys are limited to jobs:read and applications:write. They are safe to expose in browser code, but they are not authentication for a person; they only identify and scope the workspace. Never expose a secret key. The public list endpoint accepts department, location, workplaceType, and q filters. Public application submissions return 201; validation failures return 422, failed CAPTCHA checks return 403, unavailable jobs return 404, and rate-limited clients receive 429 with Retry-After.

OpenAPI document

Fetch /api/v1/openapi.json from your Harly instance for the full generated contract.

Get started

Tutorials

Using Harly

Deploy Harly

Integrations

Security

API and automation

API Reference

Operations

API resource reference

API key format

Resources

Mutation examples

List jobs

Create a candidate

Move an application

Reject an application

Rotate an API key

Pipeline stages

All scopes

Errors

Public jobs and applications

OpenAPI document

​API key format

​Resources

​Mutation examples

​List jobs

​Create a candidate

​Move an application

​Reject an application

​Rotate an API key

​Pipeline stages

​All scopes

​Errors

​Public jobs and applications

OpenAPI document

API key format

Resources

Mutation examples

List jobs

Create a candidate

Move an application

Reject an application

Rotate an API key

Pipeline stages

All scopes

Errors

Public jobs and applications