A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Vimeo API is how an app or AI agent works with a Vimeo account: uploading a video, editing its title and privacy, organizing videos into showcases and folders, or posting a comment on someone's behalf. Access is granted through an OAuth access token, and the token carries scopes like private, edit, upload, and delete that set which actions a call is allowed to take. Each request names the API version it wants, so a representation never changes underneath an integration without an explicit move.
How an app or AI agent connects to Vimeo determines what it can reach. There is a route for making calls, authenticated with an OAuth access token, and a route for receiving events through app webhooks, and each is governed by the token behind it and the scopes that token carries.
The REST API returns JSON and pages through lists with page and per_page, at https://api.vimeo.com. A call authenticates with an OAuth 2.0 access token sent as a Bearer token, and each request pins the API version in the Accept header (application/vnd.vimeo.*+json;version=3.4). The /me path is shorthand for the signed-in user.
Video bytes are not posted to the REST API directly. A POST to /me/videos returns a tus upload link, and the file is transferred to that link using the open tus protocol, which sends the file in resumable chunks so an interrupted upload continues instead of restarting. This is the upload method since API version 3.4.
An API app can register a webhook URL for a limited set of events, like video.upload.complete and video.play. Vimeo POSTs to the URL when an event fires, and the receiver verifies the vimeo-signature header against the app's secret to confirm the request came from Vimeo. There is no event for transcode completion, so transcode status is polled.
The authorization code grant sends a member to Vimeo to approve the requested scopes, then exchanges the returned code for a user access token that acts on that member's account. The token is sent as a Bearer token and reaches only what its scopes allow. This is the flow for acting on behalf of a person.
The client credentials grant exchanges an app's client id and secret for an unauthenticated app access token tied to no user. It can read public data and is used for server-to-server tasks that do not act on a member. It cannot reach nonpublic videos or take actions that need a user's consent.
An app owner can generate a personal access token in the developer dashboard, scoped to the chosen permissions, to call the API as their own account without running the full OAuth redirect flow. It is sent as a Bearer token like any other access token and is suited to scripts and a single owner's automation.
The Vimeo API is split into areas an agent can act on, like videos, the signed-in user's account, showcases, folders, channels, groups, comments, likes, and captions. Each area has its own methods, and a write needs the matching scope, so reading a video and deleting one are governed separately.
Methods for uploading, reading, editing, and deleting videos, plus their captions.
Methods for reading a user account, where /me stands in for the signed-in user.
Methods for creating, editing, and deleting showcases and adding videos to them.
Methods for organizing a user's own videos into folders, called projects in the API.
Methods for creating channels and adding videos to them, plus following channels.
Methods for reading groups, their members and videos, and joining or contributing to them.
Methods for reading and posting comments on a video.
Methods for liking and unliking videos on a member's behalf.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
VideosMethods for uploading, reading, editing, and deleting videos, plus their captions.7 | ||||||
| GET | /me/videos | Get all the videos a user has uploaded (page-paginated). | read | — | Current | |
No scope for public videos; the private scope is needed to include nonpublic videos. Acts onvideo Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /videos/{video_id} | Get a specific video and its metadata. | read | — | Current | |
No scope for a public video; the private scope is needed for a nonpublic one. Acts onvideo Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /me/videos | Begin a video upload, returning a tus link the file is then transferred to. | write | upload | Current | |
Needs the upload scope; the file itself is sent via the tus resumable protocol, not this endpoint. Acts onvideo Permission (capability) uploadVersionAvailable since the API’s base version Webhook event video.upload.completeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /videos/{video_id} | Edit a video's metadata, like its title, description, and privacy. | write | edit | Current | |
Needs the edit scope. Acts onvideo Permission (capability) editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /videos/{video_id} | Delete a video. | write | delete | Current | |
Needs the delete scope; the video is permanently removed. Acts onvideo Permission (capability) deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /videos/{video_id}/texttracks | Get all the text tracks (captions, subtitles, chapters) of a video. | read | — | Current | |
No scope for a public video's tracks. Acts ontext_track Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /videos/{video_id}/texttracks | Add a text track (caption or subtitle file) to a video. | write | upload | Current | |
Needs the upload scope; the caption file is then uploaded to the returned link. Acts ontext_track Permission (capability) uploadVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Me & UsersMethods for reading a user account, where /me stands in for the signed-in user.2 | ||||||
| GET | /me | Get the signed-in user's account, where /me stands in for /users/{user_id}. | read | — | Current | |
No scope is required for public fields; the private scope is needed to read nonpublic account data. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /users/{user_id} | Get a specific user by id. | read | — | Current | |
No scope is required for public profile fields. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Showcases (Albums)Methods for creating, editing, and deleting showcases and adding videos to them.5 | ||||||
| GET | /me/albums | Get all the showcases (albums) that belong to a user. | read | — | Current | |
No scope for public showcases; the private scope includes nonpublic ones. Acts onalbum Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /me/albums | Create a showcase (album). | write | create | Current | |
Needs the create scope. Acts onalbum Permission (capability) createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /me/albums/{album_id} | Edit a showcase's settings. | write | edit | Current | |
Needs the edit scope. Acts onalbum Permission (capability) editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /me/albums/{album_id} | Delete a showcase. | write | delete | Current | |
Needs the delete scope; removes the showcase but not its videos. Acts onalbum Permission (capability) deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /me/albums/{album_id}/videos/{video_id} | Add a specific video to a showcase. | write | edit | Current | |
Needs the edit scope. Acts onalbum Permission (capability) editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Folders (Projects)Methods for organizing a user's own videos into folders, called projects in the API.4 | ||||||
| GET | /me/projects | Get all the folders (projects) that belong to a user. | read | private | Current | |
Needs the private scope, since folders organize a user's own videos. Acts onproject Permission (capability) privateVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /me/projects | Create a folder (project). | write | create | Current | |
Needs the create scope. Acts onproject Permission (capability) createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /me/projects/{project_id}/videos/{video_id} | Add a specific video to a folder (project). | write | interact | Current | |
Needs the interact scope. Acts onproject Permission (capability) interactVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /me/projects/{project_id} | Delete a folder (project). | write | delete | Current | |
Needs the delete scope. Acts onproject Permission (capability) deleteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ChannelsMethods for creating channels and adding videos to them, plus following channels.4 | ||||||
| GET | /channels | Get all channels. | read | — | Current | |
No scope required. Acts onchannel Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /channels | Create a channel. | write | create | Current | |
Needs the create scope. Acts onchannel Permission (capability) createVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /channels/{channel_id}/videos/{video_id} | Add a specific video to a channel. | write | edit | Current | |
Needs the edit scope. Acts onchannel Permission (capability) editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /me/channels/{channel_id} | Subscribe the signed-in user to a channel (follow it). | write | interact | Current | |
Needs the interact scope. Acts onchannel Permission (capability) interactVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
GroupsMethods for reading groups, their members and videos, and joining or contributing to them.3 | ||||||
| GET | /groups | Get all groups. | read | — | Current | |
No scope required. Acts ongroup Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /groups/{group_id}/videos | Get all the videos in a group. | read | — | Current | |
No scope required. Acts ongroup Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /me/groups/{group_id} | Add the signed-in user to a group (join it). | write | interact | Current | |
Needs the interact scope. Acts ongroup Permission (capability) interactVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CommentsMethods for reading and posting comments on a video.2 | ||||||
| GET | /videos/{video_id}/comments | Get all the comments on a video. | read | — | Current | |
No scope for a public video's comments. Acts oncomment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /videos/{video_id}/comments | Add a comment to a video. | write | interact | Current | |
Needs the interact scope; the comment is visible to others. Acts oncomment Permission (capability) interactVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
LikesMethods for liking and unliking videos on a member's behalf.2 | ||||||
| PUT | /me/likes/{video_id} | Cause the signed-in user to like a video. | write | interact | Current | |
Needs the interact scope. Acts onlike Permission (capability) interactVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /me/likes | Get all the videos the signed-in user has liked. | read | — | Current | |
No scope for public likes; the private scope includes nonpublic ones. Acts onlike Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Vimeo can notify an app when something happens to a video, like an upload finishing or a play being recorded. Webhooks are registered against an API app, not against an arbitrary token, and a receiver verifies the vimeo-signature header to confirm the request came from Vimeo.
| Event | What it signals | Triggered by |
|---|---|---|
video.upload.complete | A video upload finished and the source file was received. This signals that the video exists, though transcoding may still be in progress, which is checked by polling the video's status. | /me/videos |
video.play | A play of a video was recorded. An app subscribes to this through an app webhook to learn about viewing activity without polling. | In-app only |
Vimeo limits how fast an app can call, counted per app across all of its users over a rolling window, with the remaining allowance returned on every response.
Vimeo meters requests per app across all of its users, not per individual end user, over a rolling window. Every response returns the current allowance in the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers, so an integration watches the remaining count and slows down before it runs out. Going over returns HTTP 429 with error code 9000, and the app stops being served for that user for the rest of the period. The newer AI endpoints are limited separately, to roughly 10 requests per minute per endpoint.
List endpoints are page-based: the page parameter selects the page and per_page sets its size, up to a maximum of 100 items. A paging object in the response carries next, previous, first, and last links so an integration can walk the full set without constructing URLs by hand. A total field gives the count of matching items.
A list page returns at most 100 items (the maximum value of per_page). Uploads have no fixed per-request size because tus transfers a file in resumable chunks, and the account's storage plan, not the API, sets the overall ceiling on how much video can be stored.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_request | The request was malformed: a required parameter is missing or a value is invalid. The developer_message names the specific problem. | Read error and developer_message, fix the parameters, and resend. The request is not retryable as-is. |
| 401 | 8003 | Authentication failed or no usable credentials were sent, for example a missing, expired, or malformed access token. | Send a valid Bearer access token, and re-run the OAuth flow if the token has expired or been revoked. |
| 403 | 3500 | Access is forbidden. The token lacks the scope the action needs, or the client has been banned for abuse. | Request a token carrying the required scope, like edit or delete, or contact Vimeo support if the client has been banned. |
| 404 | 5000 | The requested resource does not exist, or is not visible to this token, account, or privacy setting. | Verify the id and confirm the token's scopes and the resource's privacy allow it to be seen. |
| 429 | 9000 | The app exceeded its rate limit for this end user. The app is not served for that user for the rest of the current period. | Watch the X-RateLimit-Remaining header, stop calling when it nears zero, and resume after X-RateLimit-Reset. |
| 500 | server_error | An error on Vimeo's side, returned as 'Something strange occurred'. It is rare. | Retry with backoff, and contact Vimeo support if it persists. |
Vimeo pins the API version through the Accept header on each request, so a call can target an exact representation and a newer version never silently changes an existing one.
Version 3.4 is the current public default of the Vimeo API, targeted through the Accept header like application/vnd.vimeo.*+json;version=3.4. It introduced the open tus resumable protocol as the upload method, replacing the older resumable PUT 'streaming' upload. A request can pin different versions per resource type in a single Accept header.
Earlier 3.x versions of the API are still reachable by pinning them in the Accept header, so an integration can request, for example, an older user representation alongside a newer video representation. Vimeo keeps prior representations stable so a pinned integration is not broken by later changes.
Pin the version in the Accept header and move up deliberately.
Vimeo API changelog ↗Bollard AI sits between a team's AI agents and Vimeo. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.