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
- Scheduling: times, time zones, queues and stagger.
- Idempotency and duplicates: what makes a retry safe.
- Errors: every error code, what it means and how to fix it.
- API reference: every operation, generated from the OpenAPI document.