Publishing
Idempotency and duplicates
The four guarantees that make retries safe, how idempotency keys behave in every case, and the 24-hour duplicate guard.
Networks fail and clients retry. Relay Port is built so that a retry does not turn into a second post. It makes four guarantees, and nothing more:
- One publish call per target revision. Relay Port makes the platform's publish call at most once per target revision on its own.
- Idempotency keys. A repeated API call with the same
Idempotency-Keyreturns the same post. - A duplicate guard. Identical content to the same account within 24 hours is refused unless you opt in.
- Unconfirmed, with evidence. When a platform's answer is ambiguous, the target becomes
unconfirmedwith the evidence attached.
In one sentence: we never send the same post twice on our own, and we tell you when a platform's response is ambiguous.
Idempotency keys
Send an Idempotency-Key header with a value of 1 to 255 characters on the requests that create something. The reference marks every operation that accepts one. Use a new value, such as a UUID, for each new request, and the same value only to repeat that request.
curl -X POST https://api.relayport.dev/posts \
-H "Authorization: Bearer $RELAYPORT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: winter-menu-2026-12-01" \
-d '{
"mode": "schedule",
"scheduledAt": "2026-12-01T09:00:00+09:00",
"text": "Our winter menu is here.",
"media": [
{ "mediaId": "0193d29f-0c4a-7e21-a5b8-2c9d8e7f6a01" },
{ "mediaId": "0193d29f-0c4a-7e22-b6c9-3d0e9f8a7b02" }
],
"platformData": { "instagram": { "contentType": "carousel" } },
"targets": [
{ "accountId": "0193c8e1-77a2-7b05-8d14-6a5b4c3d2e10" },
{ "accountId": "0193c8e1-77a2-7b06-9e25-7b6c5d4e3f21" }
]
}'
| Case | Answer |
|---|---|
| The first request with a key | It runs. A successful answer is kept for 24 hours. |
| The same key with the same request | The kept answer again, with the header Idempotent-Replayed: true. Nothing runs twice. |
| The same key with different parameters | 422 IdempotencyKeyReused. |
| The same key while the first request still runs | 409 IdempotencyInProgress with Retry-After. Wait, then repeat the request with the same key. |
| The first request failed | Nothing is kept, so the same key can run again once you fix the request. |
Keys belong to the workspace, and a key used by one credential cannot be replayed by another.
The duplicate guard
If the same account received identical text and media in the last 24 hours, POST /posts answers 409 DuplicateContent. Send allowDuplicate: true when you mean to post the same content again. Together with idempotency keys, this is what makes it safe for your code, or an agent acting for you, to retry: a repeated call returns the same post or is refused.
Retrying safely
- A network error while creating a post: send the same request again with the same
Idempotency-Key. - A
failedtarget:POST /posts/{id}/retryre-arms the failed targets as a new revision. A failed target never reached the platform's feed, so a retry is safe. - An
unconfirmedtarget may already be live. It is retried only when you sendincludeUnconfirmed: true, and only after you check the account: see Unconfirmed targets.