Skip to content
Relay Port

Get started

Quickstart

Create an API key, connect an account and schedule your first post with one request, then follow every target to its receipt.

Relay Port publishes to social networks through one REST API. You send a post once, with one target per connected account, and you get a receipt for every target: when it went out and its permalink, or why it did not.

1. Create an API key

Sign in to the Dashboard and create an API key. A key starts with rp_live_ for live data or rp_test_ for test data, and you send it as a bearer token on every request. Authentication lists the scopes a key can hold.

2. Connect an account

Instagram accounts are connected with Instagram's own sign-in, from the Dashboard or through a hosted connect link that you send to your customer. To try the API before you connect anything, use a test key and a sandbox account: it publishes nowhere and settles every post at once.

3. Schedule a post

POST /posts creates one post with a target per account. The mode is explicit: draft, schedule, publish_now or queue. Send an Idempotency-Key header, so that a retried request returns the same post instead of creating a second one. The same request in each language:

cURL

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" }
    ]
  }'

TypeScript

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();

Python

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"]

Response

The answer is 201 Created with the post and one target per account:

{
  "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"
  }
}

4. Follow what happened

Each target moves from scheduled to publishing, then to published, failed or unconfirmed. Read the state of every target with GET /posts/{id}, read each step it went through with GET /posts/{id}/events, or subscribe a webhook endpoint to the post.* events and get told.

A published target carries the platform's post id and its permalink. A failed one carries an error with a message and the action to take. An unconfirmed one carries the evidence of what was checked: read Unconfirmed targets before you retry it.

Next steps