Skip to main content

Start an AI tool run

POST 
/api/tools/:module/runs

Doc 97 §13. Multipart: the photo, the profile slug, YOUR reference for the end user (the per-person daily limit counts by it), and — when the profile requires consent — the version of the consent text your app showed and the person accepted (your attestation). The run is queued and records surface = api; it passes the same gates, limits, wallet and metering as any other run. A gate refusal is still 201, with status = refused and error_code.

Subscribe a webhook endpoint to tool_run.completed / tool_run.failed to be told when it finishes, or poll GET /api/tools/runs/{run}.

Retries — Idempotency-Key. Send a unique key (a UUID) with each new run and the SAME key when you retry it. A retry with the same key, the same server key and the same body returns the original response — same status, same body, header Idempotent-Replayed: true — and starts (and charges) nothing new. The same key with a different body is 409 idempotency_key_reused; while the first request is still being processed, 409 idempotency_key_in_progress (retry after Retry-After). Keys are scoped per server key and kept for 24 hours. Only a response that created a run is kept: an error before any run existed (e.g. 409 consent_required, 422) leaves the key free for the corrected request.

Request​

Responses​

The run (pending, or refused by a gate). On an idempotent replay, the original response.

Response Headers
    Idempotent-Replayed

    true when this is the stored response of an earlier request with the same Idempotency-Key.