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.

Public jobs and applications API

The public API is the same API used by Harly’s embedded job widget. It is CORS-enabled and intentionally exposes only published, open jobs and the application intake flow. It never exposes candidate or application records after submission. Every request must identify the workspace in one of these ways:

Add ?workspace=<workspace-slug> to the URL. This is zero-configuration and is suitable when the public workspace slug is already known.
Send a publishable key (pk_) in X-API-Key, Authorization: Bearer, or ?pk=. The key is bound to one workspace and is useful for browser embeds, analytics, and revocation.

The public routes do not infer a workspace automatically, even on a single-workspace installation. Never send a secret (sk_) key to a browser.

1. List open jobs

curl 'https://hiring.example.com/api/public/v1/jobs?workspace=acme'

With a publishable key:

curl \
  -H 'X-API-Key: harly_pk_live_YOUR_PUBLISHABLE_KEY' \
  'https://hiring.example.com/api/public/v1/jobs'

The list endpoint supports the optional department, location, workplaceType, and q query filters. It returns a standard { data } success envelope containing the workspace branding and serialized public jobs. Use the returned job’s slug as the public job identifier. A custom frontend should use the slug rather than the internal job id.

2. Fetch a job and its application configuration

curl \
  'https://hiring.example.com/api/public/v1/jobs/senior-frontend-engineer?workspace=acme'

The response includes applicationConfig. Its questions array is the source of truth for custom questions:

{
  "id": "q_why-us",
  "label": "Why do you want to join us?",
  "type": "textarea",
  "required": true,
  "minLength": 50,
  "placeholder": "Tell us why…"
}

The question’s id is the key used in questionAnswers. Supported question types are text, textarea, url, and select; select questions also return an options array. The same response describes standard fields under applicationConfig.sections, including resume, links, education, experience, and cover letter visibility (required, optional, or disabled).

3. Submit the application

const response = await fetch(
  "https://hiring.example.com/api/public/v1/jobs/senior-frontend-engineer/applications?workspace=acme",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      firstName: "Ada",
      lastName: "Lovelace",
      email: "ada@example.com",
      phone: "+44 20 7946 0958",
      linkedinUrl: "https://linkedin.com/in/ada-lovelace",
      questionAnswers: {
        "q_why-us": "Because…",
      },
      // Include this only when the workspace has CAPTCHA enabled.
      captchaToken: "token-from-your-captcha-provider",
      _hp: "",
    }),
  },
);

if (!response.ok) {
  const error = await response.json();
  // 422 includes field-level validation details.
  throw new Error(error.error?.message ?? "Application failed");
}

The endpoint is:

POST /api/public/v1/jobs/{jobSlug}/applications

It returns 201 with this success envelope:

{
  "data": {
    "received": true,
    "message": "Application received."
  }
}

The API validates required standard fields and every custom answer, so the frontend should render from applicationConfig instead of duplicating the form configuration. If CAPTCHA is configured for the workspace, the application request must include a valid token in captchaToken (the legacy turnstileToken name is also accepted). The public application endpoint is rate-limited to protect the intake flow. Clients must handle 429 and retry after the Retry-After response header. The request also accepts the _hp honeypot field; real forms should leave it empty.

Uploads

For a resume or profile image, request a presigned upload URL first, upload the file directly to that URL, and send the returned key and file metadata in the application payload:

POST /api/public/v1/resume/presign
POST /api/public/v1/image/presign

Both endpoints accept { filename, contentType, contentLength } and are scoped to the same workspace or publishable key. The resume fields are resumeKey, resumeFileName, resumeFileType, and resumeFileSize; the image field is photoUrl.

Normalize a profile image

After you upload a profile image, call the normalize endpoint to convert it to a stable raster format before you use it:

POST /api/public/v1/image/normalize

The flow has three steps:

Call POST /api/public/v1/image/presign and keep the returned key.
PUT the file to the returned uploadUrl.
Call POST /api/public/v1/image/normalize with { "key": "<key>" }.

const response = await fetch(
  "https://hiring.example.com/api/public/v1/image/normalize",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": "harly_pk_live_YOUR_PUBLISHABLE_KEY",
    },
    body: JSON.stringify({ key: presign.data.key }),
  },
);

const image = await response.json();
// { key, contentType, fileUrl }

Harly accepts PNG, JPEG, WebP, and SVG input up to 25 million pixels. It converts the image to WebP and scales it to fit within 2400 × 2400 pixels without enlarging it. The response contains the new key, its contentType, and a fileUrl for the normalized image. The endpoint requires the applications:write scope, is CORS-enabled, and is rate-limited to 20 requests per minute per IP address. It only accepts keys returned by the public image presign endpoint. Harly deletes the temporary upload after a successful conversion, so resubmitting the same key returns 404.

Status	Meaning
`400`	Invalid request body or unsupported image
`404`	Key not found, outside the public upload area, or already normalized
`422`	Harly could not process the image
`429`	Rate limited

For a browser integration, the publishable-key variant is usually preferable:

const headers = {
  "Content-Type": "application/json",
  "X-API-Key": "harly_pk_live_YOUR_PUBLISHABLE_KEY",
};

Never expose a secret (sk_) key in frontend code.

Public API errors

Public routes use the same error envelope as the authenticated API:

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed.",
    "details": {}
  }
}

Common statuses are 400 for a missing or malformed workspace selector, 403 for a failed CAPTCHA or missing publishable-key scope, 404 for a job that is not public, 422 for invalid application fields, and 429 for rate limiting.

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

Public jobs and applications API

1. List open jobs

2. Fetch a job and its application configuration

3. Submit the application

Uploads

Normalize a profile image

Public API errors

​Authenticate

​Response envelopes

​Success

​Error

​Pagination

​Idempotency

​Rate limits

​HTTP status codes

​Main resources

​Try it

​Public jobs and applications API

​1. List open jobs

​2. Fetch a job and its application configuration

​3. Submit the application

​Uploads

​Normalize a profile image

​Public API errors

Authenticate

Response envelopes

Success

Error

Pagination

Idempotency

Rate limits

HTTP status codes

Main resources

Try it

Public jobs and applications API

1. List open jobs

2. Fetch a job and its application configuration

3. Submit the application

Uploads

Normalize a profile image

Public API errors