Make post creation safe to retry with idempotencyKey.
Network errors and timeouts happen. If you resend a POST /v1/posts after a timeout you cannot tell whether the
first attempt went through. Send an idempotencyKey and BetterPost guarantees the post is created (and charged)
at most once.
curl -s -X POST https://api.betterpost.dev/v1/posts \
-H "x-access-key: $BETTERPOST_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "Once only",
"platforms": [{ "platform": "linkedin", "accountId": "acc_5l1n7k3j9h2g8f4d6s0a1q3w" }],
"publishNow": true,
"idempotencyKey": "launch-2026-10-21-linkedin"
}'order-1234-announcement), works well.202.200
with the post's current result in the same shape as the original response (success, status, postId,
platforms). If the post was still publishing the first time, the replay shows how it ended.202, the other 200, and the
post is charged once.400) or credits (402) creates nothing, so its key stays unused.Idempotency keys apply to POST /v1/posts (and the MCP create_post tool). For the other write endpoints:
PUT and PATCH set a state, so repeating them gives the same result.DELETE returns 404 once the resource is gone.POST /v1/posts/{id}/retry while the first retry runs returns 409 post_publishing, and after it
succeeds returns 400 no_failed_targets. Only targets that failed again are retried (and charged) again.POST endpoints create free resources (profiles, webhook subscriptions, upload URLs).