Developers

Idempotency

Every write endpoint requires an Idempotency-Key header. It is the single most important thing keeping retries from double-posting on your channels.

What to send

A client-generated unique string — a UUIDv4 is the best default.

bash
curl -X POST https://postme.live/api/v1/posts \
  -H "Authorization: Bearer pml_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '...'

Length: 8–200 characters. Must be unique per logical request — reuse the same key only when retrying that exact request.

How replays behave

  • Same key + same body — server returns the original response (same status code, same JSON body) without re-executing the request. Cached for 24 hours.
  • Same key + different body — server returns 409 idempotency_conflict. Pick a fresh key for the new request.
  • Missing key on a POST — server returns 400 invalid_request.

Suggested patterns

Manual scripts. Generate one key per intended post.

AI agents / workflows. Use a deterministic key derived from your internal job id, e.g. job_abc123-v1. If the agent crashes and retries, the same job id produces the same key, which deduplicates the request automatically.

Long backfills. Use one key per row, not per batch — a partial failure mid-batch can otherwise hand you a conflict you can't cleanly recover from.

Idempotency — Public API