API reference
Every endpoint of version 1, with its parameters and the shape it returns.
Version 1 of the API. Every path starts with /v1.
https://api.enrichednow.com/v1Conventions#
| Format | JSON in, JSON out. Send Content-Type: application/json with a body. |
| Times | RFC 3339, in UTC, to the microsecond: 2026-11-16T20:27:29.418918Z. |
| Ids | Strings with a prefix that says what they are: acc_, usr_, key_, run_. |
| Auth | Authorization: Bearer <key> — see Authentication. |
| Errors | {"error": {"code", "message", "details"}} with a matching HTTP status — see Errors. |
| Paging | List endpoints return next_cursor. Pass it back as cursor for the next page; null means the end. |
Endpoints#
| Method and path | Auth | Does |
|---|---|---|
GET /v1/health | None | Says the service is up. |
GET /v1/scrapers | None | Lists the scrapers. |
GET /v1/scrapers/{id} | None | One scraper, with its schemas. |
POST /v1/scrapers/{id}/runs | Key | Starts a run. |
GET /v1/runs | Key | Lists your runs. |
GET /v1/runs/{id} | Key | One run. |
GET /v1/runs/{id}/records | Key | A run's records. |
POST /v1/runs/{id}/cancel | Key | Asks a run to stop. |
GET /v1/usage | Key | Units charged in a period. |
POST /v1/auth/signup | None | Creates an account. Console. |
POST /v1/auth/login | None | Starts a session. Console. |
POST /v1/auth/logout | Session | Ends the session. Console. |
GET /v1/me | Session | The signed-in user and account. Console. |
GET /v1/keys | Session | Lists API keys. Console. |
POST /v1/keys | Session | Creates an API key. Console. |
DELETE /v1/keys/{id} | Session | Revokes an API key. Console. |
Where the table says Key, the console's session is accepted as well. Where it says Session, a key is not accepted.
The same list, machine-readable, is the OpenAPI document at GET /v1/openapi.json.
An address that does not exist — or a method an address does not have — answers 404 not_found.
Service#
GET /v1/health#
No authentication.
curl "https://api.enrichednow.com/v1/health"{ "status": "ok" }Catalogue#
GET /v1/scrapers#
The public catalogue: every scraper that is available. No authentication.
curl "https://api.enrichednow.com/v1/scrapers"{
"scrapers": [
{
"id": "ats.board",
"version": 1,
"title": "ATS job board",
"summary": "Job openings from one board of an applicant tracking system (Greenhouse, Lever, Ashby, Workday and others).",
"mode": "job",
"billing_unit": "request",
"data_class": "public",
"availability": "public"
},
{
"id": "careers.company",
"version": 1,
"title": "Company careers site",
"summary": "Job openings from a company's own careers site: give its domain or its careers page.",
"mode": "job",
"billing_unit": "request",
"data_class": "public",
"availability": "public"
}
]
}Each item is a ScraperCard, without the schemas.
GET /v1/scrapers/{id}#
One scraper, with the JSON Schema of its input (input_schema) and of the records it returns (record_schema).
No authentication.
curl "https://api.enrichednow.com/v1/scrapers/ats.board"Returns a ScraperCard including both schemas (shortened here):
{
"id": "ats.board",
"version": 1,
"title": "ATS job board",
"summary": "Job openings from one board of an applicant tracking system (Greenhouse, Lever, Ashby, Workday and others).",
"mode": "job",
"billing_unit": "request",
"data_class": "public",
"availability": "public",
"input_schema": {
"…": "JSON Schema"
},
"record_schema": {
"…": "JSON Schema"
}
}| Error | When |
|---|---|
404 not_found | No scraper has this id, or the scraper is not publicly available. |
The scraper pages on this site are generated from the same schemas.
Runs#
POST /v1/scrapers/{id}/runs#
Starts a run of the scraper {id}. Guide: Running a scraper.
Query
| Parameter | Type | Meaning |
|---|---|---|
wait | number, 0 to 60, default 0 | Seconds to hold the request open for the run to end. Fractions are accepted. |
Body
| Field | Type | Meaning |
|---|---|---|
input | object | Required. The scraper's input. Its fields are the scraper's input_schema. The body takes no other field. |
curl -X POST "https://api.enrichednow.com/v1/scrapers/ats.board/runs?wait=60" \
-H "Authorization: Bearer $ENRICHEDNOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"board_url": "https://boards.greenhouse.io/acme"}}'Returns a Run:
| Status | When |
|---|---|
200 | The run ended within wait. The run is final. |
202 | The run was accepted and has not ended yet: it is queued or running. Without wait, this is the answer. |
{
"id": "run_eb3c3302a5eb6987c17f3b53",
"scraper_id": "careers.company",
"scraper_version": 1,
"status": "queued",
"reason": null,
"input": {
"domain": "example.com"
},
"record_count": 0,
"units": 0,
"diagnostics": null,
"created_at": "2026-11-16T20:27:31.253846Z",
"started_at": null,
"finished_at": null
}| Error | When |
|---|---|
401 unauthorized | No valid key. |
404 not_found | No such scraper, or it is not publicly available. |
422 invalid_input | input does not fit the scraper's schema, wait is out of range, or the body is not {"input": {...}}. details.fields lists each problem. |
402 quota_exceeded | The account's allowance is used up. details carries used_units and allowance_units. |
429 too_many_runs | The account is at its concurrent-run limit. details carries active_runs and max_concurrent_runs. |
None of these creates a run.
GET /v1/runs#
Your account's runs, newest first.
Query
| Parameter | Type | Meaning |
|---|---|---|
limit | integer, 1 to 100, default 20 | Runs per page. |
cursor | string | The next_cursor of the previous page. |
scraper_id | string | Only runs of this scraper. |
status | string | Only runs with this status. |
curl "https://api.enrichednow.com/v1/runs?scraper_id=ats.board&status=unsupported" \
-H "Authorization: Bearer $ENRICHEDNOW_API_KEY"{
"runs": [
{
"id": "run_9eebae2bc0db3036c9893cda",
"scraper_id": "ats.board",
"scraper_version": 1,
"status": "unsupported",
"reason": "render_required",
"input": {
"board_url": "https://jobs.dayforcehcm.com/en-US/acme/CANDIDATEPORTAL"
},
"record_count": 0,
"units": 0,
"diagnostics": {
"requests": 0,
"bytes": null,
"wall_ms": 0,
"facts": {
"ats": "dayforce"
}
},
"created_at": "2026-11-16T20:27:29.617445Z",
"started_at": "2026-11-16T20:27:29.619938Z",
"finished_at": "2026-11-16T20:27:29.623160Z"
},
{
"id": "run_d783786ba1ae8662767c764e",
"scraper_id": "ats.board",
"scraper_version": 1,
"status": "unsupported",
"reason": "unknown_board",
"input": {
"board_url": "https://jobs.acme.com/openings"
},
"record_count": 0,
"units": 0,
"diagnostics": {
"requests": 0,
"bytes": null,
"wall_ms": 0,
"facts": {}
},
"created_at": "2026-11-16T20:27:29.606933Z",
"started_at": "2026-11-16T20:27:29.610174Z",
"finished_at": "2026-11-16T20:27:29.613181Z"
}
],
"next_cursor": null
}runs is a list of Run. 422 invalid_input for a limit out of range, a status that is not one, or
a cursor this API did not give out.
GET /v1/runs/{id}#
One run, as it is now.
curl "https://api.enrichednow.com/v1/runs/run_6cce2b12aaf37a10b5e1b885" \
-H "Authorization: Bearer $ENRICHEDNOW_API_KEY"Returns a Run. 404 not_found when your account has no such run.
{
"id": "run_6cce2b12aaf37a10b5e1b885",
"scraper_id": "ats.board",
"scraper_version": 1,
"status": "ok",
"reason": null,
"input": {
"board_url": "https://boards.greenhouse.io/acme"
},
"record_count": 19,
"units": 1,
"diagnostics": {
"requests": 1,
"bytes": 232779,
"wall_ms": 565,
"facts": {
"careers_url": "https://boards.greenhouse.io/acme",
"discovery": "supplied",
"ats": "greenhouse",
"pages_read": 1,
"renders_refused": 0
}
},
"created_at": "2026-11-16T20:27:29.009834Z",
"started_at": "2026-11-16T20:27:29.013803Z",
"finished_at": "2026-11-16T20:27:29.582787Z"
}GET /v1/runs/{id}/records#
The records a run stored, in the order it stored them. Records are kept for 7 days after the run ended.
Query
| Parameter | Type | Meaning |
|---|---|---|
limit | integer, 1 to 1000, default 100 | Records per page. |
cursor | string | The next_cursor of the previous page. |
curl "https://api.enrichednow.com/v1/runs/run_6cce2b12aaf37a10b5e1b885/records?limit=1000" \
-H "Authorization: Bearer $ENRICHEDNOW_API_KEY"Returns
| Field | Type | Meaning |
|---|---|---|
records | list | One page of records. Empty for a run that stored none. |
next_cursor | string or null | Pass it back as cursor for the next page; null at the end. |
expired | true | Present only when the records are gone because the 7 days have passed. |
Each record has the shape of the scraper's record_schema — see the scraper pages. A page asked
for with limit=2 (the records themselves are left out here), and the answer once the records have expired:
{
"records": [
{
"…": "a record"
},
{
"…": "a record"
}
],
"next_cursor": "Mg"
}{
"records": [],
"next_cursor": null,
"expired": true
}POST /v1/runs/{id}/cancel#
Asks a run to stop. No body.
curl -X POST "https://api.enrichednow.com/v1/runs/run_6cce2b12aaf37a10b5e1b885/cancel" \
-H "Authorization: Bearer $ENRICHEDNOW_API_KEY"Returns the Run with 200, as it is at that moment: cancelled for a run that was still queued,
usually still running for one that was running, and unchanged for one that had already ended. Cancelling is
cooperative: a run that was already finishing may still complete, so poll for the status it ends with — see
Cancel a run. A run that ends cancelled costs nothing and keeps the
records it had found.
Usage#
GET /v1/usage#
Units charged in a period. Guide: Usage and units.
Query
| Parameter | Type | Meaning |
|---|---|---|
from | date | First day of the period (UTC), included. Default: the 1st of the month to falls in. |
to | date | Last day of the period (UTC), included. Default: today. |
group_by | day or scraper, default day | What one row stands for. |
A period is at most 366 days, and must not end before it starts: otherwise 422 invalid_input.
curl "https://api.enrichednow.com/v1/usage?from=2026-11-01&to=2026-11-30&group_by=day" \
-H "Authorization: Bearer $ENRICHEDNOW_API_KEY"Returns
| Field | Type | Meaning |
|---|---|---|
period | object | The period covered: from and to. |
total_units | integer | Units charged in the period. |
allowance_units | integer | The account's allowance for a calendar month. |
rows | list | key, units and runs (the charged runs). By day: one row for every day of the period. By scraper: one row for each scraper that was charged, most units first. |
{
"period": {
"from": "2026-11-16",
"to": "2026-11-16"
},
"total_units": 1,
"allowance_units": 1000,
"rows": [
{
"key": "2026-11-16",
"units": 1,
"runs": 1
}
]
}Console endpoints#
These are what the console itself calls. They use a session cookie, not an API key, and you do not need them
to use the API. A session is a cookie named enrichednow_session (HttpOnly, SameSite=Lax, 30 days) set by signing
up or logging in. Requests that change something — every POST and DELETE made with the session, starting and
cancelling runs included — must also send the header X-CSRF-Token, with the csrf_token value that signing up,
logging in and GET /v1/me return; without it the answer is 403 forbidden.
Signing up and logging in are limited to 20 attempts a minute: 429 rate_limited, with a Retry-After header.
POST /v1/auth/signup#
Creates a user and an account, and starts a session.
| Field | Type | Meaning |
|---|---|---|
email | string | The user's email address. Kept in lowercase. |
password | string | The password, at least 8 characters. Stored only as a scrypt hash. |
account_name | string | A name for the account, at most 200 characters. |
Returns 201 with Me and sets the session cookie:
POST /v1/auth/signup
HTTP 201
Set-Cookie: enrichednow_session=<session token>; HttpOnly; Max-Age=2592000; Path=/; SameSite=lax{
"user": {
"id": "usr_a750fc675f1e87d6e8f8e445",
"email": "you@acme.com"
},
"account": {
"id": "acc_6d354f1d8ef38533377cc8db",
"name": "Acme",
"allowance_units": 1000,
"max_concurrent_runs": 2
},
"csrf_token": "csrf-token-from-GET-/v1/me"
}422 invalid_input when a field does not fit, or when an account with this email already exists:
{
"error": {
"code": "invalid_input",
"message": "An account with this email already exists.",
"details": {
"fields": [
{
"path": "email",
"message": "An account with this email already exists."
}
]
}
}
}POST /v1/auth/login#
Starts a session. The body is email and password. Returns 200 with Me and sets the session cookie.
A wrong email or password — the answer does not say which — is 401 unauthorized:
{
"error": {
"code": "unauthorized",
"message": "The email or the password is wrong.",
"details": {}
}
}POST /v1/auth/logout#
Ends the session. Needs the X-CSRF-Token header. Returns 204 with no body and clears the cookie.
GET /v1/me#
The signed-in user, their account, and the CSRF token. Returns Me.
GET /v1/keys#
The account's API keys, without their secrets.
{
"keys": [
{
"id": "key_02f1e08e65f29703d1b463e7",
"name": "production",
"prefix": "k3J9xQ2m",
"created_at": "2026-11-16T20:27:28.985324Z",
"last_used_at": "2026-11-16T20:27:28.990857Z",
"revoked_at": null
}
]
}keys is a list of Key, newest first. A revoked key stays in the list, with its revoked_at.
POST /v1/keys#
Creates an API key.
| Field | Type | Meaning |
|---|---|---|
name | string | A name for the key, at most 100 characters. |
Returns 201 with the Key and one more field, secret — the key itself. This is the only time the
secret is returned. (The secret below is a placeholder in the real format.)
{
"id": "key_02f1e08e65f29703d1b463e7",
"name": "production",
"prefix": "k3J9xQ2m",
"created_at": "2026-11-16T20:27:28.985324Z",
"last_used_at": null,
"revoked_at": null,
"secret": "en_live_k3J9xQ2mT7vB1nR5cW8yZ4aD6fH0jL2pS9uX3eG7iK1"
}DELETE /v1/keys/{id}#
Revokes a key. Returns 204 with no body. The key stops working at once: the next request with it is answered
401. Revoking a key twice is still 204; 404 not_found when the account has no such key.
Shapes#
ScraperCard#
| Field | Type | Meaning |
|---|---|---|
id | string | The scraper's id: family.name, such as ats.board. |
version | integer | The scraper's version. |
title | string | A short name. |
summary | string | One sentence on what it returns. |
mode | sync or job | sync: answers within one request. job: reads several pages and runs in the background. |
billing_unit | request or record | What a charged run costs — see Usage and units. |
data_class | string | The kind of data returned. public for every scraper available today. |
availability | public or internal | Only public scrapers are listed and can be run. |
input_schema | JSON Schema | The input. Only on GET /v1/scrapers/{id}. |
record_schema | JSON Schema | One record. Only on GET /v1/scrapers/{id}. |
Run#
| Field | Type | Meaning |
|---|---|---|
id | string | run_… |
scraper_id | string | The scraper that ran. |
scraper_version | integer | The version of the scraper that ran. |
status | string | queued, running, ok, partial, failed, unsupported or cancelled — see Statuses. |
reason | string or null | A code when the status is not ok — see Reason codes. |
input | object | The input the run was started with. |
record_count | integer | The number of records stored. |
units | integer | The units charged — see Usage and units. |
diagnostics | object or null | requests, bytes, wall_ms and facts; null until the run ends — see Diagnostics. |
created_at | time | When the run was accepted. |
started_at | time or null | When execution began; null while the run is queued. |
finished_at | time or null | When the run ended; null until then. |
{
"id": "run_6cce2b12aaf37a10b5e1b885",
"scraper_id": "ats.board",
"scraper_version": 1,
"status": "ok",
"reason": null,
"input": {
"board_url": "https://boards.greenhouse.io/acme"
},
"record_count": 19,
"units": 1,
"diagnostics": {
"requests": 1,
"bytes": 232779,
"wall_ms": 565,
"facts": {
"careers_url": "https://boards.greenhouse.io/acme",
"discovery": "supplied",
"ats": "greenhouse",
"pages_read": 1,
"renders_refused": 0
}
},
"created_at": "2026-11-16T20:27:29.009834Z",
"started_at": "2026-11-16T20:27:29.013803Z",
"finished_at": "2026-11-16T20:27:29.582787Z"
}Key#
| Field | Type | Meaning |
|---|---|---|
id | string | key_… |
name | string | The name given when it was created. |
prefix | string | The 8 characters that follow en_live_ in the key, shown so that you can tell your keys apart. |
created_at | time | When it was created. |
last_used_at | time or null | When it was last used (noted at most once a minute); null for a key never used. |
revoked_at | time or null | When it was revoked; null for a key that works. |
secret | string | The key itself. Only in the answer of POST /v1/keys. |
Me#
{
"user": {
"id": "usr_a750fc675f1e87d6e8f8e445",
"email": "you@acme.com"
},
"account": {
"id": "acc_6d354f1d8ef38533377cc8db",
"name": "Acme",
"allowance_units": 1000,
"max_concurrent_runs": 2
},
"csrf_token": "csrf-token-from-GET-/v1/me"
}csrf_token is the value of the X-CSRF-Token header (a placeholder stands in for it here).
Error#
{
"error": {
"code": "not_found",
"message": "There is no run 'run_000000000000000000000000'.",
"details": {}
}
}| Code | HTTP |
|---|---|
unauthorized | 401 |
quota_exceeded | 402 |
forbidden | 403 |
not_found | 404 |
invalid_input | 422 |
too_many_runs | 429 |
rate_limited | 429 |
internal | 500 |
What each means and how to handle it: Errors.