Skip to content
Relay Port

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.

Request
curl https://api.relayport.dev/accounts \
  -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

Responses

200OK
  • dataSocialAccount[]required

  • idstring (uuid)required

  • brandIdstring (uuid)required

  • platformstringrequired

  • authVariantstringrequired

  • platformAccountIdstringrequired

  • usernamestringrequired

  • profilePictureUrlstring | nullrequired

  • accountCategorystring | nullrequired

  • statusstringrequired

    One of active action_required reconnect_required disconnected frozen

  • grantedScopesstring[]required

  • connectedAtstring (date-time)required

  • metaPageMetarequired

  • next_cursorstring | nullrequired

  • per_pageintegerrequired

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

GET/accounts/{id}

Get a social account

  • Scope accounts:read
Request
curl https://api.relayport.dev/accounts/{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
  • dataSocialAccountrequired

  • idstring (uuid)required

  • brandIdstring (uuid)required

  • platformstringrequired

  • authVariantstringrequired

  • platformAccountIdstringrequired

  • usernamestringrequired

  • profilePictureUrlstring | nullrequired

  • accountCategorystring | nullrequired

  • statusstringrequired

    One of active action_required reconnect_required disconnected frozen

  • grantedScopesstring[]required

  • connectedAtstring (date-time)required

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

PATCH/accounts/{id}

Move an account to another brand

  • Scope accounts:manage
Request
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-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

  • brandIdstring (uuid)required

Responses

200OK
  • dataSocialAccountrequired

  • idstring (uuid)required

  • brandIdstring (uuid)required

  • platformstringrequired

  • authVariantstringrequired

  • platformAccountIdstringrequired

  • usernamestringrequired

  • profilePictureUrlstring | nullrequired

  • accountCategorystring | nullrequired

  • statusstringrequired

    One of active action_required reconnect_required disconnected frozen

  • grantedScopesstring[]required

  • connectedAtstring (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.

Request
curl -X DELETE https://api.relayport.dev/accounts/{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
  • dataSocialAccountrequired

  • idstring (uuid)required

  • brandIdstring (uuid)required

  • platformstringrequired

  • authVariantstringrequired

  • platformAccountIdstringrequired

  • usernamestringrequired

  • profilePictureUrlstring | nullrequired

  • accountCategorystring | nullrequired

  • statusstringrequired

    One of active action_required reconnect_required disconnected frozen

  • grantedScopesstring[]required

  • connectedAtstring (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.

Request
curl https://api.relayport.dev/accounts/{id}/capabilities \
  -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
  • dataAccountCapabilitiesrequired

  • platformstringrequired

  • authVariantstringrequired

  • capabilitiesobject[]required

  • keystringrequired

    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

  • statestringrequired

    One of available reconnect_required requires_variant requires_connection plan_upgrade coming_soon unsupported

  • reasonstringrequired

  • actionUrlstring | nullrequired

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

Request
curl -X POST https://api.relayport.dev/accounts/{id}/check \
  -H "Authorization: Bearer $RELAYPORT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

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

Responses

200OK
  • dataSocialAccountrequired

  • idstring (uuid)required

  • brandIdstring (uuid)required

  • platformstringrequired

  • authVariantstringrequired

  • platformAccountIdstringrequired

  • usernamestringrequired

  • profilePictureUrlstring | nullrequired

  • accountCategorystring | nullrequired

  • statusstringrequired

    One of active action_required reconnect_required disconnected frozen

  • grantedScopesstring[]required

  • connectedAtstring (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.

Request
curl https://api.relayport.dev/accounts/{id}/limits \
  -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
  • dataAccountLimitsrequired

  • quotaTotalinteger | nullrequired

  • quotaUsageinteger | nullrequired

  • budgetsobject[]required

  • lanestringrequired

    One of prepare publish

  • windowMsintegerrequired

  • maxintegerrequired

  • usedintegerrequired

  • remainingintegerrequired

  • livebooleanrequired

  • pressureobject | nullrequired

  • percentnumberrequired

  • retryAfterMsinteger | nullrequired

  • readAtstring (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 }.

Request
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-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

  • platformstringrequired

  • authVariantstring

  • brandIdstring (uuid)

  • labelstring

  • accountIdstring (uuid)

    The account being reconnected; reconnecting an account already counted is allowed at the plan's account limit

  • returnTostring

  • redirectUristring

  • statestring

Responses

200OK. An OAuth platform: open authUrl in the browser before expiresAt
  • dataConnectStartrequired

  • authUrlstringrequired

  • connectSessionIdstring (uuid)required

  • expiresAtstring (date-time)required

201Created. A platform with a direct connect (sandbox): the connected account
  • dataSocialAccountrequired

  • idstring (uuid)required

  • brandIdstring (uuid)required

  • platformstringrequired

  • authVariantstringrequired

  • platformAccountIdstringrequired

  • usernamestringrequired

  • profilePictureUrlstring | nullrequired

  • accountCategorystring | nullrequired

  • statusstringrequired

    One of active action_required reconnect_required disconnected frozen

  • grantedScopesstring[]required

  • connectedAtstring (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).

Request
curl https://api.relayport.dev/connect-sessions/{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
  • dataConnectSessionrequired

  • idstring (uuid)required

  • statusstringrequired

    One of pending consumed completed failed

  • platformstringrequired

  • brandIdstring (uuid) | nullrequired

  • accountIdstring (uuid) | nullrequired

  • errorstring | nullrequired

  • expiresAtstring (date-time)required

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