Retries & idempotency

Networks fail. A request can reach JobsPipe and the response can still be lost on the way back. These are the tools for retrying without doing anything twice.

Idempotency-Key on POST

Send an Idempotency-Key header with any authenticated POST /v1/* request (the keyless sandbox does not replay). Use a value that is unique to the operation you mean, such as a UUID you generate once and reuse on every retry of it.

curl -X POST https://api.jobspipe.dev/v1/jobs/search \
  -H "Authorization: Bearer $JOBSPIPE_API_KEY" \
  -H "Idempotency-Key: 6f1c2e9a-3b7d-4c55-9a1e-0d2f8b4c7e10" \
  -H "Content-Type: application/json" \
  -d '{"job_title_or": ["data engineer"], "limit": 25}'

• For 24 hours, a repeat of the same key on the same path, with the same API key (or the same signed-in dashboard session), returns the first response again: the same status and the same body. The request does not run a second time, so it costs no credits.
• A replayed response carries Idempotent-Replayed: true. Every response to a request with a key echoes the key back in Idempotency-Key.
• Server errors (5xx) are not stored, so retrying one with the same key runs the request again.
• Keys are scoped to the credential that sent them and to the path. The same key on another endpoint, or sent with another of your API keys, is a different request.

PUT and DELETE

PUT and DELETE are idempotent by design and do not use the header:

• PUT /v1/monitors/by-external-id/{external_id} creates the monitor if it does not exist and updates it if it does. Sending the same body twice leaves the same monitor. The response says which happened in created.
• Deleting a monitor that is already deleted returns 404. A deleted monitor can be restored for 30 days with POST /v1/monitors/{id}/restore.

See Monitors for both.

Preview a change with dry_run

The monitor operations that change or remove things accept ?dry_run=true: the upsert, DELETE /v1/monitors/{id} and DELETE /v1/monitors/{id}/ids. A dry run makes every check and lookup the real call would make, and answers what would happen without changing anything. Use it to show a person what an agent is about to do before it does it.