Pagination and idempotency

PaginationCopy Anchor Link

Lists take limit and offset query parameters and answer one envelope:

{ "data": [], "has_more": true, "limit": 50, "offset": 0 }

While has_more is true, request the next page with offset + limit:

curl "https://api.stacksync.com/v1/workspaces/1234/queues?region=usnv&limit=50&offset=50" \
  -H "Authorization: Bearer $STACKSYNC_API_KEY"

The sync lists (syncs, sync triggers, sync webhooks and sync issues) predate this convention and page their own way: each one's page shows its parameters and answer.

IdempotencyCopy Anchor Link

Create operations accept an Idempotency-Key header, so a retry after a timeout or a dropped connection never creates the resource twice:

curl -X POST "https://api.stacksync.com/v1/workspaces/1234/queues?region=usnv" \
  -H "Authorization: Bearer $STACKSYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a1e-orders-queue" \
  -d '{ "queue_name": "Orders", "flush_batch_size": 100, "flush_record_max_age": 60 }'

• The key is 1 to 255 visible ASCII characters. A UUID per logical request works well.
• For 24 hours, a retry with the same key and the same request creates nothing and answers the first result again, with the header Idempotent-Replayed: true.
• The same key with a different request answers 422.
• A retry while the first request is still running answers 409: wait, then retry.

An operation accepts the header when its page lists Idempotency-Key under its header parameters.

Validate a writeCopy Anchor Link

Write operations that list validate_only in their request body run every check of the write without writing anything. With "validate_only": true, a valid request answers 204 with no body, and an invalid one answers the error the write would. Use it to check a request before you send it for real. A few operations answer a check result instead of 204; their page shows it.