Normalized jobs data for products and AI agents

What's in the API

• Search GET /v1/jobs/search?q=… — keyword search with cursor pagination, stable across updates. Filter by country, posted_after, work_style, seniority, employment_type, company_id.
• Faceted full-text GET /v1/jobs/search/fulltext — Typesense-backed; facets and filters on seniority, work_style, location_country, employment_type.
• Companies + listings GET /v1/companies/{id}/jobs — every active role at one company in one call.
• Compact list payloads ?exclude_description=true drops the multi-KB body and keeps the trimmed summary — list views shrink 5–10×.
• Predictable response shape JSON only. Cursor-based paging via next_cursor. Errors share a stable envelope with code, message, status, and request_id.

Field reliability

Coverage depends on the upstream feed. Plan your client to handle null on these structured fields:

• Salary salary_min / salary_max / salary_interval / currency are populated only when the source publishes them — frequently null.
• Skills skills is best-effort; many feeds carry no structured tags and the array can be empty.
• Precise location location_normalized is the most reliable single field. location_city / location_state / location_country / location_lat / location_lng are sparser.
• Employer When a job arrives via an aggregator/tracker, the real employer may not be recoverable. company_is_unknown=true + company_name="Unknown company" is the honest signal — check it before treating the name as the hiring employer.
• apply_url vs external_id apply_url is what you send users to. external_id is the source identifier; for some sources it is itself a URL and may equal apply_url. We surface the canonical employer URL when available.

Direct signup

1. Register One POST creates your account and mints your first jgk_… API key. The key is shown exactly once.

   curl -X POST https://api.jobgrid.dev/v1/auth/register \
     -H "Content-Type: application/json" \
     -d '{"email":"you@example.com","password":"a-strong-passphrase"}'

2. Capture the response You'll get back access_token and api_key. Use api_key for API calls. The server only stores a hash; use api_key_prefix when contacting support.

   {
     "access_token": "eyJhbGciOi…",
     "refresh_token": "…",
     "expires_in": 1800,
     "api_key": "jgk_…",
     "api_key_prefix": "jgk_xxxxxxx",
     "api_key_id": "…"
   }

3. Authenticate every request Send the key as Authorization: Bearer YOUR_KEY or X-API-Key: YOUR_KEY — either header works. The quickstart query also flips on search_in_description=true so a query like senior python engineer matches the description body and exclude_description=true so the response stays compact for list views — the full body is on GET /v1/jobs/{id}.

   curl -H "Authorization: Bearer YOUR_KEY" \
     "https://api.jobgrid.dev/v1/jobs/search?q=senior%20python%20engineer&search_in_description=true&exclude_description=true&limit=5"

4. Mind the free-tier limits 100 requests / minute per key, enforced via X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset response headers. 429 responses also carry a Retry-After header (seconds to wait), so off-the-shelf HTTP clients back off automatically. Need more for a serious test? Email support@jobgrid.dev and we'll bump your tier.

Pricing & limits

Direct free access is live today. Marketplace paid tiers are drafted and publish with the RapidAPI listing after approval.

• Free — development & testing 100 requests/minute per jgk_… key, surfaced via X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset response headers. 429 responses also carry Retry-After (seconds) so off-the-shelf HTTP clients back off automatically. Monthly quota is not capped on the direct free tier today — confirm by calling GET /v1/me, which returns the authoritative monthly_quota for your key (and null when no monthly cap is configured for that key on this plan; per-minute throttling still applies).
• RapidAPI paid tiers — coming soon Pro, Ultra, and Enterprise tiers will publish alongside the RapidAPI listing. No marketplace tier is purchasable today; need a higher cap for an evaluation? Email support@jobgrid.dev and we'll bump your free key.

Developer reference

• API reference (Swagger) Interactive — try requests in the browser after signing up.
• API reference (ReDoc) Long-form, read-friendly docs.
• OpenAPI schema Machine-readable spec for SDKs and codegen.
• Health endpoint GET /v1/health — JSON readiness probe.

Support

• support@jobgrid.dev Questions, bug reports, integration help.