API DOCUMENTATION / API REFERENCE
API reference
Index of public API routes and their current implementation status.
Read operations
| Method and path | Purpose | Notes |
|---|---|---|
GET /v1/jobs | Page through the combined jobs projection. | Requires an API key. |
GET /v1/jobs/count | Count distinct included job IDs at a projection watermark. | Requires an API key. |
GET /v1/jobs/changes | Read created, updated, and expired events from a change cursor or timestamp. | Requires an API key. |
GET /v1/jobs/{jobId} | Read one combined job. | Route is implemented; merged, withdrawn, and missing IDs have distinct outcomes. |
GET /v1/companies | List the pinned company release. | Requires an API key. |
POST /v1/companies/search | Search that company projection with JSON criteria. | Requires an API key. |
GET /v1/companies/{companyId} | Read one registry company. | Route is implemented; merged IDs redirect. |
GET /v1/companies/{companyId}/jobs | List jobs scoped to a canonical company ID. | Requires an API key. |
GET /v1/usage/requests | Read the authenticated customer request ledger. | Requires an API key. |
GET /v1/usage/analytics | Read daily request and returned-record aggregates. | Requires an API key. |
Conditional availability
The API can return 503 when the public catalog, projection metadata, cursor secret, or a required company representation is unavailable. An HTML description request also returns an unavailable error until confirmed source HTML is provided.
Request examples
jobs list
curl --request GET "$HEADCOUNTLABS_BASE_URL/v1/jobs?currentness=current&limit=50" --header 'Authorization: Bearer <API_KEY>'jobs count
curl --request GET "$HEADCOUNTLABS_BASE_URL/v1/jobs/count?company_id=12345678-1234-4234-8234-123456789abc¤tness=current" --header 'Authorization: Bearer <API_KEY>'job detail
curl --request GET "$HEADCOUNTLABS_BASE_URL/v1/jobs/12345678-1234-4234-8234-123456789abc" --header 'Authorization: Bearer <API_KEY>'job changes
curl --request GET "$HEADCOUNTLABS_BASE_URL/v1/jobs/changes?after=opaque_cursor_example&limit=100" --header 'Authorization: Bearer <API_KEY>'company list
curl --request GET "$HEADCOUNTLABS_BASE_URL/v1/companies?name=Acme&limit=20" --header 'Authorization: Bearer <API_KEY>'company search
curl --request POST "$HEADCOUNTLABS_BASE_URL/v1/companies/search" --header 'Authorization: Bearer <API_KEY>' --header 'Content-Type: application/json' --data-raw '{"name":"Acme","country":"US","status":"active","limit":20}'company id
curl --request GET "$HEADCOUNTLABS_BASE_URL/v1/companies/12345678-1234-4234-8234-123456789abc" --header 'Authorization: Bearer <API_KEY>'Continue in the reference
Check related request behavior before you build.
View route status and methods Discuss API requirements