jobdatapool.com

API Reference

JobDataPool API v1

A public REST API for current job listings and pool metadata, with optional Firebase authentication for account-based quotas.

Run your first request OpenAPI 3.1 JSON Schemas

Quickstart

Make a request in under a minute

Use https://api.jobdatapool.com as the canonical production host. Anonymous access requires no API key.

Anonymous request

curl -s "https://api.jobdatapool.com/v1/jobs?limit=5&country_code=US" \
  -H "Accept: application/json"

Example response

[
  {
    "id": "...",
    "job_title": "Software Engineer",
    "company_name": "Example Company",
    "country_code": "US"
  }
]

Authentication and quotas

Anonymous by default, account-based when authenticated

Website sign-in does not automatically authenticate a terminal. Send a Firebase ID token in the bearer header when you want requests charged to the signed-in account.

How accounting works

  • Each accepted call consumes one request.
  • Returned jobs and successful job redirects consume the shared listing allowance.
  • The response identifies the active policy with X-RateLimit-Identity.
  • Exhausted allowances return 429 and Retry-After.
  • /v1/jobs uses private, no-store so every call reaches quota accounting.

Endpoints

All /v1 endpoints

Five stable GET endpoints. Start with jobs, then use the compact service endpoints for source and operational metadata.

Jobs

GET /v1/jobs

List jobs from the canonical reviewed dataset, filtered by industry, country, and optional dedupe key.

Query parameters

NameTypeDefault / rangeDescription
limit integer 1-50, default 25 Maximum number of rows returned.
industries string e.g. Software,Government Comma-separated industries filter (case-insensitive partial match against job_industries and industries).
country_code string (2 chars) e.g. US ISO-like 2-letter country code. Compared against country_code.
distinct_by enum job_title | apply_link | url | company_name Optional dedupe key. Keeps the first record per group.

Responses

Response headers

  • X-Jobs-Count — rows returned in this response.
  • X-Jobs-Cache — internal dataset snapshot HIT or MISS.
  • X-Jobs-Source — upstream dataset source.
  • X-RateLimit-Identity — ip, user, or donor.
  • X-RateLimit-Policy — e.g. req=5;max=50;quota=10;w=60;by=ip.
  • See every quota and reset header →

Example

curl -s "https://api.jobdatapool.com/v1/jobs?limit=5&industries=Software&country_code=US" \
  -H "Accept: application/json"

Sources

GET /v1/sources

List canonical data sources, contract pointers, and DVC/CSV locations the pool currently reads.

Responses

Example

curl -s 'https://api.jobdatapool.com/v1/sources' \
  -H 'Accept: application/json'

Metrics

GET /v1/launch-metrics

Public launch traction metric: rolling request totals, daily averages, and the per-site usage dashboard rollup. Aggregates only — no raw IPs.

Responses

Example

curl -s 'https://api.jobdatapool.com/v1/launch-metrics' \
  -H 'Accept: application/json'

Health

GET /v1/health

Health check with current build version, service identity, data source, and the public endpoint map.

Responses

Example

curl -s 'https://api.jobdatapool.com/v1/health' \
  -H 'Accept: application/json'

Health

GET /v1

Versioned API index. Returns the canonical endpoint map and version metadata so clients can self-describe.

Responses

  • 200 Versioned API index (open object with canonical endpoints).

Example

curl -s 'https://api.jobdatapool.com/v1' \
  -H 'Accept: application/json'

Errors, headers, and caching

Read the response before retrying

API clients receive JSON errors. Browser navigations that request HTML receive a friendly slow-down page for 429 responses.

Status codes

  • 200 Successful response.
  • 400 Invalid request parameters.
  • 401 Invalid or expired Firebase ID token.
  • 429 Request or listing allowance exhausted; honor Retry-After.
  • 500 Transient server failure; retry with exponential backoff.
  • 511 A restricted network must identify with a verified account.

Quota headers

X-RateLimit-IdentityX-RateLimit-Policy X-RateLimit-Requests-LimitX-RateLimit-Requests-Remaining X-RateLimit-Requests-ResetX-RateLimit-Limit X-RateLimit-RemainingX-RateLimit-Reset X-RateLimit-Per-Request-MaxX-RateLimit-Effective-Limit Retry-After

Cache semantics

X-Jobs-Cache reports whether the service used its internal dataset snapshot. It does not mean the client response was served from a browser or shared CDN cache. Quota-bearing jobs responses use Cache-Control: private, no-store.

Response contracts

Validate against published JSON Schemas

The schema files are the exhaustive field reference. These crawlable summaries keep the API guide focused on making requests.

JobListing

A single record returned by /v1/jobs, including provenance, job attributes, validation state, and masked redirect URLs.

Open job-listing.schema.json →
Browse all schema documentationOpen the OpenAPI contract

Next Steps

Build on it, contribute to it, or read deeper

Run a query in the browser Download dataset samples Install the MCP server Join the pool as a data source Read the whitepapers Raw OpenAPI spec