Media
Media in the management API. 19 endpoints.
Read the guideOpenAPI 3.1 document
Try it settings
https://api.bifrostorbit.com/cms/manage/v1
The management API takes a management token, which is secret and acts as a person, so nothing here is sent from the docs.
Try it sends each request straight from your browser to the API. The key stays in this page's memory: it is never saved, never sent to docs.bifrostorbit.com and gone when you leave or reload the page. Only reads are run; anything that changes data is described and never sent.
The whole library, newest first
GET/organisations/{organisationId}/spaces/{spaceId}/mediaKey required
The whole library, newest first. Permission: media:read.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
Responses
200OKList of files.dataMedia[]Newest first.
Fields of data
idstringAn id.
filenamestringurlstringmimeTypestringcategorystringimage, video, document or other.
sizeintegerIn bytes.
checksumstring or nullThe SHA-256 of the stored file, in hex. null for files stored before checksums were kept.
widthinteger or nullheightinteger or nullfolderIdstring or nullAn id.
titlemap of stringBy language code.
altmap of stringBy language code, such as { "en-GB": "Kayaks on a calm fjord" }.
captionmap of stringBy language code.
tagsstring[]createdAtstringoriginalobject or nullThe file before the crop and edits, when it was kept. For an image with blurred areas, url is the media item's /original address, which needs media:upload.
Fields of original
urlstringwidthintegerheightinteger
cropobject or nullFields of crop
xnumberynumberwidthnumberheightnumber
One of 0, 90, 180, 270.rotateintegeraspectstring or nullSuch as 16:9.
editobject or nullChanges made in the image editor, or null.
Fields of edit
Only 1.versionintegerstepsany[]Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.
focalPointobject or nullFields of focalPoint
xnumber0 to 1 from the left.
ynumber0 to 1 from the top.
consentobject or nullFields of consent
referencestring or null
One of pending, approved, withdrawn.statusstringrestrictionsstring or null
subtitlesmap of stringSubtitle file addresses by language code.
sourceobject or nullSet when the file is linked from a media library connected in Orbit rather than stored in CMS Orbit. url is then the library's own address.
Fields of source
One of cloudinary, bynder, frontify.providerstringexternalIdstringThe file's id in that library.
401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks media:read.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such space, or it's in another organisation.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media' \ -H 'Authorization: Bearer cms_mt_…'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Example answer
{ "data": [ { "id": "6650f1c2a9e4b1d2c3f40a45", "filename": "lofoten-kayaks.webp", "url": "https://media.northwilds.com/lofoten-kayaks.webp", "mimeType": "image/webp", "category": "image", "size": 4, "checksum": null, "width": 1, "height": 1, "folderId": "6650f1c2a9e4b1d2c3f40a20", "title": {}, "alt": { "en-GB": "Kayaks on a calm fjord" }, "caption": {}, "tags": [ "…" ], "createdAt": "2026-11-02T09:30:00.000Z", "original": { "url": "https://northwilds.com/trips/lofoten-sea-kayaking", "width": 1, "height": 1 }, "crop": { "x": 1, "y": 1, "width": 1, "height": 1, "rotate": 0, "aspect": null }, "edit": { "version": 1, "steps": [ null ] }, "focalPoint": { "x": 1, "y": 1 }, "consent": { "reference": null, "status": "pending", "restrictions": null }, "subtitles": {}, "source": { "provider": "cloudinary", "externalId": "6650f1c2a9e4b1d2c3f40a5a" } } ]}Uploads a file
POST/organisations/{organisationId}/spaces/{spaceId}/mediaKey required
Uploads a file. Permission: media:upload.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
Idempotency-KeystringheaderOptional. A unique value, such as a UUID, that makes a retry safe: the same key with the same request within 24 hours returns the first answer again, with Idempotent-Replayed: true, instead of making the change twice. The same key with a different request gets 422; while the first request is still running, 409. Only successful answers are kept.
Up to 255 characters.
Request body
filestringrequiredJPEG, PNG, WebP, AVIF, GIF, SVG, PDF, MP4 or WebM, up to 25 MB. JPEG and PNG are stored as WebP.
folderIdstringoptionalA media folder's id.
cropstringoptionalA crop to apply at once, as JSON text: { "area": { "x", "y", "width", "height", "rotate" }, "aspect": "16:9" }.
keepOriginalstringoptionaltrue keeps the uncropped file as well.
One of true, false.
Responses
201CreatedThe file.dataMediaThe file. A file the library already has answers with the existing one.
Fields of data
idstringAn id.
filenamestringurlstringmimeTypestringcategorystringimage, video, document or other.
sizeintegerIn bytes.
checksumstring or nullThe SHA-256 of the stored file, in hex. null for files stored before checksums were kept.
widthinteger or nullheightinteger or nullfolderIdstring or nullAn id.
titlemap of stringBy language code.
altmap of stringBy language code, such as { "en-GB": "Kayaks on a calm fjord" }.
captionmap of stringBy language code.
tagsstring[]createdAtstringoriginalobject or nullThe file before the crop and edits, when it was kept. For an image with blurred areas, url is the media item's /original address, which needs media:upload.
Fields of original
urlstringwidthintegerheightinteger
cropobject or nullFields of crop
xnumberynumberwidthnumberheightnumber
One of 0, 90, 180, 270.rotateintegeraspectstring or nullSuch as 16:9.
editobject or nullChanges made in the image editor, or null.
Fields of edit
Only 1.versionintegerstepsany[]Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.
focalPointobject or nullFields of focalPoint
xnumber0 to 1 from the left.
ynumber0 to 1 from the top.
consentobject or nullFields of consent
referencestring or null
One of pending, approved, withdrawn.statusstringrestrictionsstring or null
subtitlesmap of stringSubtitle file addresses by language code.
sourceobject or nullSet when the file is linked from a media library connected in Orbit rather than stored in CMS Orbit. url is then the library's own address.
Fields of source
One of cloudinary, bynder, frontify.providerstringexternalIdstringThe file's id in that library.
400Bad requestNot multipart/form-data, no file, a type it doesn't take, over 25 MB, or crop that isn't JSON.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks media:upload, or the plan's storage is full.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such space, or it's in another organisation.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
422Unprocessablecrop doesn't match its schema.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl -X POST 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media' \ -H 'Authorization: Bearer cms_mt_…'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Example answer
{ "data": { "id": "6650f1c2a9e4b1d2c3f40a45", "filename": "lofoten-kayaks.webp", "url": "https://media.northwilds.com/lofoten-kayaks.webp", "mimeType": "image/webp", "category": "image", "size": 4, "checksum": null, "width": 1, "height": 1, "folderId": "6650f1c2a9e4b1d2c3f40a20", "title": {}, "alt": { "en-GB": "Kayaks on a calm fjord" }, "caption": {}, "tags": [ "…" ], "createdAt": "2026-11-02T09:30:00.000Z", "original": { "url": "https://northwilds.com/trips/lofoten-sea-kayaking", "width": 1, "height": 1 }, "crop": { "x": 1, "y": 1, "width": 1, "height": 1, "rotate": 0, "aspect": null }, "edit": { "version": 1, "steps": [ null ] }, "focalPoint": { "x": 1, "y": 1 }, "consent": { "reference": null, "status": "pending", "restrictions": null }, "subtitles": {}, "source": { "provider": "cloudinary", "externalId": "6650f1c2a9e4b1d2c3f40a5a" } }}Media folders
GET/organisations/{organisationId}/spaces/{spaceId}/media/foldersKey required
Media folders. Permission: media:read.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
Responses
200OK[{ id, name, parentId }].dataMediaFolder[]Fields of data
idstringAn id.
namestringparentIdstring or nullAn id.
401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks media:read.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such space, or it's in another organisation.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media/folders' \ -H 'Authorization: Bearer cms_mt_…'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Example answer
{ "data": [ { "id": "6650f1c2a9e4b1d2c3f40a4b", "name": "Lofoten 2026", "parentId": null } ]}Adds one: name, parentId
POST/organisations/{organisationId}/spaces/{spaceId}/media/foldersKey required
Adds one: name, parentId. Permission: media:upload.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
Idempotency-KeystringheaderOptional. A unique value, such as a UUID, that makes a retry safe: the same key with the same request within 24 hours returns the first answer again, with Idempotent-Replayed: true, instead of making the change twice. The same key with a different request gets 422; while the first request is still running, 409. Only successful answers are kept.
Up to 255 characters.
Request body
Up to 200 characters.namestringrequiredparentIdstring or nulloptionalAn id.
Responses
201CreatedThe new item.dataMediaFolderFields of data
idstringAn id.
namestringparentIdstring or nullAn id.
400Bad requestThe body is empty or isn't valid JSON.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks media:upload, or the token is read only.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such space, or it's in another organisation.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
422UnprocessableThe body doesn't match the schema. Each problem is in error.details.issues.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl -X POST 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media/folders' \ -H 'Authorization: Bearer cms_mt_…' \ -H 'Content-Type: application/json' \ -d '{"name":"Lofoten 2026"}'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Example answer
{ "data": { "id": "6650f1c2a9e4b1d2c3f40a4b", "name": "Lofoten 2026", "parentId": null }}Deletes an empty one
DELETE/organisations/{organisationId}/spaces/{spaceId}/media/folders/{folderId}Key required
Deletes an empty one. Permission: media:delete.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
folderIdstringpath, requiredThe folder's id.
Responses
204No contentDone, nothing to return.401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks media:delete, or the token is read only.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such folder, or it's in another organisation.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
409ConflictIt still holds files or folders.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl -X DELETE 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media/folders/6650f1c2a9e4b1d2c3f40a30' \ -H 'Authorization: Bearer cms_mt_…'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Renames one
PATCH/organisations/{organisationId}/spaces/{spaceId}/media/folders/{folderId}Key required
Renames one. Permission: media:upload.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
folderIdstringpath, requiredThe folder's id.
Idempotency-KeystringheaderOptional. A unique value, such as a UUID, that makes a retry safe: the same key with the same request within 24 hours returns the first answer again, with Idempotent-Replayed: true, instead of making the change twice. The same key with a different request gets 422; while the first request is still running, 409. Only successful answers are kept.
Up to 255 characters.
Request body
Up to 200 characters.namestringoptional
Responses
200OKThe folder.dataMediaFolderFields of data
idstringAn id.
namestringparentIdstring or nullAn id.
400Bad requestThe body is empty or isn't valid JSON.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks media:upload, or the token is read only.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such folder, or it's in another organisation.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
422UnprocessableThe body doesn't match the schema. Each problem is in error.details.issues.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl -X PATCH 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media/folders/6650f1c2a9e4b1d2c3f40a30' \ -H 'Authorization: Bearer cms_mt_…' \ -H 'Content-Type: application/json' \ -d '{"name":"Lofoten summer 2026"}'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Example answer
{ "data": { "id": "6650f1c2a9e4b1d2c3f40a4b", "name": "Lofoten 2026", "parentId": null }}Empties the bin
DELETE/organisations/{organisationId}/spaces/{spaceId}/media/trashKey required
Empties the bin. Permission: content:purge.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
Responses
200OK{ erased }.dataobjectFields of data
erasedintegerHow many files were erased.
401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks content:purge, or the token is read only.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such space, or it's in another organisation.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl -X DELETE 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media/trash' \ -H 'Authorization: Bearer cms_mt_…'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Example answer
{ "data": { "erased": 1 }}Files in the bin
GET/organisations/{organisationId}/spaces/{spaceId}/media/trashKey required
Files in the bin. Permission: media:read.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
Responses
200OKList.dataobject[]Fields of data
idstringAn id.
filenamestringurlstringmimeTypestringsizeintegerdeletedAtstring
401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks media:read.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such space, or it's in another organisation.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media/trash' \ -H 'Authorization: Bearer cms_mt_…'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Example answer
{ "data": [ { "id": "6650f1c2a9e4b1d2c3f40a40", "filename": "…", "url": "https://northwilds.com/trips/lofoten-sea-kayaking", "mimeType": "…", "size": 4, "deletedAt": "2026-11-02T09:30:00.000Z" } ]}Erases one file for good
DELETE/organisations/{organisationId}/spaces/{spaceId}/media/trash/{mediaId}Key required
Erases one file for good. Permission: content:purge.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
mediaIdstringpath, requiredThe media's id.
Responses
204No contentDone, nothing to return.401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks content:purge, or the token is read only.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such media, or it's in another organisation.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl -X DELETE 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media/trash/6650f1c2a9e4b1d2c3f40a30' \ -H 'Authorization: Bearer cms_mt_…'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Takes a file out of the bin
POST/organisations/{organisationId}/spaces/{spaceId}/media/trash/{mediaId}Key required
Takes a file out of the bin. Permission: media:delete.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
mediaIdstringpath, requiredThe media's id.
Idempotency-KeystringheaderOptional. A unique value, such as a UUID, that makes a retry safe: the same key with the same request within 24 hours returns the first answer again, with Idempotent-Replayed: true, instead of making the change twice. The same key with a different request gets 422; while the first request is still running, 409. Only successful answers are kept.
Up to 255 characters.
Responses
204No contentDone, nothing to return.401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks media:delete, or the token is read only.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such media, or it's in another organisation.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl -X POST 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media/trash/6650f1c2a9e4b1d2c3f40a30' \ -H 'Authorization: Bearer cms_mt_…'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Moves it to the bin
DELETE/organisations/{organisationId}/spaces/{spaceId}/media/{mediaId}Key required
Moves it to the bin. Permission: media:delete.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
mediaIdstringpath, requiredThe media's id.
Responses
204No contentDone, nothing to return.401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks media:delete, or the token is read only.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such media, or it's in another organisation.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl -X DELETE 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media/6650f1c2a9e4b1d2c3f40a30' \ -H 'Authorization: Bearer cms_mt_…'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Changes its name, folder, texts, tags, focal point or consent
PATCH/organisations/{organisationId}/spaces/{spaceId}/media/{mediaId}Key required
Changes its name, folder, texts, tags, focal point or consent. Permission: media:upload.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
mediaIdstringpath, requiredThe media's id.
Idempotency-KeystringheaderOptional. A unique value, such as a UUID, that makes a retry safe: the same key with the same request within 24 hours returns the first answer again, with Idempotent-Replayed: true, instead of making the change twice. The same key with a different request gets 422; while the first request is still running, 409. Only successful answers are kept.
Up to 255 characters.
Request body
Up to 200 characters.filenamestringoptionalfolderIdstring or nulloptionalAn id.
titlemap of stringoptionalBy language code.
altmap of stringoptionalBy language code, such as { "en-GB": "Kayaks on a calm fjord" }. Up to 500 characters each.
captionmap of stringoptionalBy language code.
Up to 50 items.tagsstring[]optionalfocalPointobject or nulloptionalFrom 0 to 1, x from the left and y from the top.
Fields of focalPoint
At least 0. At most 1.xnumberrequired
At least 0. At most 1.ynumberrequired
consentobject or nulloptionalFor photos of people.
Fields of consent
Default null. Up to 120 characters.referencestring or nulloptional
One of pending, approved, withdrawn. Default "pending".statusstringoptional
Default null. Up to 500 characters.restrictionsstring or nulloptional
Responses
200OKThe file.dataMediaFields of data
idstringAn id.
filenamestringurlstringmimeTypestringcategorystringimage, video, document or other.
sizeintegerIn bytes.
checksumstring or nullThe SHA-256 of the stored file, in hex. null for files stored before checksums were kept.
widthinteger or nullheightinteger or nullfolderIdstring or nullAn id.
titlemap of stringBy language code.
altmap of stringBy language code, such as { "en-GB": "Kayaks on a calm fjord" }.
captionmap of stringBy language code.
tagsstring[]createdAtstringoriginalobject or nullThe file before the crop and edits, when it was kept. For an image with blurred areas, url is the media item's /original address, which needs media:upload.
Fields of original
urlstringwidthintegerheightinteger
cropobject or nullFields of crop
xnumberynumberwidthnumberheightnumber
One of 0, 90, 180, 270.rotateintegeraspectstring or nullSuch as 16:9.
editobject or nullChanges made in the image editor, or null.
Fields of edit
Only 1.versionintegerstepsany[]Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.
focalPointobject or nullFields of focalPoint
xnumber0 to 1 from the left.
ynumber0 to 1 from the top.
consentobject or nullFields of consent
referencestring or null
One of pending, approved, withdrawn.statusstringrestrictionsstring or null
subtitlesmap of stringSubtitle file addresses by language code.
sourceobject or nullSet when the file is linked from a media library connected in Orbit rather than stored in CMS Orbit. url is then the library's own address.
Fields of source
One of cloudinary, bynder, frontify.providerstringexternalIdstringThe file's id in that library.
400Bad requestThe body is empty or isn't valid JSON.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks media:upload, or the token is read only.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such media, or it's in another organisation.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
422UnprocessableThe body doesn't match the schema. Each problem is in error.details.issues.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl -X PATCH 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media/6650f1c2a9e4b1d2c3f40a30' \ -H 'Authorization: Bearer cms_mt_…' \ -H 'Content-Type: application/json' \ -d '{"alt":{"en-GB":"Kayaks on a calm fjord below Reinebringen"},"tags":["lofoten","kayak"],"focalPoint":{"x":0.4,"y":0.6}}'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Example answer
{ "data": { "id": "6650f1c2a9e4b1d2c3f40a45", "filename": "lofoten-kayaks.webp", "url": "https://media.northwilds.com/lofoten-kayaks.webp", "mimeType": "image/webp", "category": "image", "size": 4, "checksum": null, "width": 1, "height": 1, "folderId": "6650f1c2a9e4b1d2c3f40a20", "title": {}, "alt": { "en-GB": "Kayaks on a calm fjord" }, "caption": {}, "tags": [ "…" ], "createdAt": "2026-11-02T09:30:00.000Z", "original": { "url": "https://northwilds.com/trips/lofoten-sea-kayaking", "width": 1, "height": 1 }, "crop": { "x": 1, "y": 1, "width": 1, "height": 1, "rotate": 0, "aspect": null }, "edit": { "version": 1, "steps": [ null ] }, "focalPoint": { "x": 1, "y": 1 }, "consent": { "reference": null, "status": "pending", "restrictions": null }, "subtitles": {}, "source": { "provider": "cloudinary", "externalId": "6650f1c2a9e4b1d2c3f40a5a" } }}Crops or edits an image, or takes the crop and edits off again
POST/organisations/{organisationId}/spaces/{spaceId}/media/{mediaId}/cropKey required
Crops or edits an image, or takes the crop and edits off again. Permission: media:upload.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
mediaIdstringpath, requiredThe media's id.
Idempotency-KeystringheaderOptional. A unique value, such as a UUID, that makes a retry safe: the same key with the same request within 24 hours returns the first answer again, with Idempotent-Replayed: true, instead of making the change twice. The same key with a different request gets 422; while the first request is still running, 409. Only successful answers are kept.
Up to 255 characters.
Request body
areaobject or nullrequiredIn pixels of the original after the quarter turn, flips and straightening. null removes the crop.
Fields of area
At least 0.xnumberrequired
At least 0.ynumberrequired
At least 1.widthnumberrequired
At least 1.heightnumberrequired
One of 0, 90, 180, 270.rotatenumberrequired
aspectstring or nulloptionalSuch as 16:9.
Up to 20 characters.editobject or nulloptionalThe image editor's changes: flip, straighten (-45 to 45 degrees), redact (areas as fractions of the straightened image, blurred or pixelated), adjust (-100 to 100 each), look (warm, cool, mono, noir, faded or vivid, strength 0 to 100) and sharpen (0 to 100). null removes them; leave it out to keep them. The original is kept either way.
Fields of edit
Default 1.version1optional
Up to 12 items.stepsobject or object or object or object or object or object[]requiredFields of steps
asCopybooleanoptionalKeep this file and add the result as a new one, answered with 201.
Default false.
Responses
200OKThe file, or 201 with a copy.dataMediaFields of data
idstringAn id.
filenamestringurlstringmimeTypestringcategorystringimage, video, document or other.
sizeintegerIn bytes.
checksumstring or nullThe SHA-256 of the stored file, in hex. null for files stored before checksums were kept.
widthinteger or nullheightinteger or nullfolderIdstring or nullAn id.
titlemap of stringBy language code.
altmap of stringBy language code, such as { "en-GB": "Kayaks on a calm fjord" }.
captionmap of stringBy language code.
tagsstring[]createdAtstringoriginalobject or nullThe file before the crop and edits, when it was kept. For an image with blurred areas, url is the media item's /original address, which needs media:upload.
Fields of original
urlstringwidthintegerheightinteger
cropobject or nullFields of crop
xnumberynumberwidthnumberheightnumber
One of 0, 90, 180, 270.rotateintegeraspectstring or nullSuch as 16:9.
editobject or nullChanges made in the image editor, or null.
Fields of edit
Only 1.versionintegerstepsany[]Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.
focalPointobject or nullFields of focalPoint
xnumber0 to 1 from the left.
ynumber0 to 1 from the top.
consentobject or nullFields of consent
referencestring or null
One of pending, approved, withdrawn.statusstringrestrictionsstring or null
subtitlesmap of stringSubtitle file addresses by language code.
sourceobject or nullSet when the file is linked from a media library connected in Orbit rather than stored in CMS Orbit. url is then the library's own address.
Fields of source
One of cloudinary, bynder, frontify.providerstringexternalIdstringThe file's id in that library.
201CreatedWith asCopy: the new file.dataMediaFields of data
idstringAn id.
filenamestringurlstringmimeTypestringcategorystringimage, video, document or other.
sizeintegerIn bytes.
checksumstring or nullThe SHA-256 of the stored file, in hex. null for files stored before checksums were kept.
widthinteger or nullheightinteger or nullfolderIdstring or nullAn id.
titlemap of stringBy language code.
altmap of stringBy language code, such as { "en-GB": "Kayaks on a calm fjord" }.
captionmap of stringBy language code.
tagsstring[]createdAtstringoriginalobject or nullThe file before the crop and edits, when it was kept. For an image with blurred areas, url is the media item's /original address, which needs media:upload.
Fields of original
urlstringwidthintegerheightinteger
cropobject or nullFields of crop
xnumberynumberwidthnumberheightnumber
One of 0, 90, 180, 270.rotateintegeraspectstring or nullSuch as 16:9.
editobject or nullChanges made in the image editor, or null.
Fields of edit
Only 1.versionintegerstepsany[]Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.
focalPointobject or nullFields of focalPoint
xnumber0 to 1 from the left.
ynumber0 to 1 from the top.
consentobject or nullFields of consent
referencestring or null
One of pending, approved, withdrawn.statusstringrestrictionsstring or null
subtitlesmap of stringSubtitle file addresses by language code.
sourceobject or nullSet when the file is linked from a media library connected in Orbit rather than stored in CMS Orbit. url is then the library's own address.
Fields of source
One of cloudinary, bynder, frontify.providerstringexternalIdstringThe file's id in that library.
400Bad requestThe body is empty or isn't valid JSON. Or the file isn't a JPEG, PNG, WebP or AVIF image, or the area is outside it.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks media:upload, or the token is read only.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such media, or it's in another organisation.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
422UnprocessableThe body doesn't match the schema. Each problem is in error.details.issues.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl -X POST 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media/6650f1c2a9e4b1d2c3f40a30/crop' \ -H 'Authorization: Bearer cms_mt_…' \ -H 'Content-Type: application/json' \ -d '{"area":{"x":0,"y":120,"width":1600,"height":900,"rotate":0},"aspect":"16:9","edit":{"version":1,"steps":[{"type":"straighten","angle":1.5},{"type":"redact","areas":[{"x":0.62,"y":0.71,"width":0.12,"height":0.05,"style":"pixelate"}]},{"type":"adjust","brightness":8,"contrast":0,"saturation":0,"warmth":12,"shadows":15,"highlights":-10},{"type":"look","name":"warm","strength":40}]}}'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Example answer
{ "data": { "id": "6650f1c2a9e4b1d2c3f40a45", "filename": "lofoten-kayaks.webp", "url": "https://media.northwilds.com/lofoten-kayaks.webp", "mimeType": "image/webp", "category": "image", "size": 4, "checksum": null, "width": 1, "height": 1, "folderId": "6650f1c2a9e4b1d2c3f40a20", "title": {}, "alt": { "en-GB": "Kayaks on a calm fjord" }, "caption": {}, "tags": [ "…" ], "createdAt": "2026-11-02T09:30:00.000Z", "original": { "url": "https://northwilds.com/trips/lofoten-sea-kayaking", "width": 1, "height": 1 }, "crop": { "x": 1, "y": 1, "width": 1, "height": 1, "rotate": 0, "aspect": null }, "edit": { "version": 1, "steps": [ null ] }, "focalPoint": { "x": 1, "y": 1 }, "consent": { "reference": null, "status": "pending", "restrictions": null }, "subtitles": {}, "source": { "provider": "cloudinary", "externalId": "6650f1c2a9e4b1d2c3f40a5a" } }}The same as crop, under a name that fits edits
POST/organisations/{organisationId}/spaces/{spaceId}/media/{mediaId}/editKey required
The same as crop, under a name that fits edits. Permission: media:upload.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
mediaIdstringpath, requiredThe media's id.
Idempotency-KeystringheaderOptional. A unique value, such as a UUID, that makes a retry safe: the same key with the same request within 24 hours returns the first answer again, with Idempotent-Replayed: true, instead of making the change twice. The same key with a different request gets 422; while the first request is still running, 409. Only successful answers are kept.
Up to 255 characters.
Request body
areaobject or nullrequiredIn pixels of the original after the quarter turn, flips and straightening. null removes the crop.
Fields of area
At least 0.xnumberrequired
At least 0.ynumberrequired
At least 1.widthnumberrequired
At least 1.heightnumberrequired
One of 0, 90, 180, 270.rotatenumberrequired
aspectstring or nulloptionalSuch as 16:9.
Up to 20 characters.editobject or nulloptionalThe image editor's changes: flip, straighten (-45 to 45 degrees), redact (areas as fractions of the straightened image, blurred or pixelated), adjust (-100 to 100 each), look (warm, cool, mono, noir, faded or vivid, strength 0 to 100) and sharpen (0 to 100). null removes them; leave it out to keep them. The original is kept either way.
Fields of edit
Default 1.version1optional
Up to 12 items.stepsobject or object or object or object or object or object[]requiredFields of steps
asCopybooleanoptionalKeep this file and add the result as a new one, answered with 201.
Default false.
Responses
200OKThe file, or 201 with a copy.dataMediaFields of data
idstringAn id.
filenamestringurlstringmimeTypestringcategorystringimage, video, document or other.
sizeintegerIn bytes.
checksumstring or nullThe SHA-256 of the stored file, in hex. null for files stored before checksums were kept.
widthinteger or nullheightinteger or nullfolderIdstring or nullAn id.
titlemap of stringBy language code.
altmap of stringBy language code, such as { "en-GB": "Kayaks on a calm fjord" }.
captionmap of stringBy language code.
tagsstring[]createdAtstringoriginalobject or nullThe file before the crop and edits, when it was kept. For an image with blurred areas, url is the media item's /original address, which needs media:upload.
Fields of original
urlstringwidthintegerheightinteger
cropobject or nullFields of crop
xnumberynumberwidthnumberheightnumber
One of 0, 90, 180, 270.rotateintegeraspectstring or nullSuch as 16:9.
editobject or nullChanges made in the image editor, or null.
Fields of edit
Only 1.versionintegerstepsany[]Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.
focalPointobject or nullFields of focalPoint
xnumber0 to 1 from the left.
ynumber0 to 1 from the top.
consentobject or nullFields of consent
referencestring or null
One of pending, approved, withdrawn.statusstringrestrictionsstring or null
subtitlesmap of stringSubtitle file addresses by language code.
sourceobject or nullSet when the file is linked from a media library connected in Orbit rather than stored in CMS Orbit. url is then the library's own address.
Fields of source
One of cloudinary, bynder, frontify.providerstringexternalIdstringThe file's id in that library.
201CreatedWith asCopy: the new file.dataMediaFields of data
idstringAn id.
filenamestringurlstringmimeTypestringcategorystringimage, video, document or other.
sizeintegerIn bytes.
checksumstring or nullThe SHA-256 of the stored file, in hex. null for files stored before checksums were kept.
widthinteger or nullheightinteger or nullfolderIdstring or nullAn id.
titlemap of stringBy language code.
altmap of stringBy language code, such as { "en-GB": "Kayaks on a calm fjord" }.
captionmap of stringBy language code.
tagsstring[]createdAtstringoriginalobject or nullThe file before the crop and edits, when it was kept. For an image with blurred areas, url is the media item's /original address, which needs media:upload.
Fields of original
urlstringwidthintegerheightinteger
cropobject or nullFields of crop
xnumberynumberwidthnumberheightnumber
One of 0, 90, 180, 270.rotateintegeraspectstring or nullSuch as 16:9.
editobject or nullChanges made in the image editor, or null.
Fields of edit
Only 1.versionintegerstepsany[]Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.
focalPointobject or nullFields of focalPoint
xnumber0 to 1 from the left.
ynumber0 to 1 from the top.
consentobject or nullFields of consent
referencestring or null
One of pending, approved, withdrawn.statusstringrestrictionsstring or null
subtitlesmap of stringSubtitle file addresses by language code.
sourceobject or nullSet when the file is linked from a media library connected in Orbit rather than stored in CMS Orbit. url is then the library's own address.
Fields of source
One of cloudinary, bynder, frontify.providerstringexternalIdstringThe file's id in that library.
400Bad requestThe body is empty or isn't valid JSON. Or the file isn't a JPEG, PNG, WebP or AVIF image, or the area is outside it.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks media:upload, or the token is read only.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such media, or it's in another organisation.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
422UnprocessableThe body doesn't match the schema. Each problem is in error.details.issues.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl -X POST 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media/6650f1c2a9e4b1d2c3f40a30/edit' \ -H 'Authorization: Bearer cms_mt_…' \ -H 'Content-Type: application/json' \ -d '{"area":{"x":0,"y":120,"width":1600,"height":900,"rotate":0},"aspect":"16:9","edit":{"version":1,"steps":[{"type":"straighten","angle":1.5},{"type":"redact","areas":[{"x":0.62,"y":0.71,"width":0.12,"height":0.05,"style":"pixelate"}]},{"type":"adjust","brightness":8,"contrast":0,"saturation":0,"warmth":12,"shadows":15,"highlights":-10},{"type":"look","name":"warm","strength":40}]}}'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Example answer
{ "data": { "id": "6650f1c2a9e4b1d2c3f40a45", "filename": "lofoten-kayaks.webp", "url": "https://media.northwilds.com/lofoten-kayaks.webp", "mimeType": "image/webp", "category": "image", "size": 4, "checksum": null, "width": 1, "height": 1, "folderId": "6650f1c2a9e4b1d2c3f40a20", "title": {}, "alt": { "en-GB": "Kayaks on a calm fjord" }, "caption": {}, "tags": [ "…" ], "createdAt": "2026-11-02T09:30:00.000Z", "original": { "url": "https://northwilds.com/trips/lofoten-sea-kayaking", "width": 1, "height": 1 }, "crop": { "x": 1, "y": 1, "width": 1, "height": 1, "rotate": 0, "aspect": null }, "edit": { "version": 1, "steps": [ null ] }, "focalPoint": { "x": 1, "y": 1 }, "consent": { "reference": null, "status": "pending", "restrictions": null }, "subtitles": {}, "source": { "provider": "cloudinary", "externalId": "6650f1c2a9e4b1d2c3f40a5a" } }}The kept original, for editors only, never cached
GET/organisations/{organisationId}/spaces/{spaceId}/media/{mediaId}/originalKey required
The kept original, for editors only, never cached. Permission: media:upload.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
mediaIdstringpath, requiredThe media's id.
Responses
200OKThe file the image is made from, answered with Cache-Control: private, no-store. An image with blurred areas keeps its original privately, and this is the only address that serves it.image/*
401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks media:upload.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such file, or it has no kept original.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media/6650f1c2a9e4b1d2c3f40a30/original' \ -H 'Authorization: Bearer cms_mt_…'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Replaces the original with the blurred image for good
DELETE/organisations/{organisationId}/spaces/{spaceId}/media/{mediaId}/originalKey required
Replaces the original with the blurred image for good. Permission: content:purge.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
mediaIdstringpath, requiredThe media's id.
Responses
200OKThe file.dataMediaFields of data
idstringAn id.
filenamestringurlstringmimeTypestringcategorystringimage, video, document or other.
sizeintegerIn bytes.
checksumstring or nullThe SHA-256 of the stored file, in hex. null for files stored before checksums were kept.
widthinteger or nullheightinteger or nullfolderIdstring or nullAn id.
titlemap of stringBy language code.
altmap of stringBy language code, such as { "en-GB": "Kayaks on a calm fjord" }.
captionmap of stringBy language code.
tagsstring[]createdAtstringoriginalobject or nullThe file before the crop and edits, when it was kept. For an image with blurred areas, url is the media item's /original address, which needs media:upload.
Fields of original
urlstringwidthintegerheightinteger
cropobject or nullFields of crop
xnumberynumberwidthnumberheightnumber
One of 0, 90, 180, 270.rotateintegeraspectstring or nullSuch as 16:9.
editobject or nullChanges made in the image editor, or null.
Fields of edit
Only 1.versionintegerstepsany[]Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.
focalPointobject or nullFields of focalPoint
xnumber0 to 1 from the left.
ynumber0 to 1 from the top.
consentobject or nullFields of consent
referencestring or null
One of pending, approved, withdrawn.statusstringrestrictionsstring or null
subtitlesmap of stringSubtitle file addresses by language code.
sourceobject or nullSet when the file is linked from a media library connected in Orbit rather than stored in CMS Orbit. url is then the library's own address.
Fields of source
One of cloudinary, bynder, frontify.providerstringexternalIdstringThe file's id in that library.
400Bad requestThe image has no blurred areas, so there is no original to remove.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks content:purge, or the token is read only.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such media, or it's in another organisation.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl -X DELETE 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media/6650f1c2a9e4b1d2c3f40a30/original' \ -H 'Authorization: Bearer cms_mt_…'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Example answer
{ "data": { "id": "6650f1c2a9e4b1d2c3f40a45", "filename": "lofoten-kayaks.webp", "url": "https://media.northwilds.com/lofoten-kayaks.webp", "mimeType": "image/webp", "category": "image", "size": 4, "checksum": null, "width": 1, "height": 1, "folderId": "6650f1c2a9e4b1d2c3f40a20", "title": {}, "alt": { "en-GB": "Kayaks on a calm fjord" }, "caption": {}, "tags": [ "…" ], "createdAt": "2026-11-02T09:30:00.000Z", "original": { "url": "https://northwilds.com/trips/lofoten-sea-kayaking", "width": 1, "height": 1 }, "crop": { "x": 1, "y": 1, "width": 1, "height": 1, "rotate": 0, "aspect": null }, "edit": { "version": 1, "steps": [ null ] }, "focalPoint": { "x": 1, "y": 1 }, "consent": { "reference": null, "status": "pending", "restrictions": null }, "subtitles": {}, "source": { "provider": "cloudinary", "externalId": "6650f1c2a9e4b1d2c3f40a5a" } }}Removes one language's subtitles
DELETE/organisations/{organisationId}/spaces/{spaceId}/media/{mediaId}/subtitlesKey required
Removes one language's subtitles. Permission: media:upload.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
mediaIdstringpath, requiredThe media's id.
localestringquery, requiredThe language whose subtitles to remove, such as nb-NO. Required.
Responses
200OKThe file.dataMediaFields of data
idstringAn id.
filenamestringurlstringmimeTypestringcategorystringimage, video, document or other.
sizeintegerIn bytes.
checksumstring or nullThe SHA-256 of the stored file, in hex. null for files stored before checksums were kept.
widthinteger or nullheightinteger or nullfolderIdstring or nullAn id.
titlemap of stringBy language code.
altmap of stringBy language code, such as { "en-GB": "Kayaks on a calm fjord" }.
captionmap of stringBy language code.
tagsstring[]createdAtstringoriginalobject or nullThe file before the crop and edits, when it was kept. For an image with blurred areas, url is the media item's /original address, which needs media:upload.
Fields of original
urlstringwidthintegerheightinteger
cropobject or nullFields of crop
xnumberynumberwidthnumberheightnumber
One of 0, 90, 180, 270.rotateintegeraspectstring or nullSuch as 16:9.
editobject or nullChanges made in the image editor, or null.
Fields of edit
Only 1.versionintegerstepsany[]Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.
focalPointobject or nullFields of focalPoint
xnumber0 to 1 from the left.
ynumber0 to 1 from the top.
consentobject or nullFields of consent
referencestring or null
One of pending, approved, withdrawn.statusstringrestrictionsstring or null
subtitlesmap of stringSubtitle file addresses by language code.
sourceobject or nullSet when the file is linked from a media library connected in Orbit rather than stored in CMS Orbit. url is then the library's own address.
Fields of source
One of cloudinary, bynder, frontify.providerstringexternalIdstringThe file's id in that library.
400Bad requestNo locale.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks media:upload, or the token is read only.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such media, or it's in another organisation.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl -X DELETE 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media/6650f1c2a9e4b1d2c3f40a30/subtitles?locale=nb-NO' \ -H 'Authorization: Bearer cms_mt_…'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Example answer
{ "data": { "id": "6650f1c2a9e4b1d2c3f40a45", "filename": "lofoten-kayaks.webp", "url": "https://media.northwilds.com/lofoten-kayaks.webp", "mimeType": "image/webp", "category": "image", "size": 4, "checksum": null, "width": 1, "height": 1, "folderId": "6650f1c2a9e4b1d2c3f40a20", "title": {}, "alt": { "en-GB": "Kayaks on a calm fjord" }, "caption": {}, "tags": [ "…" ], "createdAt": "2026-11-02T09:30:00.000Z", "original": { "url": "https://northwilds.com/trips/lofoten-sea-kayaking", "width": 1, "height": 1 }, "crop": { "x": 1, "y": 1, "width": 1, "height": 1, "rotate": 0, "aspect": null }, "edit": { "version": 1, "steps": [ null ] }, "focalPoint": { "x": 1, "y": 1 }, "consent": { "reference": null, "status": "pending", "restrictions": null }, "subtitles": {}, "source": { "provider": "cloudinary", "externalId": "6650f1c2a9e4b1d2c3f40a5a" } }}Adds WebVTT subtitles to a video
POST/organisations/{organisationId}/spaces/{spaceId}/media/{mediaId}/subtitlesKey required
Adds WebVTT subtitles to a video. Permission: media:upload.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
mediaIdstringpath, requiredThe media's id.
Idempotency-KeystringheaderOptional. A unique value, such as a UUID, that makes a retry safe: the same key with the same request within 24 hours returns the first answer again, with Idempotent-Replayed: true, instead of making the change twice. The same key with a different request gets 422; while the first request is still running, 409. Only successful answers are kept.
Up to 255 characters.
Request body
filestringrequiredA WebVTT file, up to 1 MB.
localestringrequiredThe language, such as nb-NO.
Responses
200OKThe file.dataMediaFields of data
idstringAn id.
filenamestringurlstringmimeTypestringcategorystringimage, video, document or other.
sizeintegerIn bytes.
checksumstring or nullThe SHA-256 of the stored file, in hex. null for files stored before checksums were kept.
widthinteger or nullheightinteger or nullfolderIdstring or nullAn id.
titlemap of stringBy language code.
altmap of stringBy language code, such as { "en-GB": "Kayaks on a calm fjord" }.
captionmap of stringBy language code.
tagsstring[]createdAtstringoriginalobject or nullThe file before the crop and edits, when it was kept. For an image with blurred areas, url is the media item's /original address, which needs media:upload.
Fields of original
urlstringwidthintegerheightinteger
cropobject or nullFields of crop
xnumberynumberwidthnumberheightnumber
One of 0, 90, 180, 270.rotateintegeraspectstring or nullSuch as 16:9.
editobject or nullChanges made in the image editor, or null.
Fields of edit
Only 1.versionintegerstepsany[]Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.
focalPointobject or nullFields of focalPoint
xnumber0 to 1 from the left.
ynumber0 to 1 from the top.
consentobject or nullFields of consent
referencestring or null
One of pending, approved, withdrawn.statusstringrestrictionsstring or null
subtitlesmap of stringSubtitle file addresses by language code.
sourceobject or nullSet when the file is linked from a media library connected in Orbit rather than stored in CMS Orbit. url is then the library's own address.
Fields of source
One of cloudinary, bynder, frontify.providerstringexternalIdstringThe file's id in that library.
400Bad requestNo file or locale, a file that isn't a video, or a subtitle file over 1 MB.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks media:upload, or the token is read only.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such media, or it's in another organisation.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl -X POST 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media/6650f1c2a9e4b1d2c3f40a30/subtitles' \ -H 'Authorization: Bearer cms_mt_…'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Example answer
{ "data": { "id": "6650f1c2a9e4b1d2c3f40a45", "filename": "lofoten-kayaks.webp", "url": "https://media.northwilds.com/lofoten-kayaks.webp", "mimeType": "image/webp", "category": "image", "size": 4, "checksum": null, "width": 1, "height": 1, "folderId": "6650f1c2a9e4b1d2c3f40a20", "title": {}, "alt": { "en-GB": "Kayaks on a calm fjord" }, "caption": {}, "tags": [ "…" ], "createdAt": "2026-11-02T09:30:00.000Z", "original": { "url": "https://northwilds.com/trips/lofoten-sea-kayaking", "width": 1, "height": 1 }, "crop": { "x": 1, "y": 1, "width": 1, "height": 1, "rotate": 0, "aspect": null }, "edit": { "version": 1, "steps": [ null ] }, "focalPoint": { "x": 1, "y": 1 }, "consent": { "reference": null, "status": "pending", "restrictions": null }, "subtitles": {}, "source": { "provider": "cloudinary", "externalId": "6650f1c2a9e4b1d2c3f40a5a" } }}Pages that use it
GET/organisations/{organisationId}/spaces/{spaceId}/media/{mediaId}/usageKey required
Pages that use it. Permission: media:read.
Parameters
organisationIdstringpath, requiredThe organisation's id, from the Management tokens page.
spaceIdstringpath, requiredThe space's id.
mediaIdstringpath, requiredThe media's id.
Responses
200OK[{ id, name, url, contentType, live }].dataobject[]Fields of data
idstringAn id.
namestringurlstring or nullcontentTypestringlivebooleanThe published page uses it, not only the draft.
401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
403ForbiddenLacks media:read.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
404Not foundNo such media, or it's in another organisation.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
500Server errorSomething went wrong on our side. Try again in a moment.errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
curl 'https://api.bifrostorbit.com/cms/manage/v1/organisations/6650f1c2a9e4b1d2c3f40a01/spaces/6650f1c2a9e4b1d2c3f40a02/media/6650f1c2a9e4b1d2c3f40a30/usage' \ -H 'Authorization: Bearer cms_mt_…'Try it
Management tokens are secret and act as a person, so nothing is sent from the docs.
Example answer
{ "data": [ { "id": "6650f1c2a9e4b1d2c3f40a40", "name": "Lofoten sea kayaking", "url": "https://northwilds.com/trips/lofoten-sea-kayaking", "contentType": "…", "live": true } ]}SchemasThe shapes the endpoints above answer with and take.
Error
Every error has this shape. Write code against code and the status, never the message.
errorobjectFields of error
One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.codestringmessagestringFollows Accept-Language when CMS Orbit has the language.
detailsanysometimesWhen there is more to read. On 422, issues: each field that failed, with path, message and code. On a field value that breaks the content type's rules, a list of { path, message }. On a version conflict, currentVersion, expected and received.
Media
idstringAn id.
filenamestringurlstringmimeTypestringcategorystringimage, video, document or other.
sizeintegerIn bytes.
checksumstring or nullThe SHA-256 of the stored file, in hex. null for files stored before checksums were kept.
widthinteger or nullheightinteger or nullfolderIdstring or nullAn id.
titlemap of stringBy language code.
altmap of stringBy language code, such as { "en-GB": "Kayaks on a calm fjord" }.
captionmap of stringBy language code.
tagsstring[]createdAtstringoriginalobject or nullThe file before the crop and edits, when it was kept. For an image with blurred areas, url is the media item's /original address, which needs media:upload.
Fields of original
urlstringwidthintegerheightinteger
cropobject or nullFields of crop
xnumberynumberwidthnumberheightnumber
One of 0, 90, 180, 270.rotateintegeraspectstring or nullSuch as 16:9.
editobject or nullChanges made in the image editor, or null.
Fields of edit
Only 1.versionintegerstepsany[]Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.
focalPointobject or nullFields of focalPoint
xnumber0 to 1 from the left.
ynumber0 to 1 from the top.
consentobject or nullFields of consent
referencestring or null
One of pending, approved, withdrawn.statusstringrestrictionsstring or null
subtitlesmap of stringSubtitle file addresses by language code.
sourceobject or nullSet when the file is linked from a media library connected in Orbit rather than stored in CMS Orbit. url is then the library's own address.
Fields of source
One of cloudinary, bynder, frontify.providerstringexternalIdstringThe file's id in that library.
MediaFolder
idstringAn id.
namestringparentIdstring or nullAn id.