Skip to content

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, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

Responses

  • 200OKList of files.
    • dataMedia[]

      Newest first.

      Fields of data
      • idstring

        An id.

      • filenamestring

      • urlstring

      • mimeTypestring

      • categorystring

        image, video, document or other.

      • sizeinteger

        In bytes.

      • checksumstring or null

        The SHA-256 of the stored file, in hex. null for files stored before checksums were kept.

      • widthinteger or null

      • heightinteger or null

      • folderIdstring or null

        An id.

      • titlemap of string

        By language code.

      • altmap of string

        By language code, such as { "en-GB": "Kayaks on a calm fjord" }.

      • captionmap of string

        By language code.

      • tagsstring[]

      • createdAtstring

      • originalobject or null

        The 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
        • urlstring

        • widthinteger

        • heightinteger

      • cropobject or null

        Fields of crop
        • xnumber

        • ynumber

        • widthnumber

        • heightnumber

        • rotateinteger

          One of 0, 90, 180, 270.
        • aspectstring or null

          Such as 16:9.

      • editobject or null

        Changes made in the image editor, or null.

        Fields of edit
        • versioninteger

          Only 1.
        • stepsany[]

          Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.

      • focalPointobject or null

        Fields of focalPoint
        • xnumber

          0 to 1 from the left.

        • ynumber

          0 to 1 from the top.

      • consentobject or null

        Fields of consent
        • referencestring or null

        • statusstring

          One of pending, approved, withdrawn.
        • restrictionsstring or null

      • subtitlesmap of string

        Subtitle file addresses by language code.

      • sourceobject or null

        Set 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
        • providerstring

          One of cloudinary, bynder, frontify.
        • externalIdstring

          The file's id in that library.

  • 401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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

200 OKJSON
{  "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, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

  • Idempotency-Keystringheader

    Optional. 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

  • filestringrequired

    JPEG, PNG, WebP, AVIF, GIF, SVG, PDF, MP4 or WebM, up to 25 MB. JPEG and PNG are stored as WebP.

  • folderIdstringoptional

    A media folder's id.

  • cropstringoptional

    A crop to apply at once, as JSON text: { "area": { "x", "y", "width", "height", "rotate" }, "aspect": "16:9" }.

  • keepOriginalstringoptional

    true keeps the uncropped file as well.

    One of true, false.

Responses

  • 201CreatedThe file.
    • dataMedia

      The file. A file the library already has answers with the existing one.

      Fields of data
      • idstring

        An id.

      • filenamestring

      • urlstring

      • mimeTypestring

      • categorystring

        image, video, document or other.

      • sizeinteger

        In bytes.

      • checksumstring or null

        The SHA-256 of the stored file, in hex. null for files stored before checksums were kept.

      • widthinteger or null

      • heightinteger or null

      • folderIdstring or null

        An id.

      • titlemap of string

        By language code.

      • altmap of string

        By language code, such as { "en-GB": "Kayaks on a calm fjord" }.

      • captionmap of string

        By language code.

      • tagsstring[]

      • createdAtstring

      • originalobject or null

        The 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
        • urlstring

        • widthinteger

        • heightinteger

      • cropobject or null

        Fields of crop
        • xnumber

        • ynumber

        • widthnumber

        • heightnumber

        • rotateinteger

          One of 0, 90, 180, 270.
        • aspectstring or null

          Such as 16:9.

      • editobject or null

        Changes made in the image editor, or null.

        Fields of edit
        • versioninteger

          Only 1.
        • stepsany[]

          Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.

      • focalPointobject or null

        Fields of focalPoint
        • xnumber

          0 to 1 from the left.

        • ynumber

          0 to 1 from the top.

      • consentobject or null

        Fields of consent
        • referencestring or null

        • statusstring

          One of pending, approved, withdrawn.
        • restrictionsstring or null

      • subtitlesmap of string

        Subtitle file addresses by language code.

      • sourceobject or null

        Set 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
        • providerstring

          One of cloudinary, bynder, frontify.
        • externalIdstring

          The 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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

201 CreatedJSON
{  "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, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

Responses

  • 200OK[{ id, name, parentId }].
    • dataMediaFolder[]

      Fields of data
      • idstring

        An id.

      • namestring

      • parentIdstring or null

        An id.

  • 401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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

200 OKJSON
{  "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, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

  • Idempotency-Keystringheader

    Optional. 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

  • namestringrequired

    Up to 200 characters.
  • parentIdstring or nulloptional

    An id.

Responses

  • 201CreatedThe new item.
    • dataMediaFolder

      Fields of data
      • idstring

        An id.

      • namestring

      • parentIdstring or null

        An id.

  • 400Bad requestThe body is empty or isn't valid JSON.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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

201 CreatedJSON
{  "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, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

  • folderIdstringpath, required

    The 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

  • folderIdstringpath, required

    The folder's id.

  • Idempotency-Keystringheader

    Optional. 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

  • namestringoptional

    Up to 200 characters.

Responses

  • 200OKThe folder.
    • dataMediaFolder

      Fields of data
      • idstring

        An id.

      • namestring

      • parentIdstring or null

        An id.

  • 400Bad requestThe body is empty or isn't valid JSON.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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

200 OKJSON
{  "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, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

Responses

  • 200OK{ erased }.
    • dataobject

      Fields of data
      • erasedinteger

        How many files were erased.

  • 401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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

200 OKJSON
{  "data": {    "erased": 1  }}

Files in the bin

GET/organisations/{organisationId}/spaces/{spaceId}/media/trashKey required

Files in the bin. Permission: media:read.

Parameters

  • organisationIdstringpath, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

Responses

  • 200OKList.
    • dataobject[]

      Fields of data
      • idstring

        An id.

      • filenamestring

      • urlstring

      • mimeTypestring

      • sizeinteger

      • deletedAtstring

  • 401UnauthorisedNo token, or a token that is unknown, expired or revoked, or whose person no longer has access.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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

200 OKJSON
{  "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, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

  • mediaIdstringpath, required

    The 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

  • mediaIdstringpath, required

    The media's id.

  • Idempotency-Keystringheader

    Optional. 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

  • mediaIdstringpath, required

    The 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

  • mediaIdstringpath, required

    The media's id.

  • Idempotency-Keystringheader

    Optional. 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

  • filenamestringoptional

    Up to 200 characters.
  • folderIdstring or nulloptional

    An id.

  • titlemap of stringoptional

    By language code.

  • altmap of stringoptional

    By language code, such as { "en-GB": "Kayaks on a calm fjord" }. Up to 500 characters each.

  • captionmap of stringoptional

    By language code.

  • tagsstring[]optional

    Up to 50 items.
  • focalPointobject or nulloptional

    From 0 to 1, x from the left and y from the top.

    Fields of focalPoint
    • xnumberrequired

      At least 0. At most 1.
    • ynumberrequired

      At least 0. At most 1.
  • consentobject or nulloptional

    For photos of people.

    Fields of consent
    • referencestring or nulloptional

      Default null. Up to 120 characters.
    • statusstringoptional

      One of pending, approved, withdrawn. Default "pending".
    • restrictionsstring or nulloptional

      Default null. Up to 500 characters.

Responses

  • 200OKThe file.
    • dataMedia

      Fields of data
      • idstring

        An id.

      • filenamestring

      • urlstring

      • mimeTypestring

      • categorystring

        image, video, document or other.

      • sizeinteger

        In bytes.

      • checksumstring or null

        The SHA-256 of the stored file, in hex. null for files stored before checksums were kept.

      • widthinteger or null

      • heightinteger or null

      • folderIdstring or null

        An id.

      • titlemap of string

        By language code.

      • altmap of string

        By language code, such as { "en-GB": "Kayaks on a calm fjord" }.

      • captionmap of string

        By language code.

      • tagsstring[]

      • createdAtstring

      • originalobject or null

        The 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
        • urlstring

        • widthinteger

        • heightinteger

      • cropobject or null

        Fields of crop
        • xnumber

        • ynumber

        • widthnumber

        • heightnumber

        • rotateinteger

          One of 0, 90, 180, 270.
        • aspectstring or null

          Such as 16:9.

      • editobject or null

        Changes made in the image editor, or null.

        Fields of edit
        • versioninteger

          Only 1.
        • stepsany[]

          Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.

      • focalPointobject or null

        Fields of focalPoint
        • xnumber

          0 to 1 from the left.

        • ynumber

          0 to 1 from the top.

      • consentobject or null

        Fields of consent
        • referencestring or null

        • statusstring

          One of pending, approved, withdrawn.
        • restrictionsstring or null

      • subtitlesmap of string

        Subtitle file addresses by language code.

      • sourceobject or null

        Set 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
        • providerstring

          One of cloudinary, bynder, frontify.
        • externalIdstring

          The file's id in that library.

  • 400Bad requestThe body is empty or isn't valid JSON.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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

200 OKJSON
{  "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, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

  • mediaIdstringpath, required

    The media's id.

  • Idempotency-Keystringheader

    Optional. 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 nullrequired

    In pixels of the original after the quarter turn, flips and straightening. null removes the crop.

    Fields of area
    • xnumberrequired

      At least 0.
    • ynumberrequired

      At least 0.
    • widthnumberrequired

      At least 1.
    • heightnumberrequired

      At least 1.
    • rotatenumberrequired

      One of 0, 90, 180, 270.
  • aspectstring or nulloptional

    Such as 16:9.

    Up to 20 characters.
  • editobject or nulloptional

    The 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
    • version1optional

      Default 1.
    • stepsobject or object or object or object or object or object[]required

      Up to 12 items.
      Fields of steps
  • asCopybooleanoptional

    Keep this file and add the result as a new one, answered with 201.

    Default false.

Responses

  • 200OKThe file, or 201 with a copy.
    • dataMedia

      Fields of data
      • idstring

        An id.

      • filenamestring

      • urlstring

      • mimeTypestring

      • categorystring

        image, video, document or other.

      • sizeinteger

        In bytes.

      • checksumstring or null

        The SHA-256 of the stored file, in hex. null for files stored before checksums were kept.

      • widthinteger or null

      • heightinteger or null

      • folderIdstring or null

        An id.

      • titlemap of string

        By language code.

      • altmap of string

        By language code, such as { "en-GB": "Kayaks on a calm fjord" }.

      • captionmap of string

        By language code.

      • tagsstring[]

      • createdAtstring

      • originalobject or null

        The 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
        • urlstring

        • widthinteger

        • heightinteger

      • cropobject or null

        Fields of crop
        • xnumber

        • ynumber

        • widthnumber

        • heightnumber

        • rotateinteger

          One of 0, 90, 180, 270.
        • aspectstring or null

          Such as 16:9.

      • editobject or null

        Changes made in the image editor, or null.

        Fields of edit
        • versioninteger

          Only 1.
        • stepsany[]

          Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.

      • focalPointobject or null

        Fields of focalPoint
        • xnumber

          0 to 1 from the left.

        • ynumber

          0 to 1 from the top.

      • consentobject or null

        Fields of consent
        • referencestring or null

        • statusstring

          One of pending, approved, withdrawn.
        • restrictionsstring or null

      • subtitlesmap of string

        Subtitle file addresses by language code.

      • sourceobject or null

        Set 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
        • providerstring

          One of cloudinary, bynder, frontify.
        • externalIdstring

          The file's id in that library.

  • 201CreatedWith asCopy: the new file.
    • dataMedia

      Fields of data
      • idstring

        An id.

      • filenamestring

      • urlstring

      • mimeTypestring

      • categorystring

        image, video, document or other.

      • sizeinteger

        In bytes.

      • checksumstring or null

        The SHA-256 of the stored file, in hex. null for files stored before checksums were kept.

      • widthinteger or null

      • heightinteger or null

      • folderIdstring or null

        An id.

      • titlemap of string

        By language code.

      • altmap of string

        By language code, such as { "en-GB": "Kayaks on a calm fjord" }.

      • captionmap of string

        By language code.

      • tagsstring[]

      • createdAtstring

      • originalobject or null

        The 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
        • urlstring

        • widthinteger

        • heightinteger

      • cropobject or null

        Fields of crop
        • xnumber

        • ynumber

        • widthnumber

        • heightnumber

        • rotateinteger

          One of 0, 90, 180, 270.
        • aspectstring or null

          Such as 16:9.

      • editobject or null

        Changes made in the image editor, or null.

        Fields of edit
        • versioninteger

          Only 1.
        • stepsany[]

          Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.

      • focalPointobject or null

        Fields of focalPoint
        • xnumber

          0 to 1 from the left.

        • ynumber

          0 to 1 from the top.

      • consentobject or null

        Fields of consent
        • referencestring or null

        • statusstring

          One of pending, approved, withdrawn.
        • restrictionsstring or null

      • subtitlesmap of string

        Subtitle file addresses by language code.

      • sourceobject or null

        Set 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
        • providerstring

          One of cloudinary, bynder, frontify.
        • externalIdstring

          The 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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

200 OKJSON
{  "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, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

  • mediaIdstringpath, required

    The media's id.

  • Idempotency-Keystringheader

    Optional. 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 nullrequired

    In pixels of the original after the quarter turn, flips and straightening. null removes the crop.

    Fields of area
    • xnumberrequired

      At least 0.
    • ynumberrequired

      At least 0.
    • widthnumberrequired

      At least 1.
    • heightnumberrequired

      At least 1.
    • rotatenumberrequired

      One of 0, 90, 180, 270.
  • aspectstring or nulloptional

    Such as 16:9.

    Up to 20 characters.
  • editobject or nulloptional

    The 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
    • version1optional

      Default 1.
    • stepsobject or object or object or object or object or object[]required

      Up to 12 items.
      Fields of steps
  • asCopybooleanoptional

    Keep this file and add the result as a new one, answered with 201.

    Default false.

Responses

  • 200OKThe file, or 201 with a copy.
    • dataMedia

      Fields of data
      • idstring

        An id.

      • filenamestring

      • urlstring

      • mimeTypestring

      • categorystring

        image, video, document or other.

      • sizeinteger

        In bytes.

      • checksumstring or null

        The SHA-256 of the stored file, in hex. null for files stored before checksums were kept.

      • widthinteger or null

      • heightinteger or null

      • folderIdstring or null

        An id.

      • titlemap of string

        By language code.

      • altmap of string

        By language code, such as { "en-GB": "Kayaks on a calm fjord" }.

      • captionmap of string

        By language code.

      • tagsstring[]

      • createdAtstring

      • originalobject or null

        The 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
        • urlstring

        • widthinteger

        • heightinteger

      • cropobject or null

        Fields of crop
        • xnumber

        • ynumber

        • widthnumber

        • heightnumber

        • rotateinteger

          One of 0, 90, 180, 270.
        • aspectstring or null

          Such as 16:9.

      • editobject or null

        Changes made in the image editor, or null.

        Fields of edit
        • versioninteger

          Only 1.
        • stepsany[]

          Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.

      • focalPointobject or null

        Fields of focalPoint
        • xnumber

          0 to 1 from the left.

        • ynumber

          0 to 1 from the top.

      • consentobject or null

        Fields of consent
        • referencestring or null

        • statusstring

          One of pending, approved, withdrawn.
        • restrictionsstring or null

      • subtitlesmap of string

        Subtitle file addresses by language code.

      • sourceobject or null

        Set 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
        • providerstring

          One of cloudinary, bynder, frontify.
        • externalIdstring

          The file's id in that library.

  • 201CreatedWith asCopy: the new file.
    • dataMedia

      Fields of data
      • idstring

        An id.

      • filenamestring

      • urlstring

      • mimeTypestring

      • categorystring

        image, video, document or other.

      • sizeinteger

        In bytes.

      • checksumstring or null

        The SHA-256 of the stored file, in hex. null for files stored before checksums were kept.

      • widthinteger or null

      • heightinteger or null

      • folderIdstring or null

        An id.

      • titlemap of string

        By language code.

      • altmap of string

        By language code, such as { "en-GB": "Kayaks on a calm fjord" }.

      • captionmap of string

        By language code.

      • tagsstring[]

      • createdAtstring

      • originalobject or null

        The 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
        • urlstring

        • widthinteger

        • heightinteger

      • cropobject or null

        Fields of crop
        • xnumber

        • ynumber

        • widthnumber

        • heightnumber

        • rotateinteger

          One of 0, 90, 180, 270.
        • aspectstring or null

          Such as 16:9.

      • editobject or null

        Changes made in the image editor, or null.

        Fields of edit
        • versioninteger

          Only 1.
        • stepsany[]

          Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.

      • focalPointobject or null

        Fields of focalPoint
        • xnumber

          0 to 1 from the left.

        • ynumber

          0 to 1 from the top.

      • consentobject or null

        Fields of consent
        • referencestring or null

        • statusstring

          One of pending, approved, withdrawn.
        • restrictionsstring or null

      • subtitlesmap of string

        Subtitle file addresses by language code.

      • sourceobject or null

        Set 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
        • providerstring

          One of cloudinary, bynder, frontify.
        • externalIdstring

          The 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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

200 OKJSON
{  "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, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

  • mediaIdstringpath, required

    The 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

  • mediaIdstringpath, required

    The media's id.

Responses

  • 200OKThe file.
    • dataMedia

      Fields of data
      • idstring

        An id.

      • filenamestring

      • urlstring

      • mimeTypestring

      • categorystring

        image, video, document or other.

      • sizeinteger

        In bytes.

      • checksumstring or null

        The SHA-256 of the stored file, in hex. null for files stored before checksums were kept.

      • widthinteger or null

      • heightinteger or null

      • folderIdstring or null

        An id.

      • titlemap of string

        By language code.

      • altmap of string

        By language code, such as { "en-GB": "Kayaks on a calm fjord" }.

      • captionmap of string

        By language code.

      • tagsstring[]

      • createdAtstring

      • originalobject or null

        The 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
        • urlstring

        • widthinteger

        • heightinteger

      • cropobject or null

        Fields of crop
        • xnumber

        • ynumber

        • widthnumber

        • heightnumber

        • rotateinteger

          One of 0, 90, 180, 270.
        • aspectstring or null

          Such as 16:9.

      • editobject or null

        Changes made in the image editor, or null.

        Fields of edit
        • versioninteger

          Only 1.
        • stepsany[]

          Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.

      • focalPointobject or null

        Fields of focalPoint
        • xnumber

          0 to 1 from the left.

        • ynumber

          0 to 1 from the top.

      • consentobject or null

        Fields of consent
        • referencestring or null

        • statusstring

          One of pending, approved, withdrawn.
        • restrictionsstring or null

      • subtitlesmap of string

        Subtitle file addresses by language code.

      • sourceobject or null

        Set 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
        • providerstring

          One of cloudinary, bynder, frontify.
        • externalIdstring

          The file's id in that library.

  • 400Bad requestThe image has no blurred areas, so there is no original to remove.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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

200 OKJSON
{  "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, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

  • mediaIdstringpath, required

    The media's id.

  • localestringquery, required

    The language whose subtitles to remove, such as nb-NO. Required.

Responses

  • 200OKThe file.
    • dataMedia

      Fields of data
      • idstring

        An id.

      • filenamestring

      • urlstring

      • mimeTypestring

      • categorystring

        image, video, document or other.

      • sizeinteger

        In bytes.

      • checksumstring or null

        The SHA-256 of the stored file, in hex. null for files stored before checksums were kept.

      • widthinteger or null

      • heightinteger or null

      • folderIdstring or null

        An id.

      • titlemap of string

        By language code.

      • altmap of string

        By language code, such as { "en-GB": "Kayaks on a calm fjord" }.

      • captionmap of string

        By language code.

      • tagsstring[]

      • createdAtstring

      • originalobject or null

        The 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
        • urlstring

        • widthinteger

        • heightinteger

      • cropobject or null

        Fields of crop
        • xnumber

        • ynumber

        • widthnumber

        • heightnumber

        • rotateinteger

          One of 0, 90, 180, 270.
        • aspectstring or null

          Such as 16:9.

      • editobject or null

        Changes made in the image editor, or null.

        Fields of edit
        • versioninteger

          Only 1.
        • stepsany[]

          Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.

      • focalPointobject or null

        Fields of focalPoint
        • xnumber

          0 to 1 from the left.

        • ynumber

          0 to 1 from the top.

      • consentobject or null

        Fields of consent
        • referencestring or null

        • statusstring

          One of pending, approved, withdrawn.
        • restrictionsstring or null

      • subtitlesmap of string

        Subtitle file addresses by language code.

      • sourceobject or null

        Set 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
        • providerstring

          One of cloudinary, bynder, frontify.
        • externalIdstring

          The file's id in that library.

  • 400Bad requestNo locale.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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

200 OKJSON
{  "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, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

  • mediaIdstringpath, required

    The media's id.

  • Idempotency-Keystringheader

    Optional. 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

  • filestringrequired

    A WebVTT file, up to 1 MB.

  • localestringrequired

    The language, such as nb-NO.

Responses

  • 200OKThe file.
    • dataMedia

      Fields of data
      • idstring

        An id.

      • filenamestring

      • urlstring

      • mimeTypestring

      • categorystring

        image, video, document or other.

      • sizeinteger

        In bytes.

      • checksumstring or null

        The SHA-256 of the stored file, in hex. null for files stored before checksums were kept.

      • widthinteger or null

      • heightinteger or null

      • folderIdstring or null

        An id.

      • titlemap of string

        By language code.

      • altmap of string

        By language code, such as { "en-GB": "Kayaks on a calm fjord" }.

      • captionmap of string

        By language code.

      • tagsstring[]

      • createdAtstring

      • originalobject or null

        The 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
        • urlstring

        • widthinteger

        • heightinteger

      • cropobject or null

        Fields of crop
        • xnumber

        • ynumber

        • widthnumber

        • heightnumber

        • rotateinteger

          One of 0, 90, 180, 270.
        • aspectstring or null

          Such as 16:9.

      • editobject or null

        Changes made in the image editor, or null.

        Fields of edit
        • versioninteger

          Only 1.
        • stepsany[]

          Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.

      • focalPointobject or null

        Fields of focalPoint
        • xnumber

          0 to 1 from the left.

        • ynumber

          0 to 1 from the top.

      • consentobject or null

        Fields of consent
        • referencestring or null

        • statusstring

          One of pending, approved, withdrawn.
        • restrictionsstring or null

      • subtitlesmap of string

        Subtitle file addresses by language code.

      • sourceobject or null

        Set 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
        • providerstring

          One of cloudinary, bynder, frontify.
        • externalIdstring

          The 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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

200 OKJSON
{  "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, required

    The organisation's id, from the Management tokens page.

  • spaceIdstringpath, required

    The space's id.

  • mediaIdstringpath, required

    The media's id.

Responses

  • 200OK[{ id, name, url, contentType, live }].
    • dataobject[]

      Fields of data
      • idstring

        An id.

      • namestring

      • urlstring or null

      • contentTypestring

      • liveboolean

        The 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.
    • errorobject

      Fields of error
      • codestring

        One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
      • messagestring

        Follows Accept-Language when CMS Orbit has the language.

      • detailsanysometimes

        When 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.

Shell
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

200 OKJSON
{  "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.

  • errorobject

    Fields of error
    • codestring

      One of bad_request, unauthorized, forbidden, not_found, created_in_orbit, conflict, validation_failed, internal_error, unavailable.
    • messagestring

      Follows Accept-Language when CMS Orbit has the language.

    • detailsanysometimes

      When 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

  • idstring

    An id.

  • filenamestring

  • urlstring

  • mimeTypestring

  • categorystring

    image, video, document or other.

  • sizeinteger

    In bytes.

  • checksumstring or null

    The SHA-256 of the stored file, in hex. null for files stored before checksums were kept.

  • widthinteger or null

  • heightinteger or null

  • folderIdstring or null

    An id.

  • titlemap of string

    By language code.

  • altmap of string

    By language code, such as { "en-GB": "Kayaks on a calm fjord" }.

  • captionmap of string

    By language code.

  • tagsstring[]

  • createdAtstring

  • originalobject or null

    The 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
    • urlstring

    • widthinteger

    • heightinteger

  • cropobject or null

    Fields of crop
    • xnumber

    • ynumber

    • widthnumber

    • heightnumber

    • rotateinteger

      One of 0, 90, 180, 270.
    • aspectstring or null

      Such as 16:9.

  • editobject or null

    Changes made in the image editor, or null.

    Fields of edit
    • versioninteger

      Only 1.
    • stepsany[]

      Applied in this order: flip, straighten, redact, then the crop, then adjust, look and sharpen.

  • focalPointobject or null

    Fields of focalPoint
    • xnumber

      0 to 1 from the left.

    • ynumber

      0 to 1 from the top.

  • consentobject or null

    Fields of consent
    • referencestring or null

    • statusstring

      One of pending, approved, withdrawn.
    • restrictionsstring or null

  • subtitlesmap of string

    Subtitle file addresses by language code.

  • sourceobject or null

    Set 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
    • providerstring

      One of cloudinary, bynder, frontify.
    • externalIdstring

      The file's id in that library.

MediaFolder

  • idstring

    An id.

  • namestring

  • parentIdstring or null

    An id.