# MediaLab API

> REST API to integrate with MediaLab.co.

Each MediaLab environment (lab) has its own API base URL: `https://<your-lab>/api`, for example `https://yourcompany.medialab.app/api`. Always call the lab the account belongs to; the server URL in this document points to a demo lab.

Authenticate every request with one of:

- **Private token**: a token generated for a single account, sent as `Authorization: Private-Token <token>`. Suited for server-to-server integrations.
- **OAuth2**: the authorization code flow via `/oauth2/authorize` and `/oauth2/token`, for apps acting on behalf of a user. Send the access token as `Authorization: Bearer <token>`. Each operation lists the scope it requires.

Requests and responses use JSON unless an operation states otherwise. Errors return an `ApiError` object with an `error` code and a `user_message` that can be shown to the end-user.

Treat ids as opaque values of the type documented for each field: some ids are strings, so do not assume an id is numeric.

- OpenAPI specification (JSON): https://www.medialab.app/docs/api/medialabv1.json
- Complete reference in a single file: https://www.medialab.app/docs/api/llms-full.txt
- Data models: https://www.medialab.app/docs/api/reference/models.md

## Reference

- [General](https://www.medialab.app/docs/api/reference/general.md): Check that the API is reachable and get information about the lab.
- [OAuth2](https://www.medialab.app/docs/api/reference/oauth2.md): Authorize an app with OAuth2 and exchange codes for access tokens.
- [DFS](https://www.medialab.app/docs/api/reference/dfs.md): Inspect storage blobs, manage storage containers and connect storage destinations.
- [Faces / Persons](https://www.medialab.app/docs/api/reference/faces/persons.md): Manage the persons recognized by face detection.
- [Files](https://www.medialab.app/docs/api/reference/files.md): List, get, delete, download, transcode, move, copy and share files and their formats.
- [Files / Archive](https://www.medialab.app/docs/api/reference/files/archive.md): Archive files, restore them, or copy them back out of the archive.
- [Files / Captions](https://www.medialab.app/docs/api/reference/files/captions.md): Add, update, download and delete captions of a file.
- [Files / Chapters](https://www.medialab.app/docs/api/reference/files/chapters.md): Manage the chapters of a video or audio file.
- [Files / Comments](https://www.medialab.app/docs/api/reference/files/comments.md): Read, add and delete comments on a file and their reactions.
- [Files / Faces](https://www.medialab.app/docs/api/reference/files/faces.md): Get the faces detected in a file and tag persons manually.
- [Files / Meta](https://www.medialab.app/docs/api/reference/files/meta.md): Read and update the custom metadata of a file.
- [Files / Reactions](https://www.medialab.app/docs/api/reference/files/reactions.md): Read, add and remove reactions on a file.
- [Files / Workflows](https://www.medialab.app/docs/api/reference/files/workflows.md): List the workflows available for a file and start one.
- [Folders](https://www.medialab.app/docs/api/reference/folders.md): Get, create, edit, delete, copy, move and share folders and list their contents.
- [Folders / Archive](https://www.medialab.app/docs/api/reference/folders/archive.md): Archive folders, restore them, or copy content back out of the archive.
- [Folders / Notifications](https://www.medialab.app/docs/api/reference/folders/notifications.md): Read and update the notification settings of a folder.
- [Folders / Reactions](https://www.medialab.app/docs/api/reference/folders/reactions.md): Read the reactions on the files in a folder.
- [Folders / Workflows](https://www.medialab.app/docs/api/reference/folders/workflows.md): List the workflows available for a folder and start one.
- [Livestreams](https://www.medialab.app/docs/api/reference/livestreams.md): Manage livestreams.
- [Meta](https://www.medialab.app/docs/api/reference/meta.md): Read metadata fields and their options, and manage the metadata template.
- [oEmbed](https://www.medialab.app/docs/api/reference/oembed.md): Get oEmbed information to embed a share link on another site.
- [Playlists](https://www.medialab.app/docs/api/reference/playlists.md): Manage playlists, their files, and share them by email or link.
- [Push](https://www.medialab.app/docs/api/reference/push.md): Manage push destinations and auto-push rules, and follow the status of pushes.
- [Search](https://www.medialab.app/docs/api/reference/search.md): Search for files and folders and get the available search filters.
- [Settings / Brands](https://www.medialab.app/docs/api/reference/settings/brands.md): Manage brands, their files and the user groups they apply to.
- [Settings / Permissions](https://www.medialab.app/docs/api/reference/settings/permissions.md): Manage user groups and read the available permission levels.
- [Settings / SSO](https://www.medialab.app/docs/api/reference/settings/sso.md): Read single sign-on connections and connection presets.
- [Settings / Trash](https://www.medialab.app/docs/api/reference/settings/trash.md): Restore or permanently delete files and folders in the trash.
- [Share / Alias](https://www.medialab.app/docs/api/reference/share/alias.md): Manage share aliases, the sender name, email address and signature used for share emails.
- [Share / Email](https://www.medialab.app/docs/api/reference/share/email.md): Share files, folders or playlists by email with personal links and track sign-ups.
- [Share / Upload](https://www.medialab.app/docs/api/reference/share/upload.md): Create and manage upload links that let others send files to a folder.
- [Share / Watch](https://www.medialab.app/docs/api/reference/share/watch.md): Share files, folders or playlists with a public link and manage those links.
- [Upload](https://www.medialab.app/docs/api/reference/upload.md): Upload files with TUS, POST, S3 single or multipart uploads, from a URL, or from remote storage.
- [User](https://www.medialab.app/docs/api/reference/user.md): Get the authenticated user's info, avatar and notifications.
- [User / Bookmarks](https://www.medialab.app/docs/api/reference/user/bookmarks.md): Manage the authenticated user's file and folder bookmarks.
- [User / Contacts](https://www.medialab.app/docs/api/reference/user/contacts.md): List and search the authenticated user's contacts.
- [Users](https://www.medialab.app/docs/api/reference/users.md): Get information and the avatar of another user.
- [Workflows](https://www.medialab.app/docs/api/reference/workflows.md): List the available workflows and get their details.

## Read more

- [Help centre and developer guides](https://www.medialab.co/llms.txt): Index of all help articles and developer guides (authentication, uploads, webhooks, metadata templates, MCP server).