API reference
Accounts
Connected social accounts: connect, read, check, move between brands and disconnect.
GET/accounts
List connected social accounts
- Scope accounts:read
A brand-restricted key sees only its brands' accounts; a test key sees only test accounts and a live key never sees them.
curl https://api.relayport.dev/accounts \
-H "Authorization: Bearer $RELAYPORT_API_KEY"Parameters
X-Api-VersionstringheaderThe 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-01X-Workspace-Idstring (uuid)headerThe 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.
cursorstringquerylimitintegerquery
Responses
200OK
dataSocialAccount[]requiredidstring (uuid)requiredbrandIdstring (uuid)requiredplatformstringrequiredauthVariantstringrequiredplatformAccountIdstringrequiredusernamestringrequiredprofilePictureUrlstring | nullrequiredaccountCategorystring | nullrequiredstatusstringrequiredOne of
activeaction_requiredreconnect_requireddisconnectedfrozengrantedScopesstring[]requiredconnectedAtstring (date-time)requiredmetaPageMetarequirednext_cursorstring | nullrequiredper_pageintegerrequired
400WorkspaceRequired
401InvalidApiKeyUnauthenticated
403ForbiddenWorkspaceSuspended
404NotFound
422ValidationError
429RateLimited
503RateLimiterUnavailable
GET/accounts/{id}
Get a social account
- Scope accounts:read
curl https://api.relayport.dev/accounts/{id} \
-H "Authorization: Bearer $RELAYPORT_API_KEY"Parameters
X-Api-VersionstringheaderThe 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-01X-Workspace-Idstring (uuid)headerThe 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
dataSocialAccountrequiredidstring (uuid)requiredbrandIdstring (uuid)requiredplatformstringrequiredauthVariantstringrequiredplatformAccountIdstringrequiredusernamestringrequiredprofilePictureUrlstring | nullrequiredaccountCategorystring | nullrequiredstatusstringrequiredOne of
activeaction_requiredreconnect_requireddisconnectedfrozengrantedScopesstring[]requiredconnectedAtstring (date-time)required
400WorkspaceRequired
401InvalidApiKeyUnauthenticated
403ForbiddenWorkspaceSuspended
404NotFound
422ValidationError
429RateLimited
503RateLimiterUnavailable
PATCH/accounts/{id}
Move an account to another brand
- Scope accounts:manage
curl -X PATCH https://api.relayport.dev/accounts/{id} \
-H "Authorization: Bearer $RELAYPORT_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "brandId": "<uuid>" }'Parameters
X-Api-VersionstringheaderThe 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-01X-Workspace-Idstring (uuid)headerThe 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-WithstringheaderRequired on every write made with a signed-in session; without it the request is 403 CsrfRejected. API keys do not send it.
One of
XMLHttpRequestidstring (uuid)pathrequired
Request body
brandIdstring (uuid)required
Responses
200OK
dataSocialAccountrequiredidstring (uuid)requiredbrandIdstring (uuid)requiredplatformstringrequiredauthVariantstringrequiredplatformAccountIdstringrequiredusernamestringrequiredprofilePictureUrlstring | nullrequiredaccountCategorystring | nullrequiredstatusstringrequiredOne of
activeaction_requiredreconnect_requireddisconnectedfrozengrantedScopesstring[]requiredconnectedAtstring (date-time)required
400InvalidJsonWorkspaceRequired
401InvalidApiKeyUnauthenticated
403CsrfRejectedForbiddenWorkspaceSuspended
404NotFound
409Conflict
422ValidationError
429RateLimited
503RateLimiterUnavailable
DELETE/accounts/{id}
Disconnect an account
- Scope accounts:manage
Deletes the stored credentials and keeps the account record with status disconnected.
curl -X DELETE https://api.relayport.dev/accounts/{id} \
-H "Authorization: Bearer $RELAYPORT_API_KEY"Parameters
X-Api-VersionstringheaderThe 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-01X-Workspace-Idstring (uuid)headerThe 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-WithstringheaderRequired on every write made with a signed-in session; without it the request is 403 CsrfRejected. API keys do not send it.
One of
XMLHttpRequestidstring (uuid)pathrequired
Responses
200OK
dataSocialAccountrequiredidstring (uuid)requiredbrandIdstring (uuid)requiredplatformstringrequiredauthVariantstringrequiredplatformAccountIdstringrequiredusernamestringrequiredprofilePictureUrlstring | nullrequiredaccountCategorystring | nullrequiredstatusstringrequiredOne of
activeaction_requiredreconnect_requireddisconnectedfrozengrantedScopesstring[]requiredconnectedAtstring (date-time)required
400WorkspaceRequired
401InvalidApiKeyUnauthenticated
403CsrfRejectedForbiddenWorkspaceSuspended
404NotFound
422ValidationError
429RateLimited
503RateLimiterUnavailable
GET/accounts/{id}/capabilities
List what an account can do
- Scope accounts:read
One entry per capability key with its state (available, reconnect_required, requires_variant, plan_upgrade, coming_soon, unsupported ...), a reason and the action URL when one applies.
curl https://api.relayport.dev/accounts/{id}/capabilities \
-H "Authorization: Bearer $RELAYPORT_API_KEY"Parameters
X-Api-VersionstringheaderThe 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-01X-Workspace-Idstring (uuid)headerThe 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
dataAccountCapabilitiesrequiredplatformstringrequiredauthVariantstringrequiredcapabilitiesobject[]requiredkeystringrequiredOne of
publishing.imagepublishing.carouselpublishing.reelpublishing.storypublishing.collaboratorspublishing.alt_textpublishing.user_tagspublishing.locationpublishing.trial_reelspublishing.ai_labelpublishing.first_commentpublishing.deletepublishing.resumable_uploadpublishing.partnership_labelpublishing.pollspublishing.audioinbox.comments.readinbox.mentionsinbox.dm.sendinbox.private_replyanalytics.post_metricsanalytics.account_metricsanalytics.story_insights_webhookads.booststatestringrequiredOne of
availablereconnect_requiredrequires_variantrequires_connectionplan_upgradecoming_soonunsupportedreasonstringrequiredactionUrlstring | nullrequiredlimitsmap of number | nullrequired
400WorkspaceRequired
401InvalidApiKeyUnauthenticated
403ForbiddenWorkspaceSuspended
404NotFound
422ValidationError
429RateLimited
503RateLimiterUnavailable
POST/accounts/{id}/check
Check an account's connection with the platform
- Scope accounts:manage
- Idempotency-Key
Reads the profile from the platform and updates the account's status (active, action_required or reconnect_required).
curl -X POST https://api.relayport.dev/accounts/{id}/check \
-H "Authorization: Bearer $RELAYPORT_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"Parameters
X-Api-VersionstringheaderThe 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-01X-Workspace-Idstring (uuid)headerThe 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-KeystringheaderRepeating a request with the same key within 24 hours returns the first response (header Idempotent-Replayed: true) instead of running it again.
X-Requested-WithstringheaderRequired on every write made with a signed-in session; without it the request is 403 CsrfRejected. API keys do not send it.
One of
XMLHttpRequestidstring (uuid)pathrequired
Responses
200OK
dataSocialAccountrequiredidstring (uuid)requiredbrandIdstring (uuid)requiredplatformstringrequiredauthVariantstringrequiredplatformAccountIdstringrequiredusernamestringrequiredprofilePictureUrlstring | nullrequiredaccountCategorystring | nullrequiredstatusstringrequiredOne of
activeaction_requiredreconnect_requireddisconnectedfrozengrantedScopesstring[]requiredconnectedAtstring (date-time)required
400WorkspaceRequired
401InvalidApiKeyUnauthenticated
403CsrfRejectedForbiddenWorkspaceSuspended
404NotFound
409AccountDisconnectedIdempotencyInProgress
413PayloadTooLarge
422IdempotencyKeyReusedValidationError
429RateLimited
502UpstreamUnavailable
503RateLimiterUnavailable
GET/accounts/{id}/limits
Get an account's publishing budgets
- Scope accounts:read
The platform quota and the rolling-window budgets of the account's publish and prepare lanes, with the last rate pressure the platform reported.
curl https://api.relayport.dev/accounts/{id}/limits \
-H "Authorization: Bearer $RELAYPORT_API_KEY"Parameters
X-Api-VersionstringheaderThe 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-01X-Workspace-Idstring (uuid)headerThe 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
dataAccountLimitsrequiredquotaTotalinteger | nullrequiredquotaUsageinteger | nullrequiredbudgetsobject[]requiredlanestringrequiredOne of
preparepublishwindowMsintegerrequiredmaxintegerrequiredusedintegerrequiredremainingintegerrequiredlivebooleanrequiredpressureobject | nullrequiredpercentnumberrequiredretryAfterMsinteger | nullrequiredreadAtstring (date-time) | nullrequired
400WorkspaceRequired
401InvalidApiKeyUnauthenticated
403ForbiddenWorkspaceSuspended
404NotFound
422ValidationError
429RateLimited
503RateLimiterUnavailable
POST/accounts/connect
Start connecting a social account
- Scope accounts:manage
- Idempotency-Key
Sessions can connect any live platform. API keys: test keys only, for test platforms such as sandbox, which connect at once; connect a real account through a connect link (POST /connect-links). Send redirectUri (and state) to end an OAuth connect on your own page with status, accountIds, brandId, state and error. A planned platform is 422 CapabilityUnavailable with details { platform, availability, release, interestKey, interestUrl }.
curl -X POST https://api.relayport.dev/accounts/connect \
-H "Authorization: Bearer $RELAYPORT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "platform": "<string>" }'Parameters
X-Api-VersionstringheaderThe 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-01X-Workspace-Idstring (uuid)headerThe 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-KeystringheaderRepeating a request with the same key within 24 hours returns the first response (header Idempotent-Replayed: true) instead of running it again.
X-Requested-WithstringheaderRequired 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
platformstringrequiredauthVariantstringbrandIdstring (uuid)labelstringaccountIdstring (uuid)The account being reconnected; reconnecting an account already counted is allowed at the plan's account limit
returnTostringredirectUristringstatestring
Responses
200OK. An OAuth platform: open authUrl in the browser before expiresAt
dataConnectStartrequiredauthUrlstringrequiredconnectSessionIdstring (uuid)requiredexpiresAtstring (date-time)required
201Created. A platform with a direct connect (sandbox): the connected account
dataSocialAccountrequiredidstring (uuid)requiredbrandIdstring (uuid)requiredplatformstringrequiredauthVariantstringrequiredplatformAccountIdstringrequiredusernamestringrequiredprofilePictureUrlstring | nullrequiredaccountCategorystring | nullrequiredstatusstringrequiredOne of
activeaction_requiredreconnect_requireddisconnectedfrozengrantedScopesstring[]requiredconnectedAtstring (date-time)required
400InvalidJsonWorkspaceRequired
401InvalidApiKeyUnauthenticated
402PaymentRequiredPlanLimitReached
403CsrfRejectedForbiddenWorkspaceSuspended
404NotFound
409IdempotencyInProgressWorkspaceDeletionInProgress
413PayloadTooLarge
422CapabilityUnavailableIdempotencyKeyReusedUnsupportedAuthVariantUnsupportedPlatformValidationError
429RateLimited
503RateLimiterUnavailable
GET/connect-sessions/{id}
Get the outcome of a connect
- Scope accounts:read
The connectSessionId from POST /accounts/connect. status is pending until the platform sign-in returns, then completed (accountId set) or failed (error is the connect result code).
curl https://api.relayport.dev/connect-sessions/{id} \
-H "Authorization: Bearer $RELAYPORT_API_KEY"Parameters
X-Api-VersionstringheaderThe 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-01X-Workspace-Idstring (uuid)headerThe 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
dataConnectSessionrequiredidstring (uuid)requiredstatusstringrequiredOne of
pendingconsumedcompletedfailedplatformstringrequiredbrandIdstring (uuid) | nullrequiredaccountIdstring (uuid) | nullrequirederrorstring | nullrequiredexpiresAtstring (date-time)required