Solutions
Retries your agent can make safely.
Let an agent publish to Instagram with retries that cannot double up.
An agent that drafts and schedules posts will retry. Networks drop, tools time out, and a model may call the same function twice. Relay Port is built so that a retry returns the same post, a repeated post is refused, and a platform answer that is unclear is reported as such.
Read idempotency and duplicates for every case, and unconfirmed targets for what the agent should do when we cannot tell what happened.
A workflow
How it goes, step by step.
- 01The agent calls POST /posts with an Idempotency-Key it creates once for each post it means to make.
- 02If the call times out, the agent repeats the same request with the same key and receives the same post.
- 03If the same content already went to that account in the last 24 hours, the call is refused with 409 DuplicateContent unless the agent sets allowDuplicate.
- 04The agent reads GET /posts/{id}. Every target says published, failed, or unconfirmed with the evidence we gathered.
- 05A target that is unconfirmed goes to a person, or the agent checks the account. Retrying it with includeUnconfirmed is a choice made after looking.
Create a post
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" }
]
}'const apiKey = "YOUR_API_KEY";
const res = await fetch("https://api.relayport.dev/posts", {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
"Idempotency-Key": "winter-menu-2026-12-01",
},
body: JSON.stringify({
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" },
],
}),
});
const { data: post } = await res.json();import os, requests
key = os.environ["RELAYPORT_API_KEY"]
res = requests.post(
"https://api.relayport.dev/posts",
headers={
"Authorization": f"Bearer {key}",
"Idempotency-Key": "winter-menu-2026-12-01",
},
json={
"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" },
],
},
)
post = res.json()["data"]Response201 Created
{
"data": {
"id": "0193d2a4-6b1e-7c3f-8a92-4f1e2d3c5b60",
"brandId": "0193c8d0-2f6a-7a11-9c04-1b2a3c4d5e60",
"status": "scheduled",
"mode": "schedule",
"text": "Our winter menu is here.",
"title": null,
"firstComment": null,
"scheduledAt": "2026-12-01T00:00:00.000Z",
"queueId": null,
"revision": 1,
"source": "api",
"media": [
{
"mediaId": "0193d29f-0c4a-7e21-a5b8-2c9d8e7f6a01",
"position": 0
},
{
"mediaId": "0193d29f-0c4a-7e22-b6c9-3d0e9f8a7b02",
"position": 1
}
],
"platformData": { "instagram": { "contentType": "carousel" } },
"stagger": null,
"metadata": {},
"targets": [
{
"id": "0193d2a4-6b1f-7d40-9b13-5e2f3a4c6d71",
"accountId": "0193c8e1-77a2-7b05-8d14-6a5b4c3d2e10",
"platform": "instagram",
"status": "scheduled",
"dueAt": "2026-12-01T00:00:00.000Z",
"leadMs": 120000,
"platformPostId": null,
"permalink": null,
"permalinkPending": false,
"publishedAt": null,
"publishedLateMs": null,
"error": null,
"reconciliation": null,
"revision": 1
},
{
"id": "0193d2a4-6b1f-7d41-a024-6f3a4b5c7e82",
"accountId": "0193c8e1-77a2-7b06-9e25-7b6c5d4e3f21",
"platform": "instagram",
"status": "scheduled",
"dueAt": "2026-12-01T00:00:00.000Z",
"leadMs": 120000,
"platformPostId": null,
"permalink": null,
"permalinkPending": false,
"publishedAt": null,
"publishedLateMs": null,
"error": null,
"reconciliation": null,
"revision": 1
}
],
"warnings": [],
"createdAt": "2026-11-30T23:51:20.000Z"
}
}Questions
- What keeps a retry from posting twice?
- Three things. A repeated call with the same Idempotency-Key returns the same post. Identical content to the same account within 24 hours is refused unless the caller opts in. And we make the platform's publish call at most once per target revision on our own, so a retry on our side never sends it again.
- Can I limit what the agent is allowed to do?
- Yes. Create an API key with only the scopes the agent needs, for example posts:write and posts:read, and restrict it to one brand if you want.
- Can the agent practice without publishing?
- Yes. A sandbox account runs the same publish flow without calling Instagram. See [Sandbox](/docs/sandbox).