Idempotency

A retried search or feed request runs again and is billed again. Send an Idempotency-Key header, and a retry with the same key returns the stored result at no extra charge.

How it works

Send Idempotency-Key on any POST, PUT, PATCH, or DELETE. Generate one UUID v4 per logical operation before the first attempt, and reuse it for every retry of that operation. A retry with a new key runs and is billed again. The header covers every write route outside /api/auto-apply/*: POST /api/jobs/search and the feed endpoints POST /api/jobs/feed, POST /api/jobs/feed/managed, and POST /api/jobs/feed/{feed_id}. Auto Apply keeps its own records; see the Auto Apply exception.

curl -X POST "https://connect.jobo.world/api/jobs/feed" \
  --max-time 120 \
  -H "X-Api-Key: $JOBO_API_KEY" \
  -H "Idempotency-Key: 6c9b1e2a-8f3d-4b7a-9c1e-2a8f3d4b7a9c" \
  -H "Content-Type: application/json" \
  -d '{"sources": ["greenhouse", "lever"], "batch_size": 1000}'

import os
import uuid

import httpx

key = str(uuid.uuid4())  # one key per page request; reuse it for every retry

response = httpx.post(
    "https://connect.jobo.world/api/jobs/feed",
    headers={
        "X-Api-Key": os.environ["JOBO_API_KEY"],
        "Idempotency-Key": key,
    },
    json={"sources": ["greenhouse", "lever"], "batch_size": 1000},
    timeout=120,
)

What gets stored, and for how long

Rule	Behavior
Scope	Your account, the key, and the route (method, path, and query string). The same key on another route is a separate entry.
Key, not body	Reusing a key with a different body on the same route returns the original stored response.
Stored responses	`2xx` only. After a `4xx` or `5xx`, a retry with the same key runs again.
Lifetime	24 hours. After that, a retry runs as a new request.
Key length	Up to 200 characters. A longer key is ignored, and the request runs without replay protection.
`GET`	No effect. `GET` requests are already safe to repeat.
Not covered	Sandbox-key requests, which are free, and requests through RapidAPI or the MCP server.

On the feed, use a new key for each new cursor. Reusing the previous page’s key returns that stale page.

What a replay returns

A replay returns the original status code and body, plus X-Idempotent-Replay: true. It is not billed again and does not count toward your rate limits. The original’s other headers, such as X-Has-More, X-Credits-Deducted, and X-RateLimit-*, are not replayed. On a feed replay, read has_more and next_cursor from the body. See Response headers.

A result is stored only once the original request completes. A retry sent while the original is still running executes again and is billed again. Give feed requests a client timeout of at least 120 seconds, so you retry only after the server answers.

Worked example: retry after a dropped connection

The server completes attempt 1, but the connection drops before the response arrives. The client retries with the same key and body:

# Attempt 1: completes on the server, but the response is lost
curl -X POST "https://connect.jobo.world/api/jobs/feed" \
  --max-time 120 \
  -H "X-Api-Key: $JOBO_API_KEY" \
  -H "Idempotency-Key: 6c9b1e2a-8f3d-4b7a-9c1e-2a8f3d4b7a9c" \
  -H "Content-Type: application/json" \
  -d '{"sources": ["greenhouse", "lever"], "batch_size": 1000}'

# Attempt 2: same key, same body, so it replays attempt 1's stored result
curl -si -X POST "https://connect.jobo.world/api/jobs/feed" \
  --max-time 120 \
  -H "X-Api-Key: $JOBO_API_KEY" \
  -H "Idempotency-Key: 6c9b1e2a-8f3d-4b7a-9c1e-2a8f3d4b7a9c" \
  -H "Content-Type: application/json" \
  -d '{"sources": ["greenhouse", "lever"], "batch_size": 1000}'

HTTP/1.1 200 OK
X-Idempotent-Replay: true

Attempt 2 returns attempt 1’s page. It does no new work and is not billed.

The Auto Apply exception

/api/auto-apply/* routes skip the shared cache. POST /api/auto-apply/applications requires an Idempotency-Key and keeps its own durable 24-hour record. It returns explicit errors instead of a silent replay:

Status	`code`	Meaning
`400`	`idempotency_key_required`	The create request had no `Idempotency-Key`, or one longer than 200 characters.
`409`	`idempotency_key_reuse`	The key was already used for a different request body.
`409`	`idempotency_key_in_flight`	A request with this key is still being processed.

Create blocks until the first fields are discovered. Repeating it with the same key and body re-attaches to the in-flight application and resumes the same wait, so it is also the recovery path. See Recovery. POST /api/auto-apply/applications/{id}/answers is accepted once per correction round, so a duplicate post attaches to the in-flight wait instead of submitting twice. A key used on a live-key create cannot be reused on a sandbox-key create, or the other way round. That returns 409 idempotency_key_reuse.

Auto Apply keys also expire after 24 hours, and replaying a create after that can create a second application. Persist the key before you send the request, and the application ID as soon as you have it.

Overview

Conventions

Jobs

Feed

Companies

Locations

Auto Apply

How it works

What gets stored, and for how long

What a replay returns

Worked example: retry after a dropped connection

The Auto Apply exception

​How it works

​What gets stored, and for how long

​What a replay returns

​Worked example: retry after a dropped connection

​The Auto Apply exception

How it works

What gets stored, and for how long

What a replay returns

Worked example: retry after a dropped connection

The Auto Apply exception