AiPSEO API

Idempotency

Supported mutations accept an optional Idempotency-Key so reviewed clients can retry without creating duplicate resources.

Supported operations

  • POST /v1/qr
  • POST /v1/agents
  • PUT /v1/qr/{short_id}/agent
  • DELETE /v1/qr/{short_id}/agent

Key grammar: [A-Za-z0-9._:-]{1,128}. API keys and authorization headers are never part of the fingerprint.

Replay behavior

  • Exact replay returns the persisted safe result with Idempotency-Replayed: true.
  • Same key, different fingerprint → 409 IDEMPOTENCY_CONFLICT.
  • In-progress claim → IDEMPOTENCY_IN_PROGRESS with Retry-After.

Binding mutations that also require If-Match-Version include the normalized version in the fingerprint.

Not covered

QR metadata update/deactivate and PUT /v1/qr/{short_id}/paywall are not covered by idempotency middleware today. Do not document them as replay-safe.