API Reference

JobDataPool API `v1`

Public, no-auth REST API. Canonical paths live on /v1/* with compatibility aliases on /api/*. The contract below is generated from /openapi.json and the JSON schemas under /schemas/.

Endpoint reference Open OpenAPI spec Browse JSON schemas Try it on the homepage

Canonical server

https://api.jobdatapool.com

Primary host for production traffic. Versioned canonical paths.

Compatibility host

https://jobdatapool.com

Same v1 surface served from the docs origin. /api/* aliases are accepted here for legacy clients.

Overview

What you get from `/v1`

A small, stable surface for querying job listings, source metadata, service health, and ecosystem launch metrics. Responses are JSON, public, cache-friendly, and rate-limited per IP and origin.

Jobs

Filter the canonical listing dataset by limit, industries, country_code, and an optional dedupe key. Records follow job-listing.schema.json.

Sources

The catalog of upstream data sources, contract pointers, and DVC/CSV locations the pool currently reads. Stable enough to back tooling.

Health & launch metrics

Service liveness with current build version, plus the public ecosystem launch counter rolled up across the usage dashboards.

Endpoints

All `/v1` endpoints

Five GET endpoints. Method, path, parameters, response shape, and copy-paste cURL for each.

Jobs

GET `/v1/jobs`

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

Query parameters

Name	Type	Default / range	Description
`limit`	integer	1-250, 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

200 Filtered jobs response — array of JobListing.
400 Bad request — ErrorResponse.
429 Rate limit exceeded.
500 Server error — ErrorResponse.

Response headers

X-Jobs-Count — total number of records in the filtered response.
X-Jobs-Cache — HIT or MISS.
X-Jobs-Source — which upstream produced the response.
X-Jobdatapool-Version — service build version.
X-RateLimit-Policy — e.g. 30;w=60;by=ip+domain.

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

200 Source catalog — SourceCatalog.

Example

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

Health

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

200 Coarse public request metric — LaunchMetricsResponse.

Example

curl -s 'https://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

200 Service is healthy — HealthResponse.

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'

Response Schemas

JSON shapes you can build against

Stable, machine-readable JSON Schemas published under /schemas/. Wire them into tests, validators, and downstream consumers.

`JobListing`

Single job record returned by /v1/jobs. Object with open additionalProperties; the listed fields are the canonical surface.

Open job-listing.schema.json →

Field	Type	Notes
`id`	string	Stable record id within the source.
`job_title`	string	Listing title.
`company_name`	string	Hiring company name.
`job_location`	string	Free-form location, often city / region / remote indicator.
`job_seniority_level`	string	Reported seniority bucket (e.g. Mid-Senior, Entry).
`job_employment_type`	string	Reported employment type (e.g. Full-Time).
`job_industries`	string or string[]	One industry, comma-list, or array.
`job_summary`	string	Short description / posting summary.
`job_base_pay_range`	string	Reported pay band when present.
`job_posted_date`	string	Reported posting date (string, often ISO-8601).
`competitiveness_score`	number or string	Optional internal scoring signal.
`skills`	string	Reported skills (comma-list).
`certifications`	string	Reported certifications.
`industries`	string	Free-text industry tags (legacy alongside `job_industries`).
`achievements`	string	Reported preferred achievements.
`url`	string	Origin posting URL.
`apply_link`	string	Direct apply URL when known.
`country_code`	string	2-letter country code.
`ingest_utc_date`	string	UTC date the row was ingested into the pool.
`ingest_utc_hour`	string or number	UTC hour bucket the row was ingested.
`source_business_url`	string	Canonical homepage of the company / source.

`HealthResponse`

Strict object (additionalProperties: false) returned by /v1/health.

Open health.schema.json →

Field	Type	Required	Notes
`status`	string	yes	Liveness label, e.g. `ok`.
`service`	string	yes	Service identifier, e.g. `jobdatapool`.
`version`	string	yes	Build version.
`time_utc`	string	yes	UTC timestamp when the response was produced.
`data_source`	string	no	Identifier for the upstream data source.
`endpoints`	object<string, string>	yes	Map of canonical endpoint names to URLs.

`SourceCatalog`

Strict object returned by /v1/sources. Wraps SourceRecord entries and exposes contract / endpoint maps.

Field	Type	Required	Notes
`service`	string	yes	Service identifier.
`version`	string	yes	Catalog version.
`sources`	SourceRecord[]	yes	Array of source records.
`contracts`	object<string, string>	yes	Named contract URLs (OpenAPI, schemas, RFC).
`endpoints`	object<string, string>	yes	Named endpoint URLs.

`SourceRecord`

Single entry in SourceCatalog.sources.

Field	Type	Required	Notes
`id`	string	yes	Source identifier.
`kind`	string	yes	Source kind (e.g. scraper, feed, dataset).
`repository_url`	string	yes	Source code or contributor repository.
`data_api_url`	string	yes	Canonical data API URL for this source.
`dvc_pointer_url`	string	yes	DVC pointer JSON describing the latest dataset version.
`csv_url`	string	yes	Resolved CSV URL for the latest dataset version.

`LaunchMetricsResponse`

Strict object returned by /v1/launch-metrics. Aggregates only — no raw IPs, user agents, or paths.

Open launch-metrics.schema.json →

Field	Type	Notes
`requests_since_launch`	integer	Cumulative public request count since launch.
`launch_floor`	integer	Floor used by the dampened public counter.
`launch_offset`	integer	Offset applied before the rolling window.
`metric_window_days`	integer	Length of the rolling metric window.
`average_daily_requests`	integer	Daily average over the metric window.
`usage_dashboard_requests`	integer	Sum of usage dashboard requests across all member sites.
`usage_dashboard_sites`	UsageDashboardSite[]	Per-site rollup. See nested fields below.
`netlify_billing_snapshot_requests`	integer	Netlify billing-snapshot baseline (for cross-checks).
`netlify_edge_tracked_requests`	integer	Edge-tracked request counter.
`netlify_traffic_log_requests`	integer	Netlify traffic-log counter.
`previous_requests_since_launch`	integer	Prior snapshot value (for delta computation).
`request_delta_last_hour`	integer	Delta against the prior snapshot.
`metric_refresh_interval_seconds`	integer	Cadence at which the rollup refreshes (hourly).
`metric_elapsed_seconds`	integer	Seconds since the last refresh.
`estimated_requests_per_second`	number	Smoothed estimate from the rolling delta.
`previous_generated_at`	string	UTC timestamp of the previous snapshot.
`source`	enum	`usage-dashboard-rollup` \| `netlify-billing-snapshot` \| `netlify-log-drain` \| `netlify-edge-tracker` \| `launch-fallback`
`updated_at`	string	UTC timestamp the rollup was last updated.
`generated_at`	string	UTC timestamp the response was generated.
`note`	string	Optional human-readable note for context.

UsageDashboardSite entry shape

Field	Type	Notes
`site_key`	string	Stable identifier for the member site (e.g. `mewannajob`).
`site_url`	string	Canonical URL of the member site.
`request_count`	integer	Cumulative request count for the member.
`updated_at`	string	UTC timestamp the rollup last refreshed for this member.
`status`	string	Operational status from the rollup (`ok`, `stale`, etc.).
`daily`	DailyEntry[]?	Optional per-day rollup. `unique_ips` is a cardinality count only — never the IPs themselves.

DailyEntry shape

Field	Type	Notes
`date`	string (`YYYY-MM-DD`)	Local-day bucket.
`requests`	integer	Public request count that day.
`unique_ips`	integer	Cardinality of distinct request IPs that day.

`ErrorResponse`

Open object returned for 4xx/5xx failures. Always carries an error string; additional fields may be present.

Open error.schema.json →

Field	Type	Required	Notes
`error`	string	yes	Short, human-readable error description.

Status Codes

Errors and rate limiting

Standard HTTP semantics. Errors return JSON, rate limits are advertised via response headers.

Common status codes

200 Success — JSON body matches the response schema for that endpoint.
400 Bad request — invalid query parameter (e.g. limit out of range). ErrorResponse.
429 Too many requests — back off and retry. Inspect X-RateLimit-Policy for the current window.
500 Server error — transient. Retry with exponential backoff. ErrorResponse.

Rate limit posture

The default policy is per-IP and per-Origin, advertised in X-RateLimit-Policy (e.g. 30;w=60;by=ip+domain). Cache aggressively when you can — the canonical responses are immutable for the duration of their Cache-Control.

Public endpoints are no-auth on purpose; please pace your traffic so the pool stays useful for everyone.

Next Steps

Build on it, contribute to it, or read deeper

Run a query in the browser Download bulk datasets Join the pool as a data source Read the RFCs Raw OpenAPI spec

JobDataPool API v1

What you get from /v1

Jobs

Sources

Health & launch metrics

All /v1 endpoints

Query parameters

Responses

Response headers

Example

Responses

Example

Responses

Example

Responses

Example

Responses

Example

JSON shapes you can build against

Errors and rate limiting

Common status codes

Rate limit posture

Build on it, contribute to it, or read deeper

JobDataPool API `v1`

What you get from `/v1`

All `/v1` endpoints