Runs

Create Run (Async)

Direkomendasikan: JSON body dengan input_documents berisi document ID yang sudah di-upload lewat alur presigned (POST /v1/documents → PUT → /complete). Tidak ada batas ukuran selain batas presigned upload itu sendiri.

curl -X POST https://api.kakak.dev/v1/workflows/wf_7Gk2Qp/runs \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"mode":"async","input_documents":["doc_Z4n8Wd"],"metadata":{"key":"value"}}'

Response 202 Accepted dengan run_* ID. Status awal: queued.

Legacy (deprecation window): multipart files[] untuk upload inline masih diterima, tapi dibatasi 4MB total per request (bukan 50MB) — Vercel Function membatasi ukuran body request ke ~4.5MB terlepas dari content-type, jadi file yang lebih besar tidak akan pernah sampai ke server. Untuk file >4MB, gunakan alur presigned di atas.

curl -X POST https://api.kakak.dev/v1/workflows/wf_7Gk2Qp/runs \
  -H "Authorization: Bearer $KEY" \
  -F "mode=async" \
  -F "files[]=@small-doc.pdf" \
  -F 'metadata={"key":"value"}'

Sync Mode (v1)

"mode":"sync" — evaluasi dijalankan inline. Response 200 OK dengan output langsung. Bounded oleh function timeout.

curl -X POST https://api.kakak.dev/v1/workflows/wf_7Gk2Qp/runs \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"sync","input_documents":["doc_Z4n8Wd"]}'

State Machine

queuedrunningsucceededfailedcanceledrefunded

queued → running → succeeded (normal). Failed runs: full refund. Canceled queued runs: full refund.

Endpoints

Idempotency

Gunakan Idempotency-Key header (UUID). Same key + same body → replay response. Same key + different body → 409 idempotency_conflict. Same key + same body while the first request is still running → 409 idempotency_key_in_use (retry later; you will get the original response, and no second run is created or billed). Failed requests are not cached, so retrying one with the same key runs it again. Keys retained 24h.