Documentation Index
Fetch the complete documentation index at: https://docs.katalo.ai/llms.txt
Use this file to discover all available pages before exploring further.
Replay-safe writes
Every write endpoint requires anIdempotency-Key. Reusing the same key with the same payload is safe. Reusing it with a different payload is not.
| Behavior | Result |
|---|---|
| Same key, same payload | Returns the original job instead of creating a duplicate write. |
| Same key, different payload | Returns 409 idempotency_conflict. |
| Retention window | Idempotency records are retained for 24 hours. |
Rate limits and concurrency
The API applies layered limits per key, per organization, and in some cases per IP. Limit checks happen before expensive work starts.| Route | Limit |
|---|---|
POST /api/v1/source-assets | Per-key and per-organization write limits. |
GET /api/v1/source-assets/{ingest_id} | Read limits for polling source ingest state. |
POST /api/v1/generations | Per-key and per-organization write limits. |
GET /api/v1/generations/{job_id} | Read limits for polling and recovery. |
POST /api/v1/generations/{job_id}/regenerate | Write limits plus organization in-flight job caps. |
GET /api/v1/usage/summary | Read limits for reporting. |
GET /api/v1/billing/events | Read limits for ledger export. |
The organization-wide in-flight cap is 50 simultaneous generation jobs.
Retry strategy
- Retry
429responses after at least the advertisedretry_aftervalue. - Retry retryable
5xxresponses with exponential backoff and jitter. - Keep the same idempotency key when repeating the same write.
- Do not blindly retry validation, authorization, entitlement, or idempotency conflict errors.
Signed URLs are temporary
Returned output URLs are intentionally short-lived. API responses also sendCache-Control: no-store so clients always read fresh job and billing state.
Re-read the job if a signed output URL has expired. Do not assume the first URL returned for a job remains valid for the lifetime of your workflow.