Idempotency

Retry job creation safely with an Idempotency-Key, and what the API returns for a retry, a conflict and an expired key.

A network error can hide whether a job was created. Send an Idempotency-Key header with POST /v1/jobs or a per-operation endpoint (POST /v1/transcode, ...), and retry with the same key: you get the same job, never a second one.

bash

curl "$VIDEXO_API_URL/v1/jobs" \
  -H "Authorization: Bearer $VIDEXO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1234-transcode" \
  -d @job.json

The key is up to 255 printable ASCII characters without spaces. Use a value from your own system, such as an order id and a step, or a random UUID.
Keys belong to your account; another account's key never matches yours.
Every endpoint that creates a job, and the MCP tool create_job, shares your account's keys. The key remembers the endpoint as well as the body: the same key on another endpoint is a conflict, even with the same body. create_job counts as POST /v1/jobs.

What a retry returns#

Request	Response
A new key	`202` with the new job.
The same key, endpoint and body within 24 hours	`200` with the job as it is now.
The same key with another body or endpoint within 24 hours	`409 conflict` (reason `idempotency_key_reused`); nothing changes.
The same key after 24 hours	The key is free again: `202` with a new job.

The body is compared as JSON, so key order and spacing do not matter. A retry is handled before the rate limit, the body checks and the usage cap, so a retry of a job that was created always gets the job, even when a new job would be rejected.