Skip to main content

API reference

Quickstart: curl

Make your first authenticated Jobby.dev API call with curl — list live events, join a queue, watch a match come back.

Last updated

From zero to a working API call in five minutes. Every snippet below works in any POSIX shell with curl installed.

1. Mint a token

Head to /account/api-tokens. Click New token, pick the scopes queue:read + queue:write + matches:read, label it "curl quickstart", and copy the token. Export it:

export JOBBYDEV_API_TOKEN=jbb_...

2. List currently-live events (no auth needed)

curl 'https://jobby.dev/api/v1/live-events?limit=5' | jq

Discovery endpoints work without a token — public by design. Note the Cache-Control: this endpoint is edge-cached for ~15 seconds, so you're hitting our CDN, not the origin.

3. Authenticated call: read your profile

curl https://jobby.dev/api/v1/profile \
  -H "Authorization: Bearer $JOBBYDEV_API_TOKEN"

You should see your headline, skills, and other profile fields. Note the X-RateLimit-* headers in the response — track these to back off cleanly. See rate limits.

4. Join a queue

Find an event slug from the discovery listing, then:

curl https://jobby.dev/api/v1/queue/join \
  -H "Authorization: Bearer $JOBBYDEV_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"event_id": "evt_abc123"}'

5. Poll your queue status

curl https://jobby.dev/api/v1/queue/status \
  -H "Authorization: Bearer $JOBBYDEV_API_TOKEN"

Response includes your queue position, estimated wait, and any current match. Don't poll faster than once every 5 seconds — you'll burn rate-limit budget for nothing. Production integrations should subscribe to webhooks instead — see webhooks overview.

6. Read recent matches

curl 'https://jobby.dev/api/v1/matches?limit=10' \
  -H "Authorization: Bearer $JOBBYDEV_API_TOKEN"

Errors you'll see

  • 401 — token missing or revoked. Check the bearer header.
  • 403 with code: "INSUFFICIENT_SCOPE" — your token is valid but doesn't carry the right scope. Mint a new one with the scope you need.
  • 429 — you hit a rate limit. Honor Retry-After.

Next steps