Mimir REST API (1.0)

Returns the folder entry identified by folderId. Two well-known string aliases are also accepted in place of a folder UUID:

• tenant-root — the synthetic root folder under which every other folder in the tenant lives. Use this as the entry point for a folder-tree walk: GET /api/v1/folders/tenant-root returns the root's real id and kind: "tenant-root".
• archive-root — the synthetic root of the tenant's archive folder tree, when archive is enabled.

These aliases are also accepted as the parent of a POST /api/v1/folders create call. The kind field on the response distinguishes a synthetic root from a regular user-created folder.

Recursively delete a folder. All subfolders are removed. All items are soft-deleted, i.e. they are still accessible in the recycle bin.

Lists the children of folderId. The response shape and pagination contract depend on the type query parameter; the modes below cover the combinations and the differences between them.

Walking a folder tree (type=folder)

Pass ?type=folder to list only the immediate child folders. In this mode the response is a plain JSON array of folder entries, not the {from, total, hits} envelope shown in the schema. The array carries every direct child folder of the parent in a single response — there is no pagination cursor and no need for from/itemsPerPage. Each entry includes id, name, hasSubfolder, parent, owner, createdOn, and itemType: "folder".

This is the right call for building a folder browser or walking the full tree from tenant-root down. Use the hasSubfolder flag on each entry to skip recursion into leaf folders without paying an extra HTTP call per leaf.

Listing items in a folder (type=item or no filter)

Without type, or with type=item, the response uses the {from, total, hits} envelope documented in the schema, and mScrollId is not returned in this mode. Both from and itemsPerPage are honoured — use them to paginate through the results.

When itemsPerPage is omitted, OpenSearch defaults to 10 results per page. Pass itemsPerPage to get a larger page. The from field in the response reflects the from query parameter you sent.

To enumerate every item beneath a folder (and its subfolders), use ?fetchAllRecursively=true instead. This returns a different shape from the regular item-listing mode: hits are in items (not hits), from is absent, and mScrollId is present while more pages remain. Pass the cursor back as mScrollId on the next call until the response no longer carries it. See the third oneOf variant in the response schema for the exact shape.

Discovering the root

The root folder is reachable by the alias tenant-root — see GET /api/v1/folders/tenant-root for the discovery entry point. Once you have the root's id, walk down with ?type=folder calls.

Sends PUT /api/v1/folders/{folderId}/content with { "id": "<itemId>" } in the body. Note the trailing /content segment — the membership operations live one level deeper than /api/v1/folders/{folderId}, which targets the folder itself (rename, move, delete) and would return 405 Method Not Allowed for a PUT body in this shape.

An item can belong to multiple folders. Adding an item to a folder adds a reference to the item in this folder, unless it is already present (the call is idempotent — adding twice is a no-op).

Moving an item between folders

Folder membership is a multi-set: an item can have several folderParents simultaneously, and the API exposes per-membership add and remove operations rather than a single "set folders" call. To move an item from one folder to another:

1. GET /api/v1/items/{itemId} to read the item's current folderParents.
2. For each parent that is not the destination, DELETE /api/v1/folders/{parentId}/content?id=<itemId> to drop the membership.
3. PUT /api/v1/folders/{destinationId}/content with { "id": "<itemId>" } to add the destination membership.

The order of (2) and (3) does not matter for a single item, but doing the add first is safer if the source DELETE could fail — an item with no folder parents at all becomes harder to find again.

Removes one item's membership in the folder identified by folderId — the item itself is not deleted, and any other folders that contain it are unaffected.

Note the URL shape: membership operations live under /api/v1/folders/{folderId}/content, one level deeper than /api/v1/folders/{folderId} (which addresses the folder itself — DELETE on that path deletes the folder entity, not a membership).

Retrieve lightweight versions of the MDF entries of the tenant, without the field definitions

Retrieve the option lists of the tenant

This endpoint is used for polling items to known their state.

Creates an item entry placeholder with a description of which operations to apply when the item's media file will be uploaded. The request may use the 'sequenceDetails' field to describe the Mimir items this new item was created from. If this is the case, enabling a service like transcription will re-run the service on the uploaded media file; not enabling a service will cause the backend to derive the data from the segments that compose the new item. For instance, disabling transcription for an item made of two segments from existing Mimir items will generate a transcription by combining the cuts of the transcriptions found for the Mimir items the segments were taken from.

After the creation of the item entry, the next step is to actually upload the media file. In order to do that, it is necessary to first acquire the upload lock of the item to prevent concurrent modifications, which is done by using the item upload endpoint. The response object from this endpoint will include the necessary information to upload either as a single PUT request or as a multipart S3 upload.

Note that when uploading to an AWS S3 bucket, there is a restriction on the maximum size for a single PUT request. If the file size is lower than 5 gigabytes, the upload may be done with a single PUT towards the upload url. Otherwise, the upload must be done with a multipart S3 upload.

Single-PUT upload flow

1. POST /api/v1/items to create the item placeholder (this endpoint).
2. PUT /api/v1/items/{itemId}/upload with lockOwnerInstanceId, fileName, and contentType (no isMultiPartUpload). The response carries uploadSignedUrl.
3. PUT the file bytes to that signed URL with the same Content-Type. The signed URL authenticates the request — do not add the Mimir auth header on this call.
4. PATCH /api/v1/itemMetadata/{itemId}?readableMetadataFields=true to set title, description, or any other metadata field.

Multipart upload flow

1. POST /api/v1/items to create the item placeholder.
2. PUT /api/v1/items/{itemId}/upload with isMultiPartUpload=true, fileSize, contentType, and a lockOwnerInstanceId. The response carries the values you need on every subsequent multipart call — uploadId, uploadLocationId, targetKey, uploadPartCount, and uploadPartSize.
3. POST /api/v1/items/{itemId}/itemUploadPartsSignUrls with uploadId, uploadLocationId, targetKey, firstPartNumber, and partCount to receive a signed PUT URL per part. Pass uploadLocationId and targetKey verbatim from step 2 — omitting them returns an empty list with no error.
4. PUT each chunk of the file to its signed URL. Capture the ETag response header from each PUT.
5. POST /api/v1/items/{itemId}/multipartUploadComplete with uploadId, uploadLocationId, targetKey, and an uploadParts array of {PartNumber, ETag} pairs. Again pass uploadLocationId and targetKey from step 2; omitting them produces a 500 "Failed to reserve upload".
6. PATCH /api/v1/itemMetadata/{itemId}?readableMetadataFields=true to set metadata as in the single-PUT flow.

Virtual Clip

This endpoint also supports creating virtual clips. A virtual clip is a new Mimir item, but will have a reference to the media of the clip it has been created from. This allows for creating Mimir items based off the same source material, without duplicating the video footage in the storage.

Example payload to create a virtual clip:

  {
    "masterClipId": string,
    "inPoint": number,
    "outPoint": number,
    "title": string,
    "parentClipId": string,
    "startOffsetMasterClip": number
  }

Required
masterClipId: Mimir itemId of the master clip, from which the virtual clip will be created.
inPoint: TimeCode of selected in-point in milliseconds of the master clip.

Optional
outPoint: TimeCode of selected out-point in milliseconds of the master clip. If not provided, the end of the master clip will be considered as the outPoint.
title: Title of the new virtual clip item. For virtual clips this is the supported way to set the title at creation time — the top-level title field on the request body. The "deprecated: use metadata.formData.title" guidance on the title field applies only to file-upload items; for virtual clips, metadata.formData.title in the request body is not honoured. To read the title back, look at metadata.formData.title on the GET response (in readable-field-id mode).
parentClipId: If a virtual clip needs to be created from another virtual clip, then "parentClipId" is needed to relate them with each other. Otherwise virtual clip will be shown as children of the master clip.
parentClipId:
folderParents: An array of folder IDs. The newly created virtual clip item will appear in all the given folders instead of the folders where the source item belongs.
startOffsetMasterClip: If a virtual clip needs to be created from another virtual clip, then "startOffsetMasterClip" would be the source virtual clip's in-point.
visibleTo: Specify who can view this item.
updatableBy: Specify who can update this item.