Getting started

Idempotency & safe retries

Send a stable Idempotency-Key on every create-post request so a network timeout and a naive retry never double-post to a customer’s real social accounts.

Endpoint summary

All operations in this resource, with the minimum accepted key scope.

Method & endpointPurposeScope

POST/api/posts

Accepts an Idempotency-Key header for safe retries

publish

Why idempotency matters for a publishing API

Most APIs treat a retried write as a minor annoyance — an extra database row, cleaned up later. A publishing API is different: a retried POST /api/posts after a dropped connection can mean the same launch announcement goes out twice on a customer’s Instagram and LinkedIn. PostGate lets you retry the exact same logical request safely by reusing one Idempotency-Key.

Timeouts do not mean the request failed

A client-side timeout only means you stopped waiting for a response. The post may already be queued. Retry with the same key instead of assuming nothing happened.

Send a stable Idempotency-Key

Pass the header on every create-post call. If PostGate has already accepted a request with that key, it returns the original response instead of creating a second post.

Retry-safe post creationPostGate API

curl -X POST "https://postgate.studio/api/posts?profile_group_id=grp_acme123" \
  -H "Authorization: Bearer $POSTGATE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-post-001" \
  -d '{
    "post": { "body": "Launch day. 🚀" },
    "profiles": ["pro_instagram123", "pro_linkedin456"],
    "media": ["https://cdn.example.com/launch.jpg"]
  }'

Generate keys from your own request, not per attempt

A good key is stable for one logical publish and different for every distinct one — typically derived from your own internal job, queue message, or idempotent command ID, such as launch-post-{internal_job_id}. Generating a fresh random UUID on every retry defeats the purpose: PostGate would see each attempt as a brand-new request and could publish more than once.

Retention window and conflicting reuse

PostGate honors a key for 72 hours after it is first used. Retrying the identical request within that window returns the original post unchanged. Reusing the same key with different content — a different body, profiles, or media — is rejected with a 409 conflict instead of silently applying the new content, so a key collision can never overwrite what a customer already saw published.

Key reused with different contentPostGate API

{
  "error": {
    "code": "conflict",
    "message": "This idempotency key was already used with a different request.",
    "retryable": false,
    "request_id": "req_01JXYZ"
  }
}