Developer / API / Endpoints

api.vimeo.com/videos

Videos

Add a comment to a video

POST https://api.vimeo.com/videos/{video_id}/comments Playground
This method requires a token with the "interact" scope.
Name Type Required Description
text string Yes

The comment's text
HTTP Status Code Explanation
201 Created

401 Unauthorized

If invalid user credentials were supplied.

Error Code: 8000
403 Forbidden

If the clip has comments disabled.

Error Code: 3413
403 Forbidden

If the authenticated user is unverified.

Error Code: 3411
403 Forbidden

If the authenticated user is not allowed to comment

Error Code: 3412
400 Bad Request

If no comment text was supplied.

Error Code: 2207
403 Forbidden

If the supplied comment was flagged as spam.

Error Code: 3301

Add a credit to a video

POST https://api.vimeo.com/videos/{video_id}/credits Playground
Name Type Required Description
email string Yes

The email address of the person being credited.
name string Yes

The name of the person being credited.
role string Yes

The role of the person being credited.
user_uri string Yes

The URI of the Vimeo user who should be given credit in this video.
HTTP Status Code Explanation
201 Created

400 Bad Request

If the credit already exists.
400 Bad Request

If one of the parameters is invalid.
400 Bad Request

If the authenticated user has not verified their email.
400 Bad Request

If there is a user block between the video owner and the credit user.
403 Forbidden

If the authenticated user does not own the video.

Add a reply to a comment on a video

POST https://api.vimeo.com/videos/{video_id}/comments/{comment_id}/replies Playground
This method requires a token with the "interact" scope.
Name Type Required Description
text string Yes

The comment's new text.
HTTP Status Code Explanation
201 Created

403 Forbidden

If the clip has comments disabled.

Error Code: 3413
403 Forbidden

If the authenticated user is unverified.

Error Code: 3411
403 Forbidden

If the authenticated user is not allowed to comment.

Error Code: 3412
400 Bad Request

If no comment text was supplied.

Error Code: 2207
403 Forbidden

If the supplied comment was flagged as spam.

Error Code: 3301

Add a text track to a video

POST https://api.vimeo.com/videos/{video_id}/texttracks Playground
This method requires a token with the "upload" scope.
Name Type Required Description
active boolean
  • false
  • true
 No

Text tracks marked active will be visible to other users, and will show up in the player. Only one text track per language can be active.
language string Yes

Text track language
name string Yes

Text track name
type string
  • captions
  • chapters
  • descriptions
  • metadata
  • subtitles
 Yes

Text track type
HTTP Status Code Explanation
201 Created

403 Forbidden

If the authenticated user does not have permission to edit the text track.
403 Forbidden

If there are errors in the request.

Error Code: 2204

Allow a list of users to view a private video

PUT https://api.vimeo.com/videos/{video_id}/privacy/users Playground
This method requires a token with the "edit" scope.
HTTP Status Code Explanation
200 OK

Allow a user to view a private video

PUT https://api.vimeo.com/videos/{video_id}/privacy/users/{user_id} Playground
This method requires a token with the "edit" scope.
HTTP Status Code Explanation
204 No Content

If the user and video are already linked.
204 No Content

403 Forbidden

If the video is not set to a user defined access list.

Allow embedding of a video on a domain

PUT https://api.vimeo.com/videos/{video_id}/privacy/domains/{domain} Playground
This method requires a token with the "edit" scope.
HTTP Status Code Explanation
204 No Content

403 Forbidden

If the video is not set to a user defined access list.

Assign an embed preset to a video

PUT https://api.vimeo.com/videos/{video_id}/presets/{preset_id} Playground
This method requires a token with the "edit" scope.
HTTP Status Code Explanation
204 No Content

Check if a user owns a video

GET https://api.vimeo.com/me/videos/{video_id} Playground
GET https://api.vimeo.com/users/{user_id}/videos/{video_id} Playground
HTTP Status Code Explanation
200 OK

404 Not Found

If the video is not owned by the authenticated user.

Create a new video thumbnail

POST https://api.vimeo.com/videos/{video_id}/pictures Playground
This method requires a token with the "upload" scope.
Name Type Required Description
active boolean No

Make this picture the default picture if you have created a picture response from video at given time offset.
time float No

If set will create a picture resource from video at given time offset.
HTTP Status Code Explanation
201 Created

Delete a comment from a video

DELETE https://api.vimeo.com/videos/{video_id}/comments/{comment_id} Playground
This method requires a token with the "delete" scope.
HTTP Status Code Explanation
204 No Content

404 Not Found

If the video cannot be found.
404 Not Found

If the comment cannot be found.
403 Forbidden

If the authenticated user is attempting to delete a comment they did not write.

Error Code: 3415
404 Not Found

If the deleted comment still exists.

Error Code: 5000

Delete a credit on a video

DELETE https://api.vimeo.com/videos/{video_id}/credits/{credit_id} Playground
This method requires a token with the "edit" scope.
HTTP Status Code Explanation
204 No Content

400 Bad Request

If the authenticated user is neither the creator of the credit or the credited user.

Delete a users' entire watch history

DELETE https://api.vimeo.com/me/watched/videos Playground
This method requires a token with the "delete" scope.
HTTP Status Code Explanation
204 No Content

Delete a video

DELETE https://api.vimeo.com/videos/{video_id} Playground
This method requires a token with the "delete" scope.
HTTP Status Code Explanation
204 No Content

403 Forbidden

If the authenticated user does not own the video.

Delete a video from your watch history

DELETE https://api.vimeo.com/me/watched/videos/{video_id} Playground
This method requires a token with the "delete" scope.
HTTP Status Code Explanation
204 No Content

Delete a video text track

DELETE https://api.vimeo.com/videos/{video_id}/texttracks/{texttrack_id} Playground
This method requires a token with the "delete" scope.
HTTP Status Code Explanation
200 OK

404 Not Found

If the text track cannot be found.
404 Not Found

If the video cannot be found.
404 Not Found

If the authenticated user does not have permission to edit the text track.

Delete a video thumbnail

DELETE https://api.vimeo.com/videos/{video_id}/pictures/{picture_id} Playground
This method requires a token with the "edit" scope.
HTTP Status Code Explanation
204 No Content

Disallow a user from viewing a private video

DELETE https://api.vimeo.com/videos/{video_id}/privacy/users/{user_id} Playground
This method requires a token with the "edit" scope.
HTTP Status Code Explanation
204 No Content

403 Forbidden

If the video is not set to a user defined access list.
404 Not Found

If the user cannot be found.

Disallow embedding of a video on a domain

DELETE https://api.vimeo.com/videos/{video_id}/privacy/domains/{domain} Playground
This method requires a token with the "edit" scope.
HTTP Status Code Explanation
204 No Content

403 Forbidden

If the video is not set to a user defined access list.
404 Not Found

If the domain cannot be found.

Edit a comment on a video

PATCH https://api.vimeo.com/videos/{video_id}/comments/{comment_id} Playground
This method requires a token with the "edit" scope.
Name Type Required Description
text string No

The comment's new text
HTTP Status Code Explanation
200 OK

403 Forbidden

If the authenticated user is unverified.

Error Code: 3411
403 Forbidden

If the authenticated user is not allowed to post comments

Error Code: 3412
403 Forbidden

If the authenticated user is attempting to edit a comment they did not write.

Error Code: 3414
400 Bad Request

If no comment text was supplied.

Error Code: 2207
403 Forbidden

If the supplied comment was flagged as spam.

Error Code: 3301

Edit a credit on a video

PATCH https://api.vimeo.com/videos/{video_id}/credits/{credit_id} Playground
This method requires a token with the "edit" scope.
Name Type Required Description
email string No

The email address of the person being credited.
name string No

The name of the person being credited.
role string No

The role of the person being credited.
HTTP Status Code Explanation
200 OK

403 Forbidden

If one of the parameters is invalid.
404 Not Found

If the credit cannot be found.

Edit a video

PATCH https://api.vimeo.com/videos/{video_id} Playground
This method requires a token with the "edit" scope.
Name Type Required Description
content_rating array No

A list of values describing the content in this video. You can find the full list in the /contentrating endpoint. You must provide a list representation appropriate for your request body (comma separated for querystring, or array for JSON).
description string No

The new description for the video
embed.buttons.embed boolean No

Show or hide the embed button.
embed.buttons.fullscreen boolean No

Show or hide the fullscreen button.
embed.buttons.hd boolean No

Show or hide the HD button.
embed.buttons.like boolean No

Show or hide the like button.
embed.buttons.scaling boolean No

Show or hide the scaling button (shown only in fullscreen mode).
embed.buttons.share boolean No

Show or hide the share button.
embed.buttons.watchlater boolean No

Show or hide the watch later button.
embed.color string No

A primary color used by the embed player.
embed.logos.custom.active boolean No

Show or hide your custom logo.
embed.logos.custom.link string No

A url that your user will navigate to if they click your custom logo.
embed.logos.custom.sticky boolean No

Always show the custom logo, or hide it after time with the rest of the UI.
embed.logos.vimeo boolean No

Show or hide the vimeo logo.
embed.playbar boolean No

Show or hide the playbar.
embed.title.name string
  • hide
  • show
  • user
 No

Show, hide, or let the user decide if the video title shows on the video.
embed.title.owner string
  • hide
  • show
  • user
 No

Show, hide, or let the user decide if the owners information shows on the video.
embed.title.portrait string
  • hide
  • show
  • user
 No

Show, hide, or let the user decide if the owners portrait shows on the video.
embed.volume boolean No

Show or hide the volume selector.
external_links.imdb string No

External data from imdb
external_links.rotten_tomatoes string No

External data from rotten_tomatoes
license string
  • by
  • by-nc
  • by-nc-nd
  • by-nc-sa
  • by-nd
  • by-sa
  • cc0
 No

Set the Creative Commons license
locale string No

Set the default language for this video. For a full list of valid languages use the "/languages?filter=texttracks" endpoint.
name string No

The new title for the video
password string No

When you set privacy.view to password, you must provide the password as an additional parameter.
privacy.add boolean No

Enable or disable the ability for anyone to add the video to an album, channel, or group.
privacy.comments string
  • anybody
  • contacts
  • nobody
 No

The privacy for who can comment on the video.
privacy.download boolean No

Enable or disable the ability for anyone to download video.
privacy.embed string
  • private
  • public
  • whitelist
 No

The videos new embed settings. Whitelist allows you to define all valid embed domains. Check out our docs for adding and removing domains.
privacy.view string
  • anybody
  • contacts
  • disable
  • nobody
  • password
  • unlisted
  • users
 No

The new privacy setting for the video. Content-type application/json is the only valid type for type "users", basic users can not set privacy to unlisted.
ratings.mpaa.rating string
  • g
  • nc17
  • pg
  • pg13
  • r
  • x
 No

Set MPAA rating for a video.
ratings.mpaa.reason string
  • at
  • bn
  • n
  • sl
  • ss
  • v
 No

Set MPAA rating reason for a video.
ratings.tv.rating string
  • tv-14
  • tv-g
  • tv-ma
  • tv-pg
  • tv-y
  • tv-y7
  • tv-y7-fv
 No

Set TV rating for a video.
ratings.tv.reason string
  • d
  • fv
  • l
  • ss
  • v
 No

Set TV rating reason for a video.
review_link boolean No

Enable or disable the review page.
spatial.director_timeline array No

360 director timeline. The arrays in this should include a "time_code", "pitch", "yaw", and optionally "roll". For pitch, the minimum allowed is -90, and the max of 90. For yaw, the minimum is 0, and a maximum of 360.
spatial.field_of_view integer No

360 field of view. Default 50, min 30, max 90.
spatial.projection string
  • cubical
  • cylindrical
  • dome
  • equirectangular
  • pyramid
 No

360 spatial projection.
spatial.stereo_format string
  • left-right
  • mono
  • top-bottom
 No

360 spatial stereo format.
HTTP Status Code Explanation
200 OK

403 Forbidden

If the authenticated user does not own the video.
403 Forbidden

If `privacy` is `disable` and the authenticated user is not allowed to set extra embed options.
403 Forbidden

If `privacy` is `contacts` and the authenticated user is not allowed to follow users.
403 Forbidden

If the authenticated user has an opted-out PRO account and `privacy` is `users`, `password`, `nobody` or `public`.
400 Bad Request

If one of the parameters is invalid.

Edit a video text track

PATCH https://api.vimeo.com/videos/{video_id}/texttracks/{texttrack_id} Playground
This method requires a token with the "edit" scope.
Name Type Required Description
active boolean No

Text tracks marked active will be visible to other users, and will show up in the player. Only one text track per language can be active.
language string No

Text track language
name string No

Text track name
type string
  • captions
  • chapters
  • descriptions
  • metadata
  • subtitles
 No

Text track type
HTTP Status Code Explanation
200 OK

404 Not Found

If the text track cannot be found.
404 Not Found

If the video cannot be found.
403 Forbidden

If the authenticated user does not have permission to edit the text track.
403 Forbidden

If there are errors in the request.

Error Code: 2204

Edit a video thumbnail

PATCH https://api.vimeo.com/videos/{video_id}/pictures/{picture_id} Playground
This method requires a token with the "edit" scope.
Name Type Required Description
active boolean No

Make this picture the default picture.
HTTP Status Code Explanation
200 OK

Get a comment on a video

GET https://api.vimeo.com/videos/{video_id}/comments/{comment_id} Playground
HTTP Status Code Explanation
200 OK

404 Not Found

If the comment cannot be found.
404 Not Found

If the video cannot be found.

Get a credit on a video

GET https://api.vimeo.com/videos/{video_id}/credits/{credit_id} Playground
HTTP Status Code Explanation
200 OK

404 Not Found

If the credit cannot be found.
404 Not Found

If the video cannot be found.

Get a video

GET https://api.vimeo.com/videos/{video_id} Playground
HTTP Status Code Explanation
200 OK

404 Not Found

If the video cannot be found.

Get a video text track

GET https://api.vimeo.com/videos/{video_id}/texttracks/{texttrack_id} Playground
HTTP Status Code Explanation
200 OK

404 Not Found

If the text track cannot be found.
404 Not Found

If the video cannot be found.

Get a video thumbnail

GET https://api.vimeo.com/videos/{video_id}/pictures/{picture_id} Playground
HTTP Status Code Explanation
200 OK

Get all comments on a video

GET https://api.vimeo.com/videos/{video_id}/comments Playground
Name Type Required Description
direction string
  • asc
  • desc
 No

The direction that the results are sorted.
page integer No

The page number to show.
per_page integer No

Number of items to show on each page. Max 100.
query string No

Search query.
HTTP Status Code Explanation
200 OK

Get all domains a video can be embedded on

GET https://api.vimeo.com/videos/{video_id}/privacy/domains Playground
HTTP Status Code Explanation
200 OK

403 Forbidden

If you are asking for a list where none applies.

Get all embed presets for a video

GET https://api.vimeo.com/videos/{video_id}/presets/{preset_id} Playground
HTTP Status Code Explanation
204 No Content

404 Not Found

If the preset cannot be found.
404 Not Found

If the video cannot be found.

Get all replies to a comment on a video

GET https://api.vimeo.com/videos/{video_id}/comments/{comment_id}/replies Playground
Name Type Required Description
page integer No

The page number to show.
per_page integer No

Number of items to show on each page. Max 100.
HTTP Status Code Explanation
200 OK

404 Not Found

If the video cannot be found.
404 Not Found

If the comment cannot be found.

Get all the text tracks for a video

GET https://api.vimeo.com/videos/{video_id}/texttracks Playground
HTTP Status Code Explanation
200 OK

404 Not Found

If the video cannot be found.

Get all thumbnails on a video

GET https://api.vimeo.com/videos/{video_id}/pictures Playground
HTTP Status Code Explanation
200 OK

Get all users credited in a video

GET https://api.vimeo.com/videos/{video_id}/credits Playground
Name Type Required Description
direction string
  • asc
  • desc
 No

The direction that the results are sorted.
page integer No

The page number to show.
per_page integer No

Number of items to show on each page. Max 100.
query string No

Search query.
sort string
  • alphabetical
  • date
 No

Technique used to sort the results.
HTTP Status Code Explanation
200 OK

Get all users that can view a private video

GET https://api.vimeo.com/videos/{video_id}/privacy/users Playground
HTTP Status Code Explanation
200 OK

400 Bad Request

If you are asking for a list where none applies.

Get all videos a user has watched

GET https://api.vimeo.com/me/watched/videos Playground
This method requires a token with the "private" scope.
HTTP Status Code Explanation
200 OK

Get all videos uploaded by a user

GET https://api.vimeo.com/me/videos Playground
GET https://api.vimeo.com/users/{user_id}/videos Playground
Name Type Required Description
direction string
  • asc
  • desc
 No

The direction that the results are sorted.
filter string
  • app_only
  • embeddable
  • playable
 No

Filter to apply to the results.
filter_embeddable string
  • false
  • true
 No

Required if filter=embeddable. Choose between only videos that are embeddable, and only videos that are not embeddable.
filter_playable string
  • false
  • true
 No

Default true. Choose between only videos that are playable, and only videos that are not playable.
page integer No

The page number to show.
per_page integer No

Number of items to show on each page. Max 100.
query string No

Search query.
sort string
  • alphabetical
  • comments
  • date
  • default
  • duration
  • likes
  • modified_time
  • plays
 No

Technique used to sort the results.
weak_search boolean No

This forces the query parameter to use a separate search service that includes private videos. It will only perform a partial text search on the video's name. In the future the standard search will include private videos, and this parameter won't be necessary.
HTTP Status Code Explanation
304 Not Modified

If no videos were created by this user since the provided If-Modified-Since header.
200 OK

Replace a video source file

PUT https://api.vimeo.com/videos/{video_id}/files Playground
This method requires a token with the "upload,"edit" scope.
Name Type Required Description
link string No

If your upload type is pull, Vimeo will download the video hosted at this public URL. This URL must be valid for at least 24 hours.
redirect_url string No

The app redirect URL. Required for POST upload types.
type string
  • POST
  • pull
  • streaming
 Yes

Upload type
HTTP Status Code Explanation
201 Created

403 Forbidden

If the upload quota is exceeded.

Search for videos

GET https://api.vimeo.com/videos Playground
Name Type Required Description
direction string
  • asc
  • desc
 No

The direction that the results are sorted.
filter string
  • CC
  • CC-BY
  • CC-BY-NC
  • CC-BY-NC-ND
  • CC-BY-NC-SA
  • CC-BY-ND
  • CC-BY-SA
  • CC0
  • categories
  • duration
  • in-progress
  • minimum_likes
  • trending
  • upload_date
 No

Filter to apply to the results. The CC filters will show only those videos with the applicable Creative Commons licenses. See our Creative Commons page for more.
page integer No

The page number to show.
per_page integer No

Number of items to show on each page. Max 100.
query string Yes

Search query.
sort string
  • alphabetical
  • comments
  • date
  • duration
  • likes
  • plays
  • relevant
 No

Technique used to sort the results.
HTTP Status Code Explanation
200 OK

400 Bad Request

If the `uris` batch parameter is supplied with filtering or sorting arguments.

Error Code: 2101
400 Bad Request

If there is a problem with the batch request.

Error Code: 2204
503 Service Unavailable

If search is disabled.
503 Service Unavailable

If there was an internal error with our search infrastructure.

Error Code: 7300

Unassign an embed preset from a video

DELETE https://api.vimeo.com/videos/{video_id}/presets/{preset_id} Playground
This method requires a token with the "edit" scope.
HTTP Status Code Explanation
204 No Content

404 Not Found

If the preset cannot be found.
404 Not Found

If the video cannot be found.

Upload a video

POST https://api.vimeo.com/me/videos Playground
POST https://api.vimeo.com/users/{user_id}/videos Playground
This method requires a token with the "upload" scope.
Name Type Required Description
link string Yes

If your upload type is pull, Vimeo will download the video hosted at this public URL. This URL must be valid for at least 24 hours.
redirect_url string No

The app redirect URL. Required for POST upload types.
type string
  • POST
  • pull
  • streaming
 Yes

Upload type
HTTP Status Code Explanation
201 Created

403 Forbidden

If the upload quota is exceeded.

View related videos to a video

GET https://api.vimeo.com/videos/{video_id}/videos Playground
Name Type Required Description
filter string
  • related
 No

Filter to apply to the results.
page integer No

The page number to show.
per_page integer No

Number of items to show on each page. Max 100.
HTTP Status Code Explanation
200 OK

400 Bad Request

If the filter is supplied but is not `related`.
Send Feedback