Developer / API

Getting Started

  1. Get your API key

    You’ll need a Client ID and Client Secret for each application you create. To create a key, you’ll need to supply us with some basic information about your application. Don’t worry if you’re not sure about all of the information, you can always edit it later.

    Register a new application

    We also recommend you use one of our official API libraries

  2. Get an access token

    To make API requests you will need an Access token. If you want to make requests on behalf of a user, that token must be authenticated.

    Vimeo uses the OAuth 2 specification. You must send your user to a Vimeo URL, where they will be given the choice to accept or deny access. If they accept, they will be redirected to your app where you must exchange a code for your access token.

    See the authentication documentation

  3. Make API calls to Vimeo

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

  4. Upload a video

    Vimeo provides two different upload workflows. All applications must be approved for upload access before they can upload.

    Upload Documentation

  5. Stay up to date

    See our changelog to keep up-to-date with changes in the API.

Send Feedback