Reference

API

Eleven endpoints, JSON in / JSON out, Bearer auth.

Authentication

Every request must include a Bearer token in the Authorization header.

Authorization: Bearer ahr_live_<key>   # production
Authorization: Bearer ahr_test_<key>   # sandbox

Tokens are issued at /developers/keys. Plaintext is shown once at creation; we store only a SHA-256 hash.

Scopes

Each key has one or more scopes. Calls without the required scope return 403 forbidden.

Scope	Grants
`parse`	POST /api/v1/parse/resume, /parse/jd
`match`	POST /api/v1/match, GET /api/v1/matches
`retention`	POST /api/v1/retention-forecast
`skills`	POST /api/v1/skills-infer
`jobs`	POST /api/v1/jobs/sync, /jobs/bulk-sync, GET /api/v1/jobs
`candidates`	POST /api/v1/candidates/sync, GET /api/v1/candidates

Tenant scoping

Keys can additionally be bound to a specific employer or organization. When bound, the API enforces that all reads and writes touch only that tenant. Cross-tenant requests return 403.

Employer-scoped keys: required for /api/v1/jobs/*
Organization-scoped keys: required for /api/v1/candidates/*
Either: allowed for parse / match / retention / skills

Endpoints

Parsing

POST/api/v1/parse/resume

POST/api/v1/parse/jd

Matching + scoring

POST/api/v1/match

GET/api/v1/matches

POST/api/v1/retention-forecast

POST/api/v1/skills-infer

Sync (employer)

POST/api/v1/jobs/sync

POST/api/v1/jobs/bulk-sync

GET/api/v1/jobs

Sync (organization)

POST/api/v1/candidates/sync

GET/api/v1/candidates

Full request / response shape on each endpoint's page from the sidebar.

Errors

HTTP	error	When
`400`	`missing_body / missing_ids / missing_text / missing_jobs`	Required field absent
`401`	`unauthorized`	No Authorization header or invalid prefix
`403`	`forbidden / key_not_employer_scoped / key_not_organization_scoped`	Scope insufficient or tenant mismatch
`404`	`not_found`	candidateId / jobId / docId does not exist
`413`	`too_many`	Bulk-sync over 100 items
`422`	`parse_failed`	Underlying parse threw (e.g. corrupt PDF)
`500`	`internal`	Unhandled — should not happen, please report

Rate limits

v1 is best-effort — no published rate limit. We may add caps if abuse appears. Live keys get notified by email at the address on the account before any limit takes effect.

Versioning

The path prefix /api/v1 is part of the contract. Breaking changes ship under /api/v2; v1 keeps responding for at least 12 months after any v2 release. Additive changes (new optional fields, new endpoints) ship in v1 directly.