Skip to content
Relay Port

API reference

Media

Images and videos to attach to posts: direct upload, presigned upload or import from a URL.

GET/media

List media files

  • Scope posts:read
Request
curl https://api.relayport.dev/media \
  -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
  • dataMedia[]required

  • idstring (uuid)required

  • brandIdstring (uuid) | nullrequired

  • kindstring | nullrequired

  • contentTypestring | nullrequired

  • bytesintegerrequired

  • declaredBytesinteger

  • widthinteger | nullrequired

  • heightinteger | nullrequired

  • durationMsinteger | nullrequired

  • statusstringrequired

    One of pending processing ready failed

  • filenamestring | nullrequired

  • altTextstring | nullrequired

  • previewUrlstring | nullrequired

    A signed link valid for one hour; null until the media is ready

  • issuesMediaIssue[]required

  • rulestringrequired

  • messagestringrequired

  • severitystringrequired

    One of error warning

  • limitnumber

  • actualnumber

  • errorobject

  • codestringrequired

    One of size_mismatch type_mismatch unreadable rejected unsafe_url redirect_not_followed fetch_failed unsupported_content_type too_large storage_limit

  • messagestringrequired

  • issuesMediaIssue[]required

  • rulestringrequired

  • messagestringrequired

  • severitystringrequired

    One of error warning

  • limitnumber

  • actualnumber

  • createdAtstring (date-time)required

  • metaPageMetarequired

  • next_cursorstring | nullrequired

  • per_pageintegerrequired

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

POST/media

Upload a media file in the request body

  • Scope media:write
  • Idempotency-Key

The raw file is the body, with its Content-Type. Videos up to 50 MB; for bigger videos (up to 300 MB) use POST /media/uploads. A key with several brands must pass brandId.

Request
curl -X POST https://api.relayport.dev/media \
  -H "Authorization: Bearer $RELAYPORT_API_KEY" \
  -H "Content-Type: image/jpeg" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-binary @file

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

  • brandIdstring (uuid)query

  • X-Filenamestringheader

    The file name to keep with the media

Request body

Content types image/jpeg video/mp4 video/quicktime

Responses

201Created
  • dataMediarequired

  • idstring (uuid)required

  • brandIdstring (uuid) | nullrequired

  • kindstring | nullrequired

  • contentTypestring | nullrequired

  • bytesintegerrequired

  • declaredBytesinteger

  • widthinteger | nullrequired

  • heightinteger | nullrequired

  • durationMsinteger | nullrequired

  • statusstringrequired

    One of pending processing ready failed

  • filenamestring | nullrequired

  • altTextstring | nullrequired

  • previewUrlstring | nullrequired

    A signed link valid for one hour; null until the media is ready

  • issuesMediaIssue[]required

  • rulestringrequired

  • messagestringrequired

  • severitystringrequired

    One of error warning

  • limitnumber

  • actualnumber

  • errorobject

  • codestringrequired

    One of size_mismatch type_mismatch unreadable rejected unsafe_url redirect_not_followed fetch_failed unsupported_content_type too_large storage_limit

  • messagestringrequired

  • issuesMediaIssue[]required

  • rulestringrequired

  • messagestringrequired

  • severitystringrequired

    One of error warning

  • limitnumber

  • actualnumber

  • createdAtstring (date-time)required

400WorkspaceRequired
401InvalidApiKeyUnauthenticated
402PlanLimitReached
403CsrfRejectedForbiddenModuleNotAvailableWorkspaceSuspended
404NotFound
409IdempotencyInProgress
413MediaTooLargePayloadTooLarge
415UnsupportedMediaType
422IdempotencyKeyReusedMediaRejectedValidationError
429RateLimited
503RateLimiterUnavailable

GET/media/{id}

Get a media file

  • Scope posts:read

previewUrl is a signed link valid for 60 minutes, issued only for ready media (null otherwise).

Request
curl https://api.relayport.dev/media/{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
  • dataMediarequired

  • idstring (uuid)required

  • brandIdstring (uuid) | nullrequired

  • kindstring | nullrequired

  • contentTypestring | nullrequired

  • bytesintegerrequired

  • declaredBytesinteger

  • widthinteger | nullrequired

  • heightinteger | nullrequired

  • durationMsinteger | nullrequired

  • statusstringrequired

    One of pending processing ready failed

  • filenamestring | nullrequired

  • altTextstring | nullrequired

  • previewUrlstring | nullrequired

    A signed link valid for one hour; null until the media is ready

  • issuesMediaIssue[]required

  • rulestringrequired

  • messagestringrequired

  • severitystringrequired

    One of error warning

  • limitnumber

  • actualnumber

  • errorobject

  • codestringrequired

    One of size_mismatch type_mismatch unreadable rejected unsafe_url redirect_not_followed fetch_failed unsupported_content_type too_large storage_limit

  • messagestringrequired

  • issuesMediaIssue[]required

  • rulestringrequired

  • messagestringrequired

  • severitystringrequired

    One of error warning

  • limitnumber

  • actualnumber

  • createdAtstring (date-time)required

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

PATCH/media/{id}

Update a media file's alt text or file name

  • Scope media:write

Alt text applies to images only, up to the longest alt text a connected platform accepts.

Request
curl -X PATCH https://api.relayport.dev/media/{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

  • altTextstring | null

  • filenamestring

Responses

200OK
  • dataMediarequired

  • idstring (uuid)required

  • brandIdstring (uuid) | nullrequired

  • kindstring | nullrequired

  • contentTypestring | nullrequired

  • bytesintegerrequired

  • declaredBytesinteger

  • widthinteger | nullrequired

  • heightinteger | nullrequired

  • durationMsinteger | nullrequired

  • statusstringrequired

    One of pending processing ready failed

  • filenamestring | nullrequired

  • altTextstring | nullrequired

  • previewUrlstring | nullrequired

    A signed link valid for one hour; null until the media is ready

  • issuesMediaIssue[]required

  • rulestringrequired

  • messagestringrequired

  • severitystringrequired

    One of error warning

  • limitnumber

  • actualnumber

  • errorobject

  • codestringrequired

    One of size_mismatch type_mismatch unreadable rejected unsafe_url redirect_not_followed fetch_failed unsupported_content_type too_large storage_limit

  • messagestringrequired

  • issuesMediaIssue[]required

  • rulestringrequired

  • messagestringrequired

  • severitystringrequired

    One of error warning

  • limitnumber

  • actualnumber

  • createdAtstring (date-time)required

400InvalidJsonWorkspaceRequired
401InvalidApiKeyUnauthenticated
403CsrfRejectedForbiddenModuleNotAvailableWorkspaceSuspended
404NotFound
422ValidationError
429RateLimited
503RateLimiterUnavailable

DELETE/media/{id}

Delete a media file

  • Scope media:write

Refused with 409 MediaInUse while a post uses it.

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

  • idstring (uuid)required

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

POST/media/{id}/complete

Finish a presigned upload

  • Scope media:write
  • Idempotency-Key

Checks the uploaded object and settles the media ready or failed. 409 Conflict with details.reason upload_missing when nothing was uploaded. Calling it again returns the settled media.

Request
curl -X POST https://api.relayport.dev/media/{id}/complete \
  -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
  • dataMediarequired

  • idstring (uuid)required

  • brandIdstring (uuid) | nullrequired

  • kindstring | nullrequired

  • contentTypestring | nullrequired

  • bytesintegerrequired

  • declaredBytesinteger

  • widthinteger | nullrequired

  • heightinteger | nullrequired

  • durationMsinteger | nullrequired

  • statusstringrequired

    One of pending processing ready failed

  • filenamestring | nullrequired

  • altTextstring | nullrequired

  • previewUrlstring | nullrequired

    A signed link valid for one hour; null until the media is ready

  • issuesMediaIssue[]required

  • rulestringrequired

  • messagestringrequired

  • severitystringrequired

    One of error warning

  • limitnumber

  • actualnumber

  • errorobject

  • codestringrequired

    One of size_mismatch type_mismatch unreadable rejected unsafe_url redirect_not_followed fetch_failed unsupported_content_type too_large storage_limit

  • messagestringrequired

  • issuesMediaIssue[]required

  • rulestringrequired

  • messagestringrequired

  • severitystringrequired

    One of error warning

  • limitnumber

  • actualnumber

  • createdAtstring (date-time)required

400WorkspaceRequired
401InvalidApiKeyUnauthenticated
402PlanLimitReached
403CsrfRejectedForbiddenModuleNotAvailableWorkspaceSuspended
404NotFound
409ConflictIdempotencyInProgress
413PayloadTooLarge
422IdempotencyKeyReusedValidationError
429RateLimited
503RateLimiterUnavailable

POST/media/imports

Import a media file from a public HTTPS URL

  • Scope media:write
  • Idempotency-Key

Answers at once with a media in status processing; it becomes ready or failed (media.ready or media.failed event). Redirects are not followed, private and loopback hosts are refused, and the fetch stops after 60 seconds.

Request
curl -X POST https://api.relayport.dev/media/imports \
  -H "Authorization: Bearer $RELAYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "url": "<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

  • urlstringrequired

  • filenamestring

  • brandIdstring (uuid)

Responses

202Accepted
  • dataMediarequired

  • idstring (uuid)required

  • brandIdstring (uuid) | nullrequired

  • kindstring | nullrequired

  • contentTypestring | nullrequired

  • bytesintegerrequired

  • declaredBytesinteger

  • widthinteger | nullrequired

  • heightinteger | nullrequired

  • durationMsinteger | nullrequired

  • statusstringrequired

    One of pending processing ready failed

  • filenamestring | nullrequired

  • altTextstring | nullrequired

  • previewUrlstring | nullrequired

    A signed link valid for one hour; null until the media is ready

  • issuesMediaIssue[]required

  • rulestringrequired

  • messagestringrequired

  • severitystringrequired

    One of error warning

  • limitnumber

  • actualnumber

  • errorobject

  • codestringrequired

    One of size_mismatch type_mismatch unreadable rejected unsafe_url redirect_not_followed fetch_failed unsupported_content_type too_large storage_limit

  • messagestringrequired

  • issuesMediaIssue[]required

  • rulestringrequired

  • messagestringrequired

  • severitystringrequired

    One of error warning

  • limitnumber

  • actualnumber

  • createdAtstring (date-time)required

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

GET/media/storage

Get the storage meter

  • Scope posts:read

Bytes used by ready media against the plan's storage limit (null means no limit).

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

Responses

200OK
  • dataMediaStoragerequired

  • usedBytesintegerrequired

  • limitBytesinteger | nullrequired

  • countintegerrequired

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

POST/media/uploads

Get a presigned upload URL

  • Scope media:write
  • Idempotency-Key

Returns a media id and a URL to PUT the file to directly, with the given Content-Type and exactly the declared bytes, before expiresAt (15 minutes). Then call POST /media/{id}/complete. Videos up to 300 MB.

Request
curl -X POST https://api.relayport.dev/media/uploads \
  -H "Authorization: Bearer $RELAYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "filename": "<string>",
    "contentType": "image/jpeg",
    "bytes": 1
  }'

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

  • filenamestringrequired

  • contentTypestringrequired

    One of image/jpeg video/mp4 video/quicktime

  • bytesintegerrequired

  • brandIdstring (uuid)

Responses

201Created
  • dataMediaUploadTicketrequired

  • mediaIdstring (uuid)required

  • uploadUrlstringrequired

  • method"PUT"required

  • headersobjectrequired

  • content-typestringrequired

  • expiresAtstring (date-time)required

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