id, a name, and an account_id, and media items track folder membership through a folders array.
Folders are an API-level feature. The in-app Media Library modal shows a single flat grid and doesn’t expose folder browsing or management — use the API to create, rename, and assign folders.
Create a folder
POST /v1/media/folders with a name creates a folder and returns its id.
List folders
GET /v1/media/folders returns your folders, newest first.
Rename a folder
PUT /v1/media/folders/{id} with a new name renames the folder. Returns 404 if the folder doesn’t exist in your account.
Delete a folder
DELETE /v1/media/folders/{id} deletes the folder. The folder’s id is removed from every media item’s folders array first, so no items are left pointing at a deleted folder.
Deleting a folder does not delete the media inside it — those items remain in your library with the folder removed from their
folders.Move items into a folder
PUT /v1/media/group with ids (the media items to move) and folder_id sets each item’s folder membership to that single folder. This replaces any existing folder assignment rather than appending.