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

Versioning

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

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

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.

albumcategory
channelcomment
creditgroup
userportfolio
upload_ticketvideo

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

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 https://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

Batch requests

Some API endpoints are designed to support batch API requests. A batch API request affects many different resources. This request may add new resources, edit many resources or interact with many different resources in a single API call.

The parameters must be provided via the request body as a JSON array of objects. The following example demonstrates this by adding many categories to a video:

PUT https://api.vimeo.com/videos/{video_id}/categories
[{
    "category": "animation"
}, {
    "category": "talks"
}]

HTTP Method override

Some programming languages do not support the HTTP PATCH method. To work around this limitation you can use the HTTP POST method alongside the following header.

X-HTTP-Method-Override: PATCH

If-Modified-Since header

Some API endpoints support the If-Modified-Since header, which can speed up response times when a requested resource has not been recently updated. When the If-Modified-Since header and a date/time value are provided, the request becomes conditional; the API will only return information if the resource has been modified after the specified date/time.

To take advantage of this feature, add the header and a date/time value to the request header:

If-Modified-Since: Tue, 19 Jan 2016 06:01:00 GMT

If the resource has not been modified since the specified date/time, then the API will return an empty response body and HTTP Status 304 Not Modified.

Endpoints that support this feature will return a Last-Modified header and date/time value, so it's best practice to use that value for your next If-Modified-Since request to that resource.

The If-Modified-Since header is currently supported on the endpoints listed below. If there is an endpoint you would like to see support this header, let us know!

/channels/{channel_id}/videos
/groups/{group_id}/videos
/me/channels
/me/videos
/me/watchlater
/users/{user_id}/channels
/users/{user_id}/videos
/users/{user_id}/watchlater

Send Feedback