Skip to main content

​
Idempotency

All POST and PATCH mutation endpoints accept an optional Idempotency-Key header.

​
When to send it

Use an idempotency key when:
  • A client may retry after a transport failure.
  • A queue worker may dispatch the same logical operation more than once.
  • An AI agent may re-run a mutation after partial progress or tool retries.
  • Generate one stable key per logical mutation.
  • Reuse the same key for retries of that mutation.
  • Change the key when the intended mutation changes.

​
Examples

Idempotency-Key: create-project-song-1

Idempotency-Key: export-song-1

​
Good boundaries

  • One key for creating a project.
  • A different key for exporting that project.
  • A different key again for updating project settings.
This keeps retries safe without accidentally deduplicating unrelated work.