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