Skip to content
Relay Port

Solutions

Retries your agent can make safely.

Let an agent publish to Instagram with retries that cannot double up.

A workflow

How it goes, step by step.

  1. 01The agent calls POST /posts with an Idempotency-Key it creates once for each post it means to make.
  2. 02If the call times out, the agent repeats the same request with the same key and receives the same post.
  3. 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.
  4. 04The agent reads GET /posts/{id}. Every target says published, failed, or unconfirmed with the evidence we gathered.
  5. 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" }
    ]
  }'

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).