Skip to content
Relay Port

API reference

Posts

Create, schedule, publish and follow posts, one target per connected account.

GET/posts

List posts

  • Scope posts:read

Newest first. Filter by status, brandId, accountId, platform, source and a created time range.

Request
curl https://api.relayport.dev/posts \
  -H "Authorization: Bearer $RELAYPORT_API_KEY"

Parameters

  • X-Api-Versionstringheader

    The API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.

    One of 2026-12-01

  • X-Workspace-Idstring (uuid)header

    The workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.

  • cursorstringquery

  • limitintegerquery

  • statusstringquery

    One of draft scheduled publishing published partial failed unconfirmed cancelled

  • brandIdstring (uuid)query

  • accountIdstring (uuid)query

  • platformstringquery

  • sourcestringquery

    One of dashboard api

  • fromstring (date-time)query

  • tostring (date-time)query

Responses

200OK
  • dataPost[]required

  • idstring (uuid)required

  • brandIdstring (uuid)required

  • statusstringrequired

    One of draft scheduled publishing published partial failed unconfirmed cancelled

  • modestringrequired

    One of draft schedule publish_now queue

  • textstringrequired

  • titlestring | nullrequired

  • firstCommentstring | nullrequired

  • scheduledAtstring (date-time) | nullrequired

  • queueIdstring (uuid) | nullrequired

  • revisionintegerrequired

  • sourcestringrequired

    One of dashboard api

  • mediaobject[]required

  • mediaIdstring (uuid)required

  • positionintegerrequired

  • platformDatamap of objectrequired

  • staggerobject | nullrequired

  • minSecondsintegerrequired

  • maxSecondsintegerrequired

  • metadatamap of string | number | boolean | nullrequired

  • targetsobject[]required

  • idstring (uuid)required

  • accountIdstring (uuid)required

  • platformstringrequired

  • statusstringrequired

    One of draft scheduled publishing published failed unconfirmed cancelled

  • dueAtstring (date-time) | nullrequired

  • leadMsintegerrequired

  • platformPostIdstring | nullrequired

  • permalinkstring | nullrequired

  • permalinkPendingbooleanrequired

  • publishedAtstring (date-time) | nullrequired

  • publishedLateMsinteger | nullrequired

  • errorobject | nullrequired

  • codestringrequired

  • messagestringrequired

  • actionstringrequired

  • retryByUserboolean

  • reconciliationobject | nullrequired

  • evidencestring[]required

  • revisionintegerrequired

  • warningsIssue[]required

  • severitystringrequired

    One of error warning

  • targetintegerrequired

  • platformstringrequired

  • fieldstringrequired

  • rulestringrequired

  • messagestringrequired

  • limitnumber

  • actualnumber | string

  • allowedstring

  • capabilitystring

    One of publishing.image publishing.carousel publishing.reel publishing.story publishing.collaborators publishing.alt_text publishing.user_tags publishing.location publishing.trial_reels publishing.ai_label publishing.first_comment publishing.delete publishing.resumable_upload publishing.partnership_label publishing.polls publishing.audio inbox.comments.read inbox.mentions inbox.dm.send inbox.private_reply analytics.post_metrics analytics.account_metrics analytics.story_insights_webhook ads.boost

  • statestring

    One of available reconnect_required requires_variant requires_connection plan_upgrade coming_soon unsupported

  • createdAtstring (date-time)required

  • metaPageMetarequired

  • next_cursorstring | nullrequired

  • per_pageintegerrequired

400WorkspaceRequired
401InvalidApiKeyUnauthenticated
403ForbiddenModuleNotAvailableWorkspaceSuspended
404NotFound
422ValidationError
429RateLimited
503RateLimiterUnavailable

POST/posts

Create a post

  • Scope posts:write
  • Idempotency-Key

One post with 1 to 20 targets, one per connected account, all in one brand. mode is explicit: draft (saved, not scheduled), schedule (scheduledAt, or a scheduledAt on every target), publish_now (answers 202; the key also needs posts:publish) or queue (queueId, a queue id or default; the chosen slot comes back in scheduledAt). Post-level platformData is keyed by platform and carries each platform's contentType and options; a target's platformData is flat and wins. An identical post to the same account within 24 hours is 409 DuplicateContent unless allowDuplicate is true. A blocked workspace (unpaid) cannot create posts, drafts included.

Request
curl -X POST https://api.relayport.dev/posts \
  -H "Authorization: Bearer $RELAYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "mode": "draft", "targets": [{ "accountId": "<uuid>" }] }'

Parameters

  • X-Api-Versionstringheader

    The API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.

    One of 2026-12-01

  • X-Workspace-Idstring (uuid)header

    The workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.

  • Idempotency-Keystringheader

    Repeating a request with the same key within 24 hours returns the first response (header Idempotent-Replayed: true) instead of running it again.

  • X-Requested-Withstringheader

    Required on every write made with a signed-in session; without it the request is 403 CsrfRejected. API keys do not send it.

    One of XMLHttpRequest

Request body

  • brandIdstring (uuid)

  • modestringrequired

    One of draft schedule publish_now queue

  • scheduledAtstring (date-time)

  • queueId"default" | string (uuid)

  • textstring

  • titlestring

  • mediaobject[]

  • mediaIdstring (uuid)required

  • platformDataobject

    Keyed by platform: each platform's contentType and options

  • instagramobject

  • contentTypestringrequired

    One of image carousel reel

  • collaboratorsstring[]

  • aiGeneratedboolean

  • sandboxobject

  • contentTypestringrequired

    One of image carousel

  • outcomestring

    One of published failed unconfirmed

  • failureCodestring

  • firstCommentstring

  • targetsobject[]required

  • accountIdstring (uuid)required

  • scheduledAtstring (date-time)

  • textstring

  • titlestring

  • mediaobject[]

  • mediaIdstring (uuid)required

  • firstCommentstring

  • platformDataobject | object

    Flat: the options of the target's own platform, and its contentType when it differs from the post's

  • staggerobject

  • minSecondsintegerrequired

  • maxSecondsintegerrequired

  • allowDuplicateboolean

  • metadatamap of string | number | boolean | null

Responses

201Created. draft, schedule and queue
  • dataPostrequired

  • idstring (uuid)required

  • brandIdstring (uuid)required

  • statusstringrequired

    One of draft scheduled publishing published partial failed unconfirmed cancelled

  • modestringrequired

    One of draft schedule publish_now queue

  • textstringrequired

  • titlestring | nullrequired

  • firstCommentstring | nullrequired

  • scheduledAtstring (date-time) | nullrequired

  • queueIdstring (uuid) | nullrequired

  • revisionintegerrequired

  • sourcestringrequired

    One of dashboard api

  • mediaobject[]required

  • mediaIdstring (uuid)required

  • positionintegerrequired

  • platformDatamap of objectrequired

  • staggerobject | nullrequired

  • minSecondsintegerrequired

  • maxSecondsintegerrequired

  • metadatamap of string | number | boolean | nullrequired

  • targetsobject[]required

  • idstring (uuid)required

  • accountIdstring (uuid)required

  • platformstringrequired

  • statusstringrequired

    One of draft scheduled publishing published failed unconfirmed cancelled

  • dueAtstring (date-time) | nullrequired

  • leadMsintegerrequired

  • platformPostIdstring | nullrequired

  • permalinkstring | nullrequired

  • permalinkPendingbooleanrequired

  • publishedAtstring (date-time) | nullrequired

  • publishedLateMsinteger | nullrequired

  • errorobject | nullrequired

  • codestringrequired

  • messagestringrequired

  • actionstringrequired

  • retryByUserboolean

  • reconciliationobject | nullrequired

  • evidencestring[]required

  • revisionintegerrequired

  • warningsIssue[]required

  • severitystringrequired

    One of error warning

  • targetintegerrequired

  • platformstringrequired

  • fieldstringrequired

  • rulestringrequired

  • messagestringrequired

  • limitnumber

  • actualnumber | string

  • allowedstring

  • capabilitystring

    One of publishing.image publishing.carousel publishing.reel publishing.story publishing.collaborators publishing.alt_text publishing.user_tags publishing.location publishing.trial_reels publishing.ai_label publishing.first_comment publishing.delete publishing.resumable_upload publishing.partnership_label publishing.polls publishing.audio inbox.comments.read inbox.mentions inbox.dm.send inbox.private_reply analytics.post_metrics analytics.account_metrics analytics.story_insights_webhook ads.boost

  • statestring

    One of available reconnect_required requires_variant requires_connection plan_upgrade coming_soon unsupported

  • createdAtstring (date-time)required

202Accepted. publish_now: the targets start publishing; follow them with GET /posts/{id} or the post.* events
  • dataPostrequired

  • idstring (uuid)required

  • brandIdstring (uuid)required

  • statusstringrequired

    One of draft scheduled publishing published partial failed unconfirmed cancelled

  • modestringrequired

    One of draft schedule publish_now queue

  • textstringrequired

  • titlestring | nullrequired

  • firstCommentstring | nullrequired

  • scheduledAtstring (date-time) | nullrequired

  • queueIdstring (uuid) | nullrequired

  • revisionintegerrequired

  • sourcestringrequired

    One of dashboard api

  • mediaobject[]required

  • mediaIdstring (uuid)required

  • positionintegerrequired

  • platformDatamap of objectrequired

  • staggerobject | nullrequired

  • minSecondsintegerrequired

  • maxSecondsintegerrequired

  • metadatamap of string | number | boolean | nullrequired

  • targetsobject[]required

  • idstring (uuid)required

  • accountIdstring (uuid)required

  • platformstringrequired

  • statusstringrequired

    One of draft scheduled publishing published failed unconfirmed cancelled

  • dueAtstring (date-time) | nullrequired

  • leadMsintegerrequired

  • platformPostIdstring | nullrequired

  • permalinkstring | nullrequired

  • permalinkPendingbooleanrequired

  • publishedAtstring (date-time) | nullrequired

  • publishedLateMsinteger | nullrequired

  • errorobject | nullrequired

  • codestringrequired

  • messagestringrequired

  • actionstringrequired

  • retryByUserboolean

  • reconciliationobject | nullrequired

  • evidencestring[]required

  • revisionintegerrequired

  • warningsIssue[]required

  • severitystringrequired

    One of error warning

  • targetintegerrequired

  • platformstringrequired

  • fieldstringrequired

  • rulestringrequired

  • messagestringrequired

  • limitnumber

  • actualnumber | string

  • allowedstring

  • capabilitystring

    One of publishing.image publishing.carousel publishing.reel publishing.story publishing.collaborators publishing.alt_text publishing.user_tags publishing.location publishing.trial_reels publishing.ai_label publishing.first_comment publishing.delete publishing.resumable_upload publishing.partnership_label publishing.polls publishing.audio inbox.comments.read inbox.mentions inbox.dm.send inbox.private_reply analytics.post_metrics analytics.account_metrics analytics.story_insights_webhook ads.boost

  • statestring

    One of available reconnect_required requires_variant requires_connection plan_upgrade coming_soon unsupported

  • createdAtstring (date-time)required

400InvalidJsonWorkspaceRequired
401InvalidApiKeyUnauthenticated
402PaymentRequiredPlanLimitReached
403CsrfRejectedForbiddenModuleNotAvailableWorkspaceSuspended
404NotFound
409ConflictDuplicateContentIdempotencyInProgress
413PayloadTooLarge
422IdempotencyKeyReusedPostValidationFailedValidationError
429RateLimited
503RateLimiterUnavailable

GET/posts/{id}

Get a post with the state of every target

  • Scope posts:read

Each target carries its status (draft, scheduled, publishing, published, failed, unconfirmed or cancelled), the platform post id and permalink once published, and the error with the action to take when it failed.

Request
curl https://api.relayport.dev/posts/{id} \
  -H "Authorization: Bearer $RELAYPORT_API_KEY"

Parameters

  • X-Api-Versionstringheader

    The API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.

    One of 2026-12-01

  • X-Workspace-Idstring (uuid)header

    The workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.

  • idstring (uuid)pathrequired

Responses

200OK
  • dataPostrequired

  • idstring (uuid)required

  • brandIdstring (uuid)required

  • statusstringrequired

    One of draft scheduled publishing published partial failed unconfirmed cancelled

  • modestringrequired

    One of draft schedule publish_now queue

  • textstringrequired

  • titlestring | nullrequired

  • firstCommentstring | nullrequired

  • scheduledAtstring (date-time) | nullrequired

  • queueIdstring (uuid) | nullrequired

  • revisionintegerrequired

  • sourcestringrequired

    One of dashboard api

  • mediaobject[]required

  • mediaIdstring (uuid)required

  • positionintegerrequired

  • platformDatamap of objectrequired

  • staggerobject | nullrequired

  • minSecondsintegerrequired

  • maxSecondsintegerrequired

  • metadatamap of string | number | boolean | nullrequired

  • targetsobject[]required

  • idstring (uuid)required

  • accountIdstring (uuid)required

  • platformstringrequired

  • statusstringrequired

    One of draft scheduled publishing published failed unconfirmed cancelled

  • dueAtstring (date-time) | nullrequired

  • leadMsintegerrequired

  • platformPostIdstring | nullrequired

  • permalinkstring | nullrequired

  • permalinkPendingbooleanrequired

  • publishedAtstring (date-time) | nullrequired

  • publishedLateMsinteger | nullrequired

  • errorobject | nullrequired

  • codestringrequired

  • messagestringrequired

  • actionstringrequired

  • retryByUserboolean

  • reconciliationobject | nullrequired

  • evidencestring[]required

  • revisionintegerrequired

  • warningsIssue[]required

  • severitystringrequired

    One of error warning

  • targetintegerrequired

  • platformstringrequired

  • fieldstringrequired

  • rulestringrequired

  • messagestringrequired

  • limitnumber

  • actualnumber | string

  • allowedstring

  • capabilitystring

    One of publishing.image publishing.carousel publishing.reel publishing.story publishing.collaborators publishing.alt_text publishing.user_tags publishing.location publishing.trial_reels publishing.ai_label publishing.first_comment publishing.delete publishing.resumable_upload publishing.partnership_label publishing.polls publishing.audio inbox.comments.read inbox.mentions inbox.dm.send inbox.private_reply analytics.post_metrics analytics.account_metrics analytics.story_insights_webhook ads.boost

  • statestring

    One of available reconnect_required requires_variant requires_connection plan_upgrade coming_soon unsupported

  • createdAtstring (date-time)required

400WorkspaceRequired
401InvalidApiKeyUnauthenticated
403ForbiddenModuleNotAvailableWorkspaceSuspended
404NotFound
422ValidationError
429RateLimited
503RateLimiterUnavailable

PATCH/posts/{id}

Update a draft or scheduled post

  • Scope posts:write

A draft can be promoted by setting mode schedule or queue. A post whose targets already started publishing is 409 PostStateConflict; an edit never re-sends a target that may have been sent.

Request
curl -X PATCH https://api.relayport.dev/posts/{id} \
  -H "Authorization: Bearer $RELAYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Parameters

  • X-Api-Versionstringheader

    The API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.

    One of 2026-12-01

  • X-Workspace-Idstring (uuid)header

    The workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.

  • X-Requested-Withstringheader

    Required on every write made with a signed-in session; without it the request is 403 CsrfRejected. API keys do not send it.

    One of XMLHttpRequest

  • idstring (uuid)pathrequired

Request body

  • modestring

    One of schedule queue

  • scheduledAtstring (date-time)

  • queueId"default" | string (uuid)

  • textstring

  • titlestring | null

  • mediaobject[]

  • mediaIdstring (uuid)required

  • platformDataobject

    Keyed by platform: each platform's contentType and options

  • instagramobject

  • contentTypestringrequired

    One of image carousel reel

  • collaboratorsstring[]

  • aiGeneratedboolean

  • sandboxobject

  • contentTypestringrequired

    One of image carousel

  • outcomestring

    One of published failed unconfirmed

  • failureCodestring

  • firstCommentstring | null

  • targetsobject[]

  • accountIdstring (uuid)required

  • scheduledAtstring (date-time)

  • textstring

  • titlestring

  • mediaobject[]

  • mediaIdstring (uuid)required

  • firstCommentstring

  • platformDataobject | object

    Flat: the options of the target's own platform, and its contentType when it differs from the post's

  • staggerobject

  • minSecondsintegerrequired

  • maxSecondsintegerrequired

  • allowDuplicateboolean

  • metadatamap of string | number | boolean | null

Responses

200OK
  • dataPostrequired

  • idstring (uuid)required

  • brandIdstring (uuid)required

  • statusstringrequired

    One of draft scheduled publishing published partial failed unconfirmed cancelled

  • modestringrequired

    One of draft schedule publish_now queue

  • textstringrequired

  • titlestring | nullrequired

  • firstCommentstring | nullrequired

  • scheduledAtstring (date-time) | nullrequired

  • queueIdstring (uuid) | nullrequired

  • revisionintegerrequired

  • sourcestringrequired

    One of dashboard api

  • mediaobject[]required

  • mediaIdstring (uuid)required

  • positionintegerrequired

  • platformDatamap of objectrequired

  • staggerobject | nullrequired

  • minSecondsintegerrequired

  • maxSecondsintegerrequired

  • metadatamap of string | number | boolean | nullrequired

  • targetsobject[]required

  • idstring (uuid)required

  • accountIdstring (uuid)required

  • platformstringrequired

  • statusstringrequired

    One of draft scheduled publishing published failed unconfirmed cancelled

  • dueAtstring (date-time) | nullrequired

  • leadMsintegerrequired

  • platformPostIdstring | nullrequired

  • permalinkstring | nullrequired

  • permalinkPendingbooleanrequired

  • publishedAtstring (date-time) | nullrequired

  • publishedLateMsinteger | nullrequired

  • errorobject | nullrequired

  • codestringrequired

  • messagestringrequired

  • actionstringrequired

  • retryByUserboolean

  • reconciliationobject | nullrequired

  • evidencestring[]required

  • revisionintegerrequired

  • warningsIssue[]required

  • severitystringrequired

    One of error warning

  • targetintegerrequired

  • platformstringrequired

  • fieldstringrequired

  • rulestringrequired

  • messagestringrequired

  • limitnumber

  • actualnumber | string

  • allowedstring

  • capabilitystring

    One of publishing.image publishing.carousel publishing.reel publishing.story publishing.collaborators publishing.alt_text publishing.user_tags publishing.location publishing.trial_reels publishing.ai_label publishing.first_comment publishing.delete publishing.resumable_upload publishing.partnership_label publishing.polls publishing.audio inbox.comments.read inbox.mentions inbox.dm.send inbox.private_reply analytics.post_metrics analytics.account_metrics analytics.story_insights_webhook ads.boost

  • statestring

    One of available reconnect_required requires_variant requires_connection plan_upgrade coming_soon unsupported

  • createdAtstring (date-time)required

400InvalidJsonWorkspaceRequired
401InvalidApiKeyUnauthenticated
402PaymentRequiredPlanLimitReached
403CsrfRejectedForbiddenModuleNotAvailableWorkspaceSuspended
404NotFound
409ConflictDuplicateContentPostStateConflict
422PostValidationFailedValidationError
429RateLimited
503RateLimiterUnavailable

DELETE/posts/{id}

Cancel a draft or scheduled post

  • Scope posts:write

Allowed until a target starts publishing; the post stays readable with status cancelled.

Request
curl -X DELETE https://api.relayport.dev/posts/{id} \
  -H "Authorization: Bearer $RELAYPORT_API_KEY"

Parameters

  • X-Api-Versionstringheader

    The API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.

    One of 2026-12-01

  • X-Workspace-Idstring (uuid)header

    The workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.

  • X-Requested-Withstringheader

    Required on every write made with a signed-in session; without it the request is 403 CsrfRejected. API keys do not send it.

    One of XMLHttpRequest

  • idstring (uuid)pathrequired

Responses

200OK
  • dataPostrequired

  • idstring (uuid)required

  • brandIdstring (uuid)required

  • statusstringrequired

    One of draft scheduled publishing published partial failed unconfirmed cancelled

  • modestringrequired

    One of draft schedule publish_now queue

  • textstringrequired

  • titlestring | nullrequired

  • firstCommentstring | nullrequired

  • scheduledAtstring (date-time) | nullrequired

  • queueIdstring (uuid) | nullrequired

  • revisionintegerrequired

  • sourcestringrequired

    One of dashboard api

  • mediaobject[]required

  • mediaIdstring (uuid)required

  • positionintegerrequired

  • platformDatamap of objectrequired

  • staggerobject | nullrequired

  • minSecondsintegerrequired

  • maxSecondsintegerrequired

  • metadatamap of string | number | boolean | nullrequired

  • targetsobject[]required

  • idstring (uuid)required

  • accountIdstring (uuid)required

  • platformstringrequired

  • statusstringrequired

    One of draft scheduled publishing published failed unconfirmed cancelled

  • dueAtstring (date-time) | nullrequired

  • leadMsintegerrequired

  • platformPostIdstring | nullrequired

  • permalinkstring | nullrequired

  • permalinkPendingbooleanrequired

  • publishedAtstring (date-time) | nullrequired

  • publishedLateMsinteger | nullrequired

  • errorobject | nullrequired

  • codestringrequired

  • messagestringrequired

  • actionstringrequired

  • retryByUserboolean

  • reconciliationobject | nullrequired

  • evidencestring[]required

  • revisionintegerrequired

  • warningsIssue[]required

  • severitystringrequired

    One of error warning

  • targetintegerrequired

  • platformstringrequired

  • fieldstringrequired

  • rulestringrequired

  • messagestringrequired

  • limitnumber

  • actualnumber | string

  • allowedstring

  • capabilitystring

    One of publishing.image publishing.carousel publishing.reel publishing.story publishing.collaborators publishing.alt_text publishing.user_tags publishing.location publishing.trial_reels publishing.ai_label publishing.first_comment publishing.delete publishing.resumable_upload publishing.partnership_label publishing.polls publishing.audio inbox.comments.read inbox.mentions inbox.dm.send inbox.private_reply analytics.post_metrics analytics.account_metrics analytics.story_insights_webhook ads.boost

  • statestring

    One of available reconnect_required requires_variant requires_connection plan_upgrade coming_soon unsupported

  • createdAtstring (date-time)required

400WorkspaceRequired
401InvalidApiKeyUnauthenticated
403CsrfRejectedForbiddenModuleNotAvailableWorkspaceSuspended
404NotFound
409PostStateConflict
422ValidationError
429RateLimited
503RateLimiterUnavailable

GET/posts/{id}/events

List a post's publishing timeline

  • Scope posts:read

Every step each target went through (prepare, send, reconcile ...), oldest first.

Request
curl https://api.relayport.dev/posts/{id}/events \
  -H "Authorization: Bearer $RELAYPORT_API_KEY"

Parameters

  • X-Api-Versionstringheader

    The API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.

    One of 2026-12-01

  • X-Workspace-Idstring (uuid)header

    The workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.

  • idstring (uuid)pathrequired

Responses

200OK
  • dataPostEvent[]required

  • targetIdstring (uuid)required

  • stepstringrequired

  • labelstringrequired

  • outcomestringrequired

  • atstring (date-time)required

  • detailmap of any | nullrequired

400WorkspaceRequired
401InvalidApiKeyUnauthenticated
403ForbiddenModuleNotAvailableWorkspaceSuspended
404NotFound
422ValidationError
429RateLimited
503RateLimiterUnavailable

POST/posts/{id}/publish

Publish a draft or scheduled post now

  • Scope posts:publish
  • Idempotency-Key
Request
curl -X POST https://api.relayport.dev/posts/{id}/publish \
  -H "Authorization: Bearer $RELAYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

Parameters

  • X-Api-Versionstringheader

    The API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.

    One of 2026-12-01

  • X-Workspace-Idstring (uuid)header

    The workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.

  • Idempotency-Keystringheader

    Repeating a request with the same key within 24 hours returns the first response (header Idempotent-Replayed: true) instead of running it again.

  • X-Requested-Withstringheader

    Required on every write made with a signed-in session; without it the request is 403 CsrfRejected. API keys do not send it.

    One of XMLHttpRequest

  • idstring (uuid)pathrequired

Request body

  • allowDuplicateboolean

Responses

202Accepted
  • dataPostrequired

  • idstring (uuid)required

  • brandIdstring (uuid)required

  • statusstringrequired

    One of draft scheduled publishing published partial failed unconfirmed cancelled

  • modestringrequired

    One of draft schedule publish_now queue

  • textstringrequired

  • titlestring | nullrequired

  • firstCommentstring | nullrequired

  • scheduledAtstring (date-time) | nullrequired

  • queueIdstring (uuid) | nullrequired

  • revisionintegerrequired

  • sourcestringrequired

    One of dashboard api

  • mediaobject[]required

  • mediaIdstring (uuid)required

  • positionintegerrequired

  • platformDatamap of objectrequired

  • staggerobject | nullrequired

  • minSecondsintegerrequired

  • maxSecondsintegerrequired

  • metadatamap of string | number | boolean | nullrequired

  • targetsobject[]required

  • idstring (uuid)required

  • accountIdstring (uuid)required

  • platformstringrequired

  • statusstringrequired

    One of draft scheduled publishing published failed unconfirmed cancelled

  • dueAtstring (date-time) | nullrequired

  • leadMsintegerrequired

  • platformPostIdstring | nullrequired

  • permalinkstring | nullrequired

  • permalinkPendingbooleanrequired

  • publishedAtstring (date-time) | nullrequired

  • publishedLateMsinteger | nullrequired

  • errorobject | nullrequired

  • codestringrequired

  • messagestringrequired

  • actionstringrequired

  • retryByUserboolean

  • reconciliationobject | nullrequired

  • evidencestring[]required

  • revisionintegerrequired

  • warningsIssue[]required

  • severitystringrequired

    One of error warning

  • targetintegerrequired

  • platformstringrequired

  • fieldstringrequired

  • rulestringrequired

  • messagestringrequired

  • limitnumber

  • actualnumber | string

  • allowedstring

  • capabilitystring

    One of publishing.image publishing.carousel publishing.reel publishing.story publishing.collaborators publishing.alt_text publishing.user_tags publishing.location publishing.trial_reels publishing.ai_label publishing.first_comment publishing.delete publishing.resumable_upload publishing.partnership_label publishing.polls publishing.audio inbox.comments.read inbox.mentions inbox.dm.send inbox.private_reply analytics.post_metrics analytics.account_metrics analytics.story_insights_webhook ads.boost

  • statestring

    One of available reconnect_required requires_variant requires_connection plan_upgrade coming_soon unsupported

  • createdAtstring (date-time)required

400InvalidJsonWorkspaceRequired
401InvalidApiKeyUnauthenticated
402PaymentRequiredPlanLimitReached
403CsrfRejectedForbiddenModuleNotAvailableWorkspaceSuspended
404NotFound
409ConflictDuplicateContentIdempotencyInProgressPostStateConflict
413PayloadTooLarge
422IdempotencyKeyReusedPostValidationFailedValidationError
429RateLimited
503RateLimiterUnavailable

POST/posts/{id}/retry

Retry the failed targets of a post

  • Scope posts:publish
  • Idempotency-Key

Re-arms failed targets. An unconfirmed target may already be live on the platform, so it is retried only with includeUnconfirmed: true; check the account first.

Request
curl -X POST https://api.relayport.dev/posts/{id}/retry \
  -H "Authorization: Bearer $RELAYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

Parameters

  • X-Api-Versionstringheader

    The API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.

    One of 2026-12-01

  • X-Workspace-Idstring (uuid)header

    The workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.

  • Idempotency-Keystringheader

    Repeating a request with the same key within 24 hours returns the first response (header Idempotent-Replayed: true) instead of running it again.

  • X-Requested-Withstringheader

    Required on every write made with a signed-in session; without it the request is 403 CsrfRejected. API keys do not send it.

    One of XMLHttpRequest

  • idstring (uuid)pathrequired

Request body

  • includeUnconfirmedboolean

Responses

200OK
  • dataPostrequired

  • idstring (uuid)required

  • brandIdstring (uuid)required

  • statusstringrequired

    One of draft scheduled publishing published partial failed unconfirmed cancelled

  • modestringrequired

    One of draft schedule publish_now queue

  • textstringrequired

  • titlestring | nullrequired

  • firstCommentstring | nullrequired

  • scheduledAtstring (date-time) | nullrequired

  • queueIdstring (uuid) | nullrequired

  • revisionintegerrequired

  • sourcestringrequired

    One of dashboard api

  • mediaobject[]required

  • mediaIdstring (uuid)required

  • positionintegerrequired

  • platformDatamap of objectrequired

  • staggerobject | nullrequired

  • minSecondsintegerrequired

  • maxSecondsintegerrequired

  • metadatamap of string | number | boolean | nullrequired

  • targetsobject[]required

  • idstring (uuid)required

  • accountIdstring (uuid)required

  • platformstringrequired

  • statusstringrequired

    One of draft scheduled publishing published failed unconfirmed cancelled

  • dueAtstring (date-time) | nullrequired

  • leadMsintegerrequired

  • platformPostIdstring | nullrequired

  • permalinkstring | nullrequired

  • permalinkPendingbooleanrequired

  • publishedAtstring (date-time) | nullrequired

  • publishedLateMsinteger | nullrequired

  • errorobject | nullrequired

  • codestringrequired

  • messagestringrequired

  • actionstringrequired

  • retryByUserboolean

  • reconciliationobject | nullrequired

  • evidencestring[]required

  • revisionintegerrequired

  • warningsIssue[]required

  • severitystringrequired

    One of error warning

  • targetintegerrequired

  • platformstringrequired

  • fieldstringrequired

  • rulestringrequired

  • messagestringrequired

  • limitnumber

  • actualnumber | string

  • allowedstring

  • capabilitystring

    One of publishing.image publishing.carousel publishing.reel publishing.story publishing.collaborators publishing.alt_text publishing.user_tags publishing.location publishing.trial_reels publishing.ai_label publishing.first_comment publishing.delete publishing.resumable_upload publishing.partnership_label publishing.polls publishing.audio inbox.comments.read inbox.mentions inbox.dm.send inbox.private_reply analytics.post_metrics analytics.account_metrics analytics.story_insights_webhook ads.boost

  • statestring

    One of available reconnect_required requires_variant requires_connection plan_upgrade coming_soon unsupported

  • createdAtstring (date-time)required

400InvalidJsonWorkspaceRequired
401InvalidApiKeyUnauthenticated
402PaymentRequired
403CsrfRejectedForbiddenModuleNotAvailableWorkspaceSuspended
404NotFound
409IdempotencyInProgressPostStateConflict
413PayloadTooLarge
422IdempotencyKeyReusedValidationError
429RateLimited
503RateLimiterUnavailable

POST/posts/{id}/targets/{targetId}/resolve

Settle an unconfirmed target by hand

  • Scope posts:publish
  • Idempotency-Key

After checking the account on the platform, mark an unconfirmed target published (with its permalink when known) or failed.

Request
curl -X POST https://api.relayport.dev/posts/{id}/targets/{targetId}/resolve \
  -H "Authorization: Bearer $RELAYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "outcome": "published" }'

Parameters

  • X-Api-Versionstringheader

    The API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.

    One of 2026-12-01

  • X-Workspace-Idstring (uuid)header

    The workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.

  • Idempotency-Keystringheader

    Repeating a request with the same key within 24 hours returns the first response (header Idempotent-Replayed: true) instead of running it again.

  • X-Requested-Withstringheader

    Required on every write made with a signed-in session; without it the request is 403 CsrfRejected. API keys do not send it.

    One of XMLHttpRequest

  • idstring (uuid)pathrequired

  • targetIdstring (uuid)pathrequired

Request body

Content types application/json

Responses

200OK
  • dataPostrequired

  • idstring (uuid)required

  • brandIdstring (uuid)required

  • statusstringrequired

    One of draft scheduled publishing published partial failed unconfirmed cancelled

  • modestringrequired

    One of draft schedule publish_now queue

  • textstringrequired

  • titlestring | nullrequired

  • firstCommentstring | nullrequired

  • scheduledAtstring (date-time) | nullrequired

  • queueIdstring (uuid) | nullrequired

  • revisionintegerrequired

  • sourcestringrequired

    One of dashboard api

  • mediaobject[]required

  • mediaIdstring (uuid)required

  • positionintegerrequired

  • platformDatamap of objectrequired

  • staggerobject | nullrequired

  • minSecondsintegerrequired

  • maxSecondsintegerrequired

  • metadatamap of string | number | boolean | nullrequired

  • targetsobject[]required

  • idstring (uuid)required

  • accountIdstring (uuid)required

  • platformstringrequired

  • statusstringrequired

    One of draft scheduled publishing published failed unconfirmed cancelled

  • dueAtstring (date-time) | nullrequired

  • leadMsintegerrequired

  • platformPostIdstring | nullrequired

  • permalinkstring | nullrequired

  • permalinkPendingbooleanrequired

  • publishedAtstring (date-time) | nullrequired

  • publishedLateMsinteger | nullrequired

  • errorobject | nullrequired

  • codestringrequired

  • messagestringrequired

  • actionstringrequired

  • retryByUserboolean

  • reconciliationobject | nullrequired

  • evidencestring[]required

  • revisionintegerrequired

  • warningsIssue[]required

  • severitystringrequired

    One of error warning

  • targetintegerrequired

  • platformstringrequired

  • fieldstringrequired

  • rulestringrequired

  • messagestringrequired

  • limitnumber

  • actualnumber | string

  • allowedstring

  • capabilitystring

    One of publishing.image publishing.carousel publishing.reel publishing.story publishing.collaborators publishing.alt_text publishing.user_tags publishing.location publishing.trial_reels publishing.ai_label publishing.first_comment publishing.delete publishing.resumable_upload publishing.partnership_label publishing.polls publishing.audio inbox.comments.read inbox.mentions inbox.dm.send inbox.private_reply analytics.post_metrics analytics.account_metrics analytics.story_insights_webhook ads.boost

  • statestring

    One of available reconnect_required requires_variant requires_connection plan_upgrade coming_soon unsupported

  • createdAtstring (date-time)required

400InvalidJsonWorkspaceRequired
401InvalidApiKeyUnauthenticated
403CsrfRejectedForbiddenModuleNotAvailableWorkspaceSuspended
404NotFound
409IdempotencyInProgressPostStateConflict
413PayloadTooLarge
422IdempotencyKeyReusedValidationError
429RateLimited
503RateLimiterUnavailable

POST/posts/{id}/unpublish

Delete a published post from its platforms

  • Scope posts:publish
  • Idempotency-Key

No platform offers deletion yet, so this answers 501 NotSupported with details { capability: publishing.delete, targets: [{ targetId, accountId, platform, state, requiredVariant? }] } naming why each published target cannot be deleted. A post with no published target (a scheduled sandbox post included) is 409 PostStateConflict.

Request
curl -X POST https://api.relayport.dev/posts/{id}/unpublish \
  -H "Authorization: Bearer $RELAYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'

Parameters

  • X-Api-Versionstringheader

    The API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.

    One of 2026-12-01

  • X-Workspace-Idstring (uuid)header

    The workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.

  • Idempotency-Keystringheader

    Repeating a request with the same key within 24 hours returns the first response (header Idempotent-Replayed: true) instead of running it again.

  • X-Requested-Withstringheader

    Required on every write made with a signed-in session; without it the request is 403 CsrfRejected. API keys do not send it.

    One of XMLHttpRequest

  • idstring (uuid)pathrequired

Request body

Content types application/json

Responses

200OK. Not answered while no platform supports deletion
  • dataPostrequired

  • idstring (uuid)required

  • brandIdstring (uuid)required

  • statusstringrequired

    One of draft scheduled publishing published partial failed unconfirmed cancelled

  • modestringrequired

    One of draft schedule publish_now queue

  • textstringrequired

  • titlestring | nullrequired

  • firstCommentstring | nullrequired

  • scheduledAtstring (date-time) | nullrequired

  • queueIdstring (uuid) | nullrequired

  • revisionintegerrequired

  • sourcestringrequired

    One of dashboard api

  • mediaobject[]required

  • mediaIdstring (uuid)required

  • positionintegerrequired

  • platformDatamap of objectrequired

  • staggerobject | nullrequired

  • minSecondsintegerrequired

  • maxSecondsintegerrequired

  • metadatamap of string | number | boolean | nullrequired

  • targetsobject[]required

  • idstring (uuid)required

  • accountIdstring (uuid)required

  • platformstringrequired

  • statusstringrequired

    One of draft scheduled publishing published failed unconfirmed cancelled

  • dueAtstring (date-time) | nullrequired

  • leadMsintegerrequired

  • platformPostIdstring | nullrequired

  • permalinkstring | nullrequired

  • permalinkPendingbooleanrequired

  • publishedAtstring (date-time) | nullrequired

  • publishedLateMsinteger | nullrequired

  • errorobject | nullrequired

  • codestringrequired

  • messagestringrequired

  • actionstringrequired

  • retryByUserboolean

  • reconciliationobject | nullrequired

  • evidencestring[]required

  • revisionintegerrequired

  • warningsIssue[]required

  • severitystringrequired

    One of error warning

  • targetintegerrequired

  • platformstringrequired

  • fieldstringrequired

  • rulestringrequired

  • messagestringrequired

  • limitnumber

  • actualnumber | string

  • allowedstring

  • capabilitystring

    One of publishing.image publishing.carousel publishing.reel publishing.story publishing.collaborators publishing.alt_text publishing.user_tags publishing.location publishing.trial_reels publishing.ai_label publishing.first_comment publishing.delete publishing.resumable_upload publishing.partnership_label publishing.polls publishing.audio inbox.comments.read inbox.mentions inbox.dm.send inbox.private_reply analytics.post_metrics analytics.account_metrics analytics.story_insights_webhook ads.boost

  • statestring

    One of available reconnect_required requires_variant requires_connection plan_upgrade coming_soon unsupported

  • createdAtstring (date-time)required

400InvalidJsonWorkspaceRequired
401InvalidApiKeyUnauthenticated
403CsrfRejectedForbiddenModuleNotAvailableWorkspaceSuspended
404NotFound
409IdempotencyInProgressPostStateConflict
413PayloadTooLarge
422IdempotencyKeyReusedValidationError
429RateLimited
501NotSupported
503RateLimiterUnavailable

POST/posts/validate

Check a post against its platforms' rules without saving it

  • Scope posts:write
  • Idempotency-Key

Takes the same body as POST /posts and answers the issues (errors) and warnings each target would get. Nothing is created.

Request
curl -X POST https://api.relayport.dev/posts/validate \
  -H "Authorization: Bearer $RELAYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "mode": "draft", "targets": [{ "accountId": "<uuid>" }] }'

Parameters

  • X-Api-Versionstringheader

    The API version. API keys answer in the version they were created with unless this header asks for another; the current version is 2026-12-01.

    One of 2026-12-01

  • X-Workspace-Idstring (uuid)header

    The workspace of the request. Required with a session; with an API key it may be left out and must match the key's workspace when sent.

  • Idempotency-Keystringheader

    Repeating a request with the same key within 24 hours returns the first response (header Idempotent-Replayed: true) instead of running it again.

  • X-Requested-Withstringheader

    Required on every write made with a signed-in session; without it the request is 403 CsrfRejected. API keys do not send it.

    One of XMLHttpRequest

Request body

  • brandIdstring (uuid)

  • modestringrequired

    One of draft schedule publish_now queue

  • scheduledAtstring (date-time)

  • queueId"default" | string (uuid)

  • textstring

  • titlestring

  • mediaobject[]

  • mediaIdstring (uuid)required

  • platformDataobject

    Keyed by platform: each platform's contentType and options

  • instagramobject

  • contentTypestringrequired

    One of image carousel reel

  • collaboratorsstring[]

  • aiGeneratedboolean

  • sandboxobject

  • contentTypestringrequired

    One of image carousel

  • outcomestring

    One of published failed unconfirmed

  • failureCodestring

  • firstCommentstring

  • targetsobject[]required

  • accountIdstring (uuid)required

  • scheduledAtstring (date-time)

  • textstring

  • titlestring

  • mediaobject[]

  • mediaIdstring (uuid)required

  • firstCommentstring

  • platformDataobject | object

    Flat: the options of the target's own platform, and its contentType when it differs from the post's

  • staggerobject

  • minSecondsintegerrequired

  • maxSecondsintegerrequired

  • allowDuplicateboolean

  • metadatamap of string | number | boolean | null

Responses

200OK
  • dataPostCheckrequired

  • issuesIssue[]required

  • severitystringrequired

    One of error warning

  • targetintegerrequired

  • platformstringrequired

  • fieldstringrequired

  • rulestringrequired

  • messagestringrequired

  • limitnumber

  • actualnumber | string

  • allowedstring

  • capabilitystring

    One of publishing.image publishing.carousel publishing.reel publishing.story publishing.collaborators publishing.alt_text publishing.user_tags publishing.location publishing.trial_reels publishing.ai_label publishing.first_comment publishing.delete publishing.resumable_upload publishing.partnership_label publishing.polls publishing.audio inbox.comments.read inbox.mentions inbox.dm.send inbox.private_reply analytics.post_metrics analytics.account_metrics analytics.story_insights_webhook ads.boost

  • statestring

    One of available reconnect_required requires_variant requires_connection plan_upgrade coming_soon unsupported

  • warningsIssue[]required

  • severitystringrequired

    One of error warning

  • targetintegerrequired

  • platformstringrequired

  • fieldstringrequired

  • rulestringrequired

  • messagestringrequired

  • limitnumber

  • actualnumber | string

  • allowedstring

  • capabilitystring

    One of publishing.image publishing.carousel publishing.reel publishing.story publishing.collaborators publishing.alt_text publishing.user_tags publishing.location publishing.trial_reels publishing.ai_label publishing.first_comment publishing.delete publishing.resumable_upload publishing.partnership_label publishing.polls publishing.audio inbox.comments.read inbox.mentions inbox.dm.send inbox.private_reply analytics.post_metrics analytics.account_metrics analytics.story_insights_webhook ads.boost

  • statestring

    One of available reconnect_required requires_variant requires_connection plan_upgrade coming_soon unsupported

400InvalidJsonWorkspaceRequired
401InvalidApiKeyUnauthenticated
403CsrfRejectedForbiddenModuleNotAvailableWorkspaceSuspended
404NotFound
409IdempotencyInProgress
413PayloadTooLarge
422IdempotencyKeyReusedValidationError
429RateLimited
503RateLimiterUnavailable