Idempotency

Idempotency lets a caller retry a mutating request without accidentally creating duplicate work.

DevDocs should support idempotency for operations such as:

• creating a site
• requesting a preview release
• promoting a release
• attaching a domain
• importing an OpenAPI specification
• creating a playground share link

Request pattern

Idempotency-Key: 0f326a1e-7b72-4d21-9ec0-5035b6424c3d

The server should return the same result for the same key and compatible request body.

Conflict behavior

If the same key is reused with a different request body, the API should return a conflict instead of guessing which action the caller intended.

{
  "error": {
    "code": "idempotency_key_conflict",
    "message": "This key was already used with a different request body.",
    "retryable": false
  }
}

Playground behavior

The playground should show idempotency keys for mutating examples and make it clear when a generated request can be safely retried.