API Specification

Construct Your Request

Each HTTP request consists of an HTTP Method, an endpoint and a list of parameters. Throughout the documentation, these requests are formatted like the following example.

{METHOD} https://api.vimeo.com{endpoint}

This method requires a token with the "{scope_name}" scope.

Field	Required	Description
{field1}	Yes	Description of field1
{field2}	No	Description of field2

1. Method

   Most of Vimeo's API endpoints support multiple actions. Each action is defined by it's HTTP method. These methods generally follow the guidelines below.

   METHOD	Description	Example
   GET	Retrieve the JSON representation of a resource	GET /me returns the authenticated user's information
   POST	Add new resources to a collection. This method generally requires additional parameters	POST /me/albums has the authenticated user creates a new album
   PUT	Replace a resource or connect two resources together	PUT /me/likes/[video_id] adds a "like" to [video_id] on behalf of the authenticated user
   PATCH	Modify a resource. The body will contain the new resource representation.	PATCH /videos/[video_id] allows you to change fields of the video [video_id]
   DELETE	Delete an existing resource, or disconnect two resources	DELETE /videos/[video_id] deletes the video [video_id]

2. Endpoint

   An API endpoint is a path that uniquely identifies a Vimeo resource. To make an HTTP request to an endpoint, append this path to the end of https://api.vimeo.com. The response from an endpoint will be JSON, and contain one or more resources.

   
   

3. Parameters

   Most API Endpoints support additional request parameters. These parameters depend on your HTTP method and your API endpoint.

   GET

   All GET requests must append the parameters to the endpoint as is true for any standard query component.

   
   

   METHOD endpoint?field1=hello&field2=goodbye

   
   

   POST, PUT, DELETE, PATCH

   All other requests must provide the parameters through the body. By default we assume you are sending the value as application/x-www-form-urlencoded.

   
   

   METHOD endpoint
   Content-Type: application/x-www-form-urlencoded
   
   field1=hello&field2=goodbye

   
   

   We also accept JSON if you provide a Content-Type header of application/json.

   METHOD endpoint
   Content-Type: application/json
   
   { "field1": "hello", "field2": "goodbye" }

   
   

   Urlencoded nested parameters are represented in the documentation with dot notation.

   METHOD endpoint
   Content-Type: application/x-www-form-urlencoded
   
   privacy.view=anybody

   
   

   When using JSON, these fields must be nested JSON objects.

   METHOD endpoint
   Content-Type: application/json
   
   { "privacy": { "view" : "anybody" } }

   
   

4. Set your API version

   Vimeo's API provides versioning so that we can continue to improve the API over time without breaking existing users' apps. As long as you are explicitly providing a version number with every API request, we will do our best to ensure no changes impact your integrations.

   You indicate the version in the API through the Accept header. If you don't care about the details, just provide the following header and skip to the next step.

   Accept: application/vnd.vimeo.*+json;version=3.2

   
   

   If you do care about the details, keep reading.

   Many additional features are supported with this accept header, but let's pull it apart first.

   application/vnd.vimeo.*+json;version=3.2

   
   

   The first section of the accept header defines the content type you expect. The prefix is always application/vnd.vimeo. and the suffix can be * as a wildcard, or any of the following resources.

   album	category
   channel	comment
   credit	group
   user	portfolio
   upload_ticket	video

   If you explicitly request a resource that an endpoint does not return, you will receive an error. Unless you know exactly what you are doing, you should use the example above

   The second section of the accept header defines the response format. Currently only JSON is supported, but if you have need for other resources let us know

   The third section of the accept header defines the API version you expect to use. As the API grows, changes will not impact older versions of the API.

   As an added bonus, we experimentally support the q parameter as defined in the Accept header spec. By combining q and version you can request different versions of different resources with the same accept header.

   The following example will return videos at version 3, and users at version 2

   application/vnd.vimeo.user+json;version=2.0,application/vnd.vimeo.*+json;version=3.0

   
   

Authentication

All requests require some form of authentication. Authentication is handled through OAuth 2.0, using either client access tokens or user access tokens.

Learn more about authentication

Collection Representation

If your API request returns more than one resource, the Vimeo API wraps them in the collection representation. This JSON wrapper includes additional useful information, such as pagination, counts and more

Field	Type	Description
data	array	An array of resource representations. This is the primary content of the collection.
total	number	The total amount of resources for this endpoint, summed across all pages.
page	number	The current page of resources.
per_page	number	The amount of resources to include in each page of data.
pagination	object	An object detailing how to request additional pages in this collection. See our pagination docs for additional information.

Pagination

Sometimes your collection might be very large. Returning thousands of resources in a single API request can become prohibitively slow, so we split the response into multiple requests. Each request returns a single page of information, and you can increase the amount of items per page with the per_page parameter (max 100).

To request pages beyond the first, we highly recommend you use the built in pagination URI's. These are included in every collection response, and tell you the exact API call to make to receive the next, previous, first and last pages

...
 "paging": {
 "next": "/users/101193/videos?page=2&per_page=10",
 "previous": null,
 "first": "/users/101193/videos?page=1&per_page=10",
 "last": "/users/101193/videos?page=3&per_page=10"
 }
 ...
 

Common Headers and Parameters

JSON Filter

Our JSON responses can be very large. With a simple parameter you can reduce the size of the responses, and dramatically increase the performance of your API requests. This feature is surprisingly powerful for how simple it is. Simply provide a comma separated whitelist of fields, and all unwanted information will be stripped away.

GET https://api.vimeo.com/me?fields=uri,name

{
 "uri" : "/users/dashron",
 "name" : "Aaron"
 }

Need to see nested fields? Separate each tier with a period!

GET https://api.vimeo.com/me?fields=metadata.connections

{
 "metadata" : {
 "connections" : {
 "activities":{
 "uri":"/users/8607249/activities",
 "options":["GET"]
 }
 }
 }
 }

What if your information is in an array? Those work seamlessly.

GET https://api.vimeo.com/me?fields=websites.names

{
 "websites": [{
 "name":"facebook"
 },{
 "name":"twitter"
 },{
 "name":"homepage"
 }]
 }

We have some awesome optimizations around the fields filter. If you don't want a field, we won't build it. So you should see significantly faster requests if you leave out pictures, users and other related information.

Sorting

Some resources are sortable. We specify valid sorts in the endpoint documentation. All sortable resources accept the direction parameter which must be either asc or desc. The default sort direction is desc.

For example, to list a user's uploaded videos with the oldest first:

GET https://api.vimeo.com/users/brad/videos?sort=date&direction=asc

Resource filter

Some collections support reducing a result set into subsets of that data. We specify valid filters in the endpoint documentation. All filterable resources accept the filter parameter, and some resources accept additional related filter parameters.

The following example will only show featured channels

curl http://api.vimeo.com/channels?filter=featured

Content rating

Content filter is a specific type of resource filter, available on all video resources. Any videos that do not match one of the provided ratings will be excluded from the list of videos.

You enable content rating with the parameter filter=content_rating. Specific ratings are then provided through the parameter filter_content_rating=[list,of,filters]

Valid ratings include :

language

drugs

violence

nudity

safe

unrated

For example, you will find safe and unrated Staff Pick videos at

GET https://api.vimeo.com/channels/staffpicks/videos?filter=content_rating&filter_content_rating=safe,unrated

[{
 "category": "animation"
}, {
 "category": "talks"
}]