JobGrid API is live

What's in the API

• Search GET /v1/jobs/search?q=… — keyword + 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 all share {"error": {code, message, status, 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.

Sign up — get a key in one call

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

   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 (JWT for the dashboard, when it lands) and api_key (your jgk_… key for the paid routes). The server only stores a hash — lose it and you'll need to register again or contact 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.

   curl -H "Authorization: Bearer YOUR_KEY" \
     "https://api.jobgrid.dev/v1/jobs/search?q=python&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.

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.