Idempotency

Send an Idempotency-Key header on any billable request. If the request is repeated with the same key — because your process crashed, your load balancer retried, or your job runner is at-least-once — we replay the original result and charge nothing the second time.

curl -X POST 'https://api.boardwalkai.com/api/v1/projects/ai-search/jobs' \
  -H 'Authorization: Bearer bwk_live_YOUR_KEY' \
  -H 'Idempotency-Key: nightly-utah-pull-2026-08-02' \
  -H 'Content-Type: application/json' \
  -d '{"query":"projects with unresolved traffic concerns","stateIds":[1],"limit":50}'

The rules

• Keys are scoped to the credit pool, so a teammate cannot collide with your key by accident and cannot replay your result either.
• Reusing a key with a different request body or filter set is 409 idempotency_key_reuse. Replaying is safe; changing the request under the key is not.
• Reusing a key while the first request is still running is 409 idempotency_in_flight with a Retry-After. Do not fan out the same key in parallel — the whole point is that only one of them charges.
• Accepted key characters are A-Z a-z 0-9 _ . : -, up to 255 — the same grammar as X-Request-Id, so there is one rule to learn.

Where it matters most

On POST /projects/ai-search/jobs. That route reserves credits up front for the effective limit (default 10, max 100). On completion it charges 1 credit per delivered record and refunds the unused portion. Failures refund the full reservation. Charge-exempt / unlimited pools may show creditsReserved: 0; always trust meta.creditsUsed on completed responses for what was actually spent. Two identical submits without an idempotency key can hold the whole pool while both run — with a key, the retry replays the same job instead of queueing a second one.