Reliable requests

Agent work can take longer than one HTTP connection. Use the run ID as the durable handle for the work.

Prevent duplicate work

Send an Idempotency-Key with POST /v1/runs, file uploads, and cancellation requests.

Idempotency-Key: customer-order-4821-review

Store the key with your local operation. Use the same key and body after a network failure.

Retrieve accepted work

A run request can return 202. Read the run URL from location and wait for retry-after seconds.

curl https://api.simpleserve.ai/v1/runs/run_01JXYZ1234567890 \
  -H "Authorization: Bearer $SIMPLESERVE_API_KEY"

Stop polling when the status is completed, limit_reached, cancelled, or failed.

Resume a stream

Save the latest SSE event ID. Send it as Last-Event-ID when you reconnect.

Last-Event-ID: evt_01JXYZ1234567890

Trace a request

Every response includes x-request-id. Log it with the run ID and idempotency key.