Guides

Idempotency

Add an Idempotency-Key header to POST /v1/posts, POST /v1/media and POST /v1/connect-links. Use any 1 to 255 printable characters, like an order id or a UUID.

The same key from the same API key within 24 hours returns the first answer, with Idempotent-Replayed: true.
The same key with a different body answers 409 idempotency_conflict.
While the first request is still running, a second one also gets 409 idempotency_conflict; try again in a moment.
After a 500 the key is free again, so the retry runs.
Connect links: the replay gives the same link with a new url; the first one stops working.

curl https://hivepost.app/v1/posts \ -H "Authorization: Bearer $HIVEPOST_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: my-first-post" \ -d '{ "accounts": ["5ae80ed0-bdfd-4c62-a715-be5d8b8a9d37"], "text": "Pearl white, ready to fit.", "media": [ { "url": "https://cdn.example.com/IMG_4821.jpg" } ], "publish_at": "2026-11-12T10:00:00+02:00" }'

import os import requests res = requests.post( "https://hivepost.app/v1/posts", headers={ "Authorization": f"Bearer {os.environ['HIVEPOST_API_KEY']}", "Idempotency-Key": "my-first-post", }, json={ "accounts": ["5ae80ed0-bdfd-4c62-a715-be5d8b8a9d37"], "text": "Pearl white, ready to fit.", "media": [ { "url": "https://cdn.example.com/IMG_4821.jpg", }, ], "publish_at": "2026-11-12T10:00:00+02:00", }, ) print(res.status_code, res.json())

{ "error": { "code": "idempotency_conflict", "message": "This Idempotency-Key was already used for a different request.", "docs": "https://hivepost.app/docs/errors#idempotency_conflict" } }