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.

    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

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
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}
[{
 "category": "animation"
}, {
 "category": "talks"
}]
Send Feedback