api.vimeo.com/videos

Videos

View one 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

Edit one 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.

Delete one 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.

Search

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.

500 Internal Server Error

If there was an internal error with our search infrastructure.

Categories

View a video's categories

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

404 Not Found

If the video cannot be found

Categorize a video

PUT https://api.vimeo.com/videos/{video_id}/categories Playground
This method requires a token with the "edit" scope.
HTTP Status Code Explanation
201 Created

404 Not Found

If the Clip cannot be found

404 Not Found

If the Category cannot be found

403 Forbidden

If you are attempting to modify an clip you do not own.

Comments

View one comment

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

Edit one comment

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

Delete one comment

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

View all comments

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

Add one comment

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

Replies

View all replies

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

Add one reply

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

Credits

View one credit

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

Edit credit

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

Delete credit

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.

View credits

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

Add credit

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.

Replace Source file

Replace 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.

Likes

View users who liked this video

GET https://api.vimeo.com/videos/{video_id}/likes 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

Pictures

View one thumbnail

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

Edit one 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

Delete one 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

View all thumbnails

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

Create a 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

Presets

View embed preset for 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

Assign embed preset

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

Unassign embed preset

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

Embed Domains

Allow embedding 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.

409 Conflict

If you attempt to add an existing domain to the list.

Disallow embedding 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

View all allowed domains

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.

Users

Allow user to view this 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.

Disallow user from viewing this 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

View all allowed users

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.

Allow users to view this 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

Tags

Check a video tag

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

400 Bad Request

If one of the parameters is invalid.

400 Bad Request

If the tag is invalid.

404 Not Found

If the tag cannot be found in the video

Assign a tag

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

400 Bad Request

If the tag is invalid.

400 Bad Request

If an unsupported parameter is supplied.

403 Forbidden

If the number of tags on the video would exceed 20.

Remove a tag

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

400 Bad Request

If one of the parameters is invalid.

400 Bad Request

If the tag is invalid.

List a video's tags

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

Assign many tags

PUT https://api.vimeo.com/videos/{video_id}/tags Playground
This method requires a token with the "edit" scope.
Name Type Required Description
tag string Yes

The name of the tag to apply. See our documentation for batch requests for more information.

HTTP Status Code Explanation
201 Created

400 Bad Request

If the request body is not supplied.

400 Bad Request

If one of the parameters is invalid.

400 Bad Request

If the request body is not a JSON encoded list of tags.

403 Forbidden

If the authenticated user is not allowed to add tags to a video.

403 Forbidden

If the number of tags would exceed 20.

Text Tracks

View one 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 texttrack cannot be found

404 Not Found

If the video cannot be found

Edit one 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 Yes

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 Yes

Text track type

HTTP Status Code Explanation
200 OK

404 Not Found

If the texttrack 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

Delete one 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 texttrack 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.

View all text tracks

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

Add text track

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 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
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

Related Videos

View related videos

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

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