Idempotency

A timeout is not an answer. Send an Idempotency-Key on every paid call, and a retry returns the first result instead of buying it again.

Idempotency-Key: nomi-request-983472

1–255 visible ASCII characters. Use one value per intent — a request id from your own system is ideal.

What it guarantees

You send	Apiosk does
The same key, the same body	Returns the same run. Pays at most once.
The same key, a different body	`409 idempotency_conflict`. Nothing is charged.
No key	Every call is a new request, and a retry is a second purchase.

Keys are scoped to the calling API key and the logical operation. Two keys, or two different source operations, can use the same string without colliding. The v1 and v2 direct-call path aliases identify the same logical operation.

Where it applies

Endpoint	Behaviour
`POST /v1/execute/{source}/{operation}`	Honours `Idempotency-Key`
`POST /v2/sources/{source_id}/run`	Honours `Idempotency-Key`
`POST /v2/ask` (question)	Free discovery; retries may reflect a refreshed catalogue
`POST /v2/execute` (selected API)	Requires `Idempotency-Key`; same selection/input recovers one purchase
`POST /v2/ask/plan` and workflow Ask	Honours `Idempotency-Key`; a retry returns the same plan or run
`POST /v2/asks/{id}/run`	Idempotent by itself — an ask runs once, key or no key
`POST /v2/asks/{id}/continue`	Requires `Idempotency-Key`; same state/action/input resumes the same run. `limit` and `wait_seconds` may change.

Continuations without a key are refused. Their keys are scoped to the calling key and task. Keep the original signed state when retrying the same choice; use a new idempotency key for a newly reviewed action.

Retrying in practice

key="nomi-request-983472"
curl https://gateway.apiosk.com/v1/execute/kvk-dutch-business-register/company_registry.search \
  -H "Authorization: Bearer $APIOSK_KEY" \
  -H "Idempotency-Key: $key" \
  -H "Content-Type: application/json" \
  -d '{"company.name":"Mollie B.V."}'

If that call times out on your side, send it again unchanged. You get the same run id, the same result and the same single charge.

While the first request is still running, a retry answers 409 request_in_progress with a retry_after_ms. Wait that long and retry; it is not an error, and nothing was charged twice.

Runs already in flight

A run that is still executing answers 202 with its id. Polling GET /v2/runs/{id} is always free and never starts anything new.

Buy data

Use cases

Operating it

API Reference

Ask

What it guarantees

Where it applies

Retrying in practice

Runs already in flight

​What it guarantees

​Where it applies

​Retrying in practice

​Runs already in flight

What it guarantees

Where it applies

Retrying in practice

Runs already in flight