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
curl https://api.relayport.dev/media \
-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
dataMedia[]requiredidstring (uuid)requiredbrandIdstring (uuid) | nullrequiredkindstring | nullrequiredcontentTypestring | nullrequiredbytesintegerrequireddeclaredBytesintegerwidthinteger | nullrequiredheightinteger | nullrequireddurationMsinteger | nullrequiredstatusstringrequiredOne of
pendingprocessingreadyfailedfilenamestring | nullrequiredaltTextstring | nullrequiredpreviewUrlstring | nullrequiredA signed link valid for one hour; null until the media is ready
issuesMediaIssue[]requiredrulestringrequiredmessagestringrequiredseveritystringrequiredOne of
errorwarninglimitnumberactualnumbererrorobjectcodestringrequiredOne of
size_mismatchtype_mismatchunreadablerejectedunsafe_urlredirect_not_followedfetch_failedunsupported_content_typetoo_largestorage_limitmessagestringrequiredissuesMediaIssue[]requiredrulestringrequiredmessagestringrequiredseveritystringrequiredOne of
errorwarninglimitnumberactualnumbercreatedAtstring (date-time)requiredmetaPageMetarequirednext_cursorstring | nullrequiredper_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.
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 @fileParameters
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
XMLHttpRequestbrandIdstring (uuid)queryX-FilenamestringheaderThe file name to keep with the media
Request body
Content types image/jpeg video/mp4 video/quicktime
Responses
201Created
dataMediarequiredidstring (uuid)requiredbrandIdstring (uuid) | nullrequiredkindstring | nullrequiredcontentTypestring | nullrequiredbytesintegerrequireddeclaredBytesintegerwidthinteger | nullrequiredheightinteger | nullrequireddurationMsinteger | nullrequiredstatusstringrequiredOne of
pendingprocessingreadyfailedfilenamestring | nullrequiredaltTextstring | nullrequiredpreviewUrlstring | nullrequiredA signed link valid for one hour; null until the media is ready
issuesMediaIssue[]requiredrulestringrequiredmessagestringrequiredseveritystringrequiredOne of
errorwarninglimitnumberactualnumbererrorobjectcodestringrequiredOne of
size_mismatchtype_mismatchunreadablerejectedunsafe_urlredirect_not_followedfetch_failedunsupported_content_typetoo_largestorage_limitmessagestringrequiredissuesMediaIssue[]requiredrulestringrequiredmessagestringrequiredseveritystringrequiredOne of
errorwarninglimitnumberactualnumbercreatedAtstring (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).
curl https://api.relayport.dev/media/{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
dataMediarequiredidstring (uuid)requiredbrandIdstring (uuid) | nullrequiredkindstring | nullrequiredcontentTypestring | nullrequiredbytesintegerrequireddeclaredBytesintegerwidthinteger | nullrequiredheightinteger | nullrequireddurationMsinteger | nullrequiredstatusstringrequiredOne of
pendingprocessingreadyfailedfilenamestring | nullrequiredaltTextstring | nullrequiredpreviewUrlstring | nullrequiredA signed link valid for one hour; null until the media is ready
issuesMediaIssue[]requiredrulestringrequiredmessagestringrequiredseveritystringrequiredOne of
errorwarninglimitnumberactualnumbererrorobjectcodestringrequiredOne of
size_mismatchtype_mismatchunreadablerejectedunsafe_urlredirect_not_followedfetch_failedunsupported_content_typetoo_largestorage_limitmessagestringrequiredissuesMediaIssue[]requiredrulestringrequiredmessagestringrequiredseveritystringrequiredOne of
errorwarninglimitnumberactualnumbercreatedAtstring (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.
curl -X PATCH https://api.relayport.dev/media/{id} \
-H "Authorization: Bearer $RELAYPORT_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'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
altTextstring | nullfilenamestring
Responses
200OK
dataMediarequiredidstring (uuid)requiredbrandIdstring (uuid) | nullrequiredkindstring | nullrequiredcontentTypestring | nullrequiredbytesintegerrequireddeclaredBytesintegerwidthinteger | nullrequiredheightinteger | nullrequireddurationMsinteger | nullrequiredstatusstringrequiredOne of
pendingprocessingreadyfailedfilenamestring | nullrequiredaltTextstring | nullrequiredpreviewUrlstring | nullrequiredA signed link valid for one hour; null until the media is ready
issuesMediaIssue[]requiredrulestringrequiredmessagestringrequiredseveritystringrequiredOne of
errorwarninglimitnumberactualnumbererrorobjectcodestringrequiredOne of
size_mismatchtype_mismatchunreadablerejectedunsafe_urlredirect_not_followedfetch_failedunsupported_content_typetoo_largestorage_limitmessagestringrequiredissuesMediaIssue[]requiredrulestringrequiredmessagestringrequiredseveritystringrequiredOne of
errorwarninglimitnumberactualnumbercreatedAtstring (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.
curl -X DELETE https://api.relayport.dev/media/{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
dataMediaDeletedrequiredidstring (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.
curl -X POST https://api.relayport.dev/media/{id}/complete \
-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
dataMediarequiredidstring (uuid)requiredbrandIdstring (uuid) | nullrequiredkindstring | nullrequiredcontentTypestring | nullrequiredbytesintegerrequireddeclaredBytesintegerwidthinteger | nullrequiredheightinteger | nullrequireddurationMsinteger | nullrequiredstatusstringrequiredOne of
pendingprocessingreadyfailedfilenamestring | nullrequiredaltTextstring | nullrequiredpreviewUrlstring | nullrequiredA signed link valid for one hour; null until the media is ready
issuesMediaIssue[]requiredrulestringrequiredmessagestringrequiredseveritystringrequiredOne of
errorwarninglimitnumberactualnumbererrorobjectcodestringrequiredOne of
size_mismatchtype_mismatchunreadablerejectedunsafe_urlredirect_not_followedfetch_failedunsupported_content_typetoo_largestorage_limitmessagestringrequiredissuesMediaIssue[]requiredrulestringrequiredmessagestringrequiredseveritystringrequiredOne of
errorwarninglimitnumberactualnumbercreatedAtstring (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.
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-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
urlstringrequiredfilenamestringbrandIdstring (uuid)
Responses
202Accepted
dataMediarequiredidstring (uuid)requiredbrandIdstring (uuid) | nullrequiredkindstring | nullrequiredcontentTypestring | nullrequiredbytesintegerrequireddeclaredBytesintegerwidthinteger | nullrequiredheightinteger | nullrequireddurationMsinteger | nullrequiredstatusstringrequiredOne of
pendingprocessingreadyfailedfilenamestring | nullrequiredaltTextstring | nullrequiredpreviewUrlstring | nullrequiredA signed link valid for one hour; null until the media is ready
issuesMediaIssue[]requiredrulestringrequiredmessagestringrequiredseveritystringrequiredOne of
errorwarninglimitnumberactualnumbererrorobjectcodestringrequiredOne of
size_mismatchtype_mismatchunreadablerejectedunsafe_urlredirect_not_followedfetch_failedunsupported_content_typetoo_largestorage_limitmessagestringrequiredissuesMediaIssue[]requiredrulestringrequiredmessagestringrequiredseveritystringrequiredOne of
errorwarninglimitnumberactualnumbercreatedAtstring (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).
curl https://api.relayport.dev/media/storage \
-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.
Responses
200OK
dataMediaStoragerequiredusedBytesintegerrequiredlimitBytesinteger | nullrequiredcountintegerrequired
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.
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-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
filenamestringrequiredcontentTypestringrequiredOne of
image/jpegvideo/mp4video/quicktimebytesintegerrequiredbrandIdstring (uuid)
Responses
201Created
dataMediaUploadTicketrequiredmediaIdstring (uuid)requireduploadUrlstringrequiredmethod"PUT"requiredheadersobjectrequiredcontent-typestringrequiredexpiresAtstring (date-time)required