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","states":["UT"],"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 against your requested limit, so two identical submits can hold the whole pool while both run. With an idempotency key, the retry replays the same job instead of queueing a second one.