API documentation

Idempotency

The Demarky API supports optional idempotency for POST and PATCH requests, ensuring that the same request can be safely retried without causing duplicate side effects.

Idempotency-Key header

Include the Idempotency-Key header with a unique string to enable idempotent request handling:

curl -X POST https://api.demarky.ai/v1/accounts/acct_0123456789abcdefghjkmnpqrs/pages \
  -H "Authorization: Bearer dmk_at_live_xxx" \
  -H "Idempotency-Key: my-unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{"product": {"title": "My Product", "price": 99, "product_type": "physical"}}'

Behavior

Scenario	Response
First request with key	Request is processed normally
Retry with same key and body	Previous response is replayed (status code and body) — includes `Idempotent-Replayed: true` header
Retry with same key and different body	`409 Conflict` — `conflict` error code
Concurrent request with same key	`409 Conflict` — `conflict` error code with "already in progress" message
No `Idempotency-Key` header	Request is processed normally (no deduplication)

Retention

Cached idempotent responses are retained for 24 hours. After this period, the key can be reused for a new request.

Limitations

Only supported for POST and PATCH methods.
Idempotency-Key must be 255 characters or fewer.
Only applicable to authenticated requests (requires an access token).