Reference

Idempotency

Write endpoints support an Idempotency-Key header so you can safely retry requests without creating duplicate posts or schedules.

How it works

When you send a write request with an Idempotency-Key header, SocialSpool checks whether that key has been seen before for this workspace. If the key is new, the request proceeds and the response is cached. If the key was already used with the same request body, the cached response is returned without executing the operation again.

The cache lasts for 24 hours from the first request. After that, the same key can be reused for a new request.

Using idempotency keys

Add the Idempotency-Key header to any write request:

curl -X POST "$SOCIALSPOOL_BASE_URL/api/v1/posts" \
  -H "Authorization: Bearer $SOCIALSPOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: post-2026-06-02-001" \
  -d '{
    "content": "Scheduled from the SocialSpool API",
    "social_account_ids": ["SOCIAL_ACCOUNT_ID"],
    "publish_at": "2026-06-02T15:00:00Z"
  }'
Key guidelines
  • Keys must be unique strings. Use a UUID or a deterministic value derived from the operation (e.g. schedule-post_01HZ...).
  • The same key paired with a different request body returns 409 Conflict.
  • GET requests are already idempotent by nature and do not require an idempotency key.
  • Always include an idempotency key for POST, PATCH, and DELETE requests, especially when you plan to retry on network errors or timeouts.