Posting

Idempotency

Network calls fail halfway. Send an Idempotency-Key on POST /posts and a retry cannot double-post.

#How it works

The first request with a given key stores its response under that key. Any later request with the same key and the same body replays that stored response verbatim, without posting again.

curl -X POST "https://api.yeetpost.com/api/v2/posts" \
  -H "x-api-key: $YEETPOST_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "text": "shipped the new api docs today",
  "connectionSlugs": [
    "linkedin",
    "x"
  ]
}'

The header is optional. Without it, POST /posts behaves normally and a retry posts again.

#The three outcomes

Same key, same body: the stored response is replayed. Nothing is posted again.
Same key, different body: 409 idempotency_key_conflict. One key, one answer.
Same key while the first request is still running: also 409, so two racing retries cannot both post.

409

{
  "error": "idempotency_key_conflict",
  "message": "This Idempotency-Key was already used with a different request body."
}

409

{
  "error": "idempotency_key_conflict",
  "message": "A request with this Idempotency-Key is already in progress."
}

#Choosing a key

A key of your choosing, 1 to 255 characters, that makes this request safe to retry. A uuid per logical post works well. Reusing a key with a different body is a 409.

Keys are scoped to your account, not to a single API key, are 1 to 255 characters, and expire after 24 hours. Error responses are stored too: if the first attempt came back 400, the retry gets that same 400.

A uuid per logical post works well. So does a stable name for the thing you are announcing, such as release-v2.4.0-announcement: it makes a retry from a different process safe as well.

#What is not idempotent

The one-liner POST /post/{connectionSlug} does not take the header. If you need retry safety, use POST /posts. See posting for the difference between the two.