Idempotency

Networks fail. If your request to create a post times out, you can’t tell whether it went through. Send an Idempotency-Key header and you can simply retry: the same key always returns the same post.

curl https://socialhelper.app/api/v1/posts \
  -H "Authorization: Bearer $SOCIALHELPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
      "text": "We just shipped dark mode. Try it tonight 🌙",
      "accounts": [
          "ACCOUNT_ID_1",
          "ACCOUNT_ID_2"
      ]
  }'

How it works

• The first request with a key creates the post and returns 201.
• Any later request with the same key, from the same workspace, returns that same post with 200, and nothing new is posted. This holds even if two requests race each other.
• Keys are remembered for as long as the post exists, with no expiry.
• The request body isn’t compared. A reused key returns the original post even if the body is different, so use a new key (a UUID works well) for every new post.
• Only creating a post reads the header. Other endpoints ignore it.

From an AI agent

The MCP tool create_post takes the same thing as an idempotency_key argument.

Beyond your request

Idempotency covers your call to SocialHelper. SocialHelper’s own call to each platform is protected separately: it retries only when nothing was published, and when a platform’s answer is unclear it checks for the post before trying again, or stops. See Retries never post twice.