API overview

The Harly REST API is available at:

https://hiring.example.com/api/v1

The OpenAPI document is available from a running installation at /api/v1/openapi.json. Use it as the source of truth for exact schemas and route parameters. The repository also includes a generated snapshot at /openapi.json. With the Harly dev server running on port 3000, refresh it after changing an API contract with:

pnpm generate:openapi

Authenticate

Create a key from Settings → Developers → API keys, copy the raw value once, and send it as a bearer token:

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'

Keys are scoped. Give an integration only the resources it needs. Rotate or revoke keys when an owner or vendor changes.

Response envelopes

Success

{
  "data": { ... },
  "meta": {
    "nextCursor": "cursor_01j1abc"
  }
}

Error

{
  "error": {
    "code": "validation_error",
    "message": "A job title is required",
    "details": { "field": "title" }
  }
}

Common error codes: validation_error, not_found, forbidden, conflict, rate_limited.

Pagination

List endpoints use cursor-based pagination:

# First page
curl 'https://hiring.example.com/api/v1/candidates?limit=50'

# Next page — use the cursor from meta.nextCursor
curl 'https://hiring.example.com/api/v1/candidates?limit=50&cursor=cursor_01j1abc'

Do not assume a stable sort order or page number.
meta.nextCursor is absent when you have reached the last page.
limit defaults to 25 and caps at 100.

Idempotency

POST requests that support it accept an Idempotency-Key header. Use a unique value per logical operation — for example a UUID or a stable key derived from the operation’s inputs:

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

A 409 may mean a real concurrency conflict or an idempotency collision. Inspect the error envelope before retrying a mutation. Do not retry a 409 blindly — the operation may have already succeeded.

Rate limits

The API applies per-key rate limits. When a response returns 429, back off using the Retry-After header value before retrying. Do not hammer the API with immediate retries.

# Check the Retry-After header
curl -I 'https://hiring.example.com/api/v1/jobs'
# Retry-After: 30

HTTP status codes

Status	Meaning	Client action
`200`	Success	Process the response
`201`	Created	Record the new resource ID
`204`	No content (delete)	Success, no body
`400`	Malformed request	Fix the request body or params
`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	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`
`5xx`	Server error	Retry with exponential backoff

Main resources

Jobs, candidates, applications, interviews, offers, scorecards, tasks, pool entries, activity events, webhooks, and API keys are available through the versioned API. Use webhooks to react to changes instead of polling every resource. See API resource reference for the full scope and operation inventory.

Try it

The OpenAPI document at /api/v1/openapi.json is importable into Insomnia, Postman, or any OpenAPI-compatible tool:

curl -o harly-openapi.json \
  'https://hiring.example.com/api/v1/openapi.json'

See the API integration tutorial for an end-to-end walkthrough with webhook verification.

Get started

Tutorials

Using Harly

Deploy Harly

Integrations

Security

API and automation

API Reference

Operations

API overview

Authenticate

Response envelopes

Success

Error

Idempotency

Rate limits

HTTP status codes

Main resources

Try it

​Authenticate

​Response envelopes

​Success

​Error

​Pagination

​Idempotency

​Rate limits

​HTTP status codes

​Main resources

​Try it

Authenticate

Response envelopes

Success

Error

Pagination

Idempotency

Rate limits

HTTP status codes

Main resources

Try it