For nearly six months now, our brand-new API has been sitting patiently in beta, waiting for the day it’d be released to the world. Today, we’re thrilled to metaphorically pick up those giant scissors and cut that red tape. Now, everyone has access to the newly designed developer site, and the extra-fresh Vimeo API.

What’s changed? In short: everything. We’ve improved every single aspect of our documentation to some degree. We cleaned up the spec, and have ensured that our endpoint documentation is absolutely accurate. You might also notice return of the API Playground you once knew and loved. We completely overhauled the playground to make it fit the new API, and we whole-heartedly encourage you to spend recess exploring all of our API’s new features.

The API has been updated to version 3.2, and is available immediately. To learn more about our version system, check out the docs. Thanks to our beta testers, we have cleaned up our response formats and have squashed many bugs. Keep an eye open for the new “connections” and “pictures” formats.

The beta hasn’t just been about polishing our existing features — there were some features we wanted to make available on day one. Our two most requested features have always been Vimeo On Demand and thumbnail uploads, both of which are now a part of the API. In the coming weeks, we will write more about these features, but for now, you can read up on things in our endpoint documentation

These aren’t the last of the new additions — we still have so much more to come. Keep an eye on our roadmap to learn about all the awesome new features we’re working on.

WARNING — None of the following will make any sense whatsoever unless you are aware that the open beta for for our new API has begun. Read all the details.

Some of our requests give you a TON of data. And while data is super fun, sometimes, you don’t need that much. We are working on a system that will allow you to limit the response fields we send, but what if you don’t need a response at all?

HTTP allows you make conditional GET requests. These requests let you tell our servers a little bit more about the request you want to make. Currently, we only support one conditional request: If-Modified-Since.

If-Modified-Since

Say you were building a tool to watch for new Staff Pick videos. Without the If-Modified-Since header, you would request all Staff Pick videos and loop through trying to find new videos.

curl -v -H "Authorization : bearer <ACCESS TOKEN>" https://api.vimeo.com/channels/staffpicks/videos

< HTTP/1.1 200 OK
< Date: Wed, 19 Mar 2014 19:31:53 GMT
* Server Apache is not blacklisted
< Server: Apache
< Cache-Control: no-cache, max-age=315360000
< Vary: Accept,Vimeo-Client-Id,Accept-Encoding
< Last-Modified: Wed, 19 Mar 2014 15:29:35 -0400
< Expires: Sat, 16 Mar 2024 19:31:53 GMT
< Content-Length: 5788
< Content-Type: application/vnd.vimeo.video+json
<
{
    total: 7670,
    page: 1,
    per_page: 25,
    paging:
    {
         next: '/channels/staffpicks/videos?page=2',
         previous: null,
         first: '/channels/staffpicks/videos?page=1',
         last: '/channels/staffpicks/videos?page=307'
    },
    data: [ … ] 
}

Notice the response headers. One of these headers is Last-Modified: Wed, 19 Mar 2014 15:29:35 -0400. This tells you the last time a video was added or removed from the Staff Picks Channel. Make a note of this date.

Next time you check for new videos, add the If-Modified-Since header with the current date.

curl -v -H "Authorization : bearer <ACCESS TOKEN>" -H “If-Modified-Since: <CURRENT-DATE>” https://api.vimeo.com/channels/staffpicks/videos

< HTTP/1.1 304 Not Modified
< Date: Wed, 19 Mar 2014 19:54:36 GMT
* Server Apache is not blacklisted
< Server: Apache
< Expires: Sat, 16 Mar 2024 19:54:36 GMT
< Cache-Control: no-cache, max-age=315360000
< Vary: Accept,Vimeo-Client-Id,Accept-Encoding

Notice there isn’t a response body at all, but there is a 304 status code. 304 Not Modified means that nothing has changed since the date you provided. If a video had been added since that date, you will see the full response body. Let’s make one more API request to see this in action. The following example checks for new additions since 1987, significantly predating Vimeo.

curl -v -H "Authorization : bearer <ACCESS TOKEN>" -H “If-Modified-Since: 04-27-1987” https://api.vimeo.com/videos/31436718

< HTTP/1.1 200 OK
< Date: Wed, 19 Mar 2014 19:31:53 GMT
* Server Apache is not blacklisted
< Server: Apache
< Cache-Control: no-cache, max-age=315360000
< Vary: Accept,Vimeo-Client-Id,Accept-Encoding
< Last-Modified: Wed, 19 Mar 2014 15:29:35 -0400
< Expires: Sat, 16 Mar 2024 19:31:53 GMT
< Content-Length: 5788
< Content-Type: application/vnd.vimeo.video+json
<
{
    total: 7670,
    page: 1,
    per_page: 25,
    paging:
    {
         next: '/channels/staffpicks/videos?page=2',
         previous: null,
         first: '/channels/staffpicks/videos?page=1',
         last: '/channels/staffpicks/videos?page=307'
    },
    data: [ … ] 
}

There have definitely been videos added since this date, so the response is identical to a request without the If-Modified-Since header.

If-Modified-Since lets you speed up your app significantly, so you should probably use it whenever you possibly can! Not all collections support these headers just yet, so look for the Last-Modified header. If you need this feature added anywhere, please do let us know.

Next up: Video credits

This feature requires a User Access Token.

Now that you can make authenticated requests, you can interact with a video.

We provide resource interactions that allow users to easily interact with Vimeo resources via the API. These interactions allow you to like a video, join a group, follow a channel, and more. Below, I’ll describe how to interact with a video (for one, never look it in the eye).

Interacting with a Video

First, make an authenticated request for a video. The response will contain the information you need.

curl -H "Authorization : bearer <ACCESS TOKEN>" https://api.vimeo.com/videos/31436718
...
"interactions": {
    "watchlater":{
        "added":false,
        "added_time":null,
        "uri":"\/users\/8607249\/watchlater\/31436718"
    },
    "like":{
        "added":true,
        "added_time":null,
         "uri":"\/users\/8607249\/likes\/31436718"
    }
}, 
….

Notice the field interactions. This describes some of the common actions a user might perform with this resource. The two we currently provide are “like” and “watchlater”. These two interactions behave identically, so let’s focus on “like”.

Within the like object, there will be three parameters: added, added_on, and uri.

• added - boolean - This field describes the current state of the interaction. “true” means you have already performed this interaction (e.g., you have liked this video) and “false” means the interaction has not yet happened.

• added_on - date - This field will be null if added is false, and a date if added is true. This field tells you at what date the interaction was performed (e.g., at what date you liked this video).

• uri - string - This field contains the API endpoint that allows you to perform the interaction. If added is false, you should make a PUT request to this URI to perform the interaction. If added is true, you should make a DELETE request to this uri to undo the interaction.

If you have not yet liked the Bug Report video, you can like it by making the following PUT request.

curl -H "Authorization : bearer <ACCESS TOKEN>" -XPUT https://api.vimeo.com/me/likes/31436718

If you have already liked the Bug Report video, you can unlike it by making the following DELETE request.

curl -H "Authorization : bearer <ACCESS TOKEN>" -XDELETE https://api.vimeo.com/me/likes/31436718

If you are not allowed to interact with this video, you will receive a 400 or 500-level status code. These errors are always accompanied by a description of the problem — if it’s not clear, check out our help section.

Developing with interactions

When developing your API integration, we recommend that you call the URL directly from the video response instead of trying to build it yourself. In the PHP library, this looks like the following example:

$video = $lib->request(‘/videos/31436718’);

if ($action === ‘unlike’) {
    $method = ‘DELETE’;
} else if ($action === ‘like’) {
    $method = ‘PUT’;
}

$like = $lib->request($video[‘interactions’][‘like’][‘uri’], $method);

NEXT TIME : Conditional HTTP Requests.

Get excited — the open beta for our new API has begun.

Ready to take it for a test drive? Let’s talk about your first API request.

Create your API app

Go to https://developer.vimeo.com/apps/new, fill out the necessary information and click “Create App”. You will be redirected to your app details page; click the “OAuth 2” tab to find the following authentication information:

• Client ID - A unique identifier for your application
• Client Secret - A secret identifier for your application, this should never be shared with anyone
• Client Access Token - A token that allows your app to make unauthenticated requests
• User Access Token - A token that allows you to make API requests authenticated as yourself (the app owner)

Make a request

Once you have your tokens, you are ready to make a request. We use OAuth 2.0 and bearer tokens to authenticate your requests. OAuth 2.0 requires you to pass tokens through the Authorization header.

Authorization : bearer <TOKEN>

Try this now by adding your User Access Token to the following example, and entering it into your terminal.

curl -H "Authorization : bearer <ACCESS TOKEN>" https://api.vimeo.com/me

The response will include all the information related to your user account. In this response, you can see your entire profile, including your current upload quota.

If you receive an error, you may have entered the wrong token. The Client Access Token won’t work for private data, so make sure any “https://api.vimeo.com/me” requests use a User Access Token.

But — you don’t have to use the tokens we provide you. In fact, the tokens we give you are limited, and cannot access the whole API. To learn more about authentication and generating access tokens, read our full Authentication Documentation.

Vimeo’s first API was launched on Mar 26, 2007. We’ve added tons of features since then, but have always been stuck with two APIs. The Simple API was super easy to use, but didn’t allow authentication. The Advanced API had tons of features, but was more difficult to implement. We always knew, deep down, we could build a better system. We dreamt of one API to rule them all — one API that a developer could get up and running in minutes, instead of days. After many months of research and development, we are proud to announce the start of the open beta for our brand new API.

This singular, unified API replaces both the Advanced and Simple APIs. Just like the Simple API, all features are accessible within an easy to understand URL structure. This URL structure follows many of REST’s best practices, and has been carefully considered in every step of development.

That shouldn’t actually matter, though, because we also provide this information to you as often as possible. We’ve created resources that provide URLs or URL templates to guide you through our data. Should you ever forget what features are available, start with “https://api.vimeo.com/me” and start following links. Watch out, though. It’s addictive.

Over the next couple of weeks, we’ll tell you more about some of the new features supported by the API. If you’d like to be notified when we post something new, join our Google group.

Questions? Bug reports or feature requests? Contact us through our Help Center.

And to see the new API in action, take a look at the Vimeo apps for iOS and Xbox, which already have it integrated (I mean, we said this was beta. Not alpha…).

• Documentation
• Google Group
• Help
  
  

Aaron Hedges heads up all things API at Vimeo. He’s worked tirelessly on the new API for the past year and has managed not to crack (yet).

We’ve been hard at work building a brand new version of the Vimeo API (dubbed API 3.0) and we’d like to invite you to join us at Vimeo HQ to try it out!

We’ll be here May 4th from 11am to 7pm to help you build apps on the new API. The best creations will be featured on our blog and dev site.

Some of the new features your app can take advantage of are:

• Register for push notifications
• Create albums and groups
• Simplified video upload
• Easy access to a large collection of Creative Commons videos

As well as all the features of the Advanced API, including:

• Access a user’s Feed and Watch Later queue
• Interact with the Vimeo community
• Interact with the video player via JavaScript

Come check it out!

When: May 4, 2013 from 11am to 7pm
Where: 555 W 18th St, New York, NY
RSVP: http://vimeo-hackday-1.eventbrite.com

Would you be totally flabbergasted if we told you that in addition to rebuilding Vimeo from the ground up, we’ve ALSO constructed a brand new site for developers who want to rock the Vimeo APIs? Well, start flabbering your gasts* — because it’s true.

We’re happy to announce our brand new developer site: http://developer.vimeo.com! Our API is all grown up and ready to move into its own 1 bed / 1.5 bath subdomain. Laundry is just around the corner.

Right now you’re probably staring incredulously at your screen while yelling, “Whoa!!! Tell me some of the amazing features of this new dev site so I can continue my quest to conquer all technology!!!” You got it. Check our techniques:

OAuth Tokens provided

We now generate an OAuth token for you when you create an app — this way you don’t have to set up a temporary page to authorize when you only want to interact with your account. Just copy and paste into your app. OAuth awesomeness!

Simplified documentation and navigation

Life is complicated enough, so we’ve tried to streamline our documentation wherever possible. Now, instead of having to look at multiple pages of docs, you’ll find what you need on one page, reducing the need to jump around. And just like your favorite library book about deep sea creatures that somehow survive in complete darkness, our documentation now has a table of contents. Just flip to the section you’re looking for!

Clearer upload requests

Upload requests now take the form of a more straightforward questionnaire. This enables us to get right down to bizness and reduce the back and forth involved in approving your app for uploading. Because time is money, people.

Integrated Playground

The Advanced API method list now has the playground baked right into it, so you can easily get involved in some hot call-and-response action.

A suave new look

Night time is the right time for accessing data via the API. Turn the lights down, pour yourself a beverage, and kick back with some stone cold support from us.

Enjoy the new site!

*We have no idea what this means, but it feels good to say it out loud.

To be consistent with how it is handled on-site, we will be requiring read permissions for vimeo.videos.getSubscriptions starting on April 2. You will need to pass a user token to the call or you’ll receive an error.

To accomodate improvements to our subscriptions system, we have a few changes coming to subscriptions methods in the Advanced API.

The first change is that we will be dropping support for the types parameter on vimeo.people.getSubscriptions. It will return all subscription types.

A new parameter is going to be introduced to vimeo.videos.getSubscriptions: offset. The value passed should be the subscription_id from the last video on the previous page (a new field added to the response). Although not required, passing the offset will ensure that there is no overlap or missing videos between pages. As part of these changes, we will also be removing the sort ability for vimeo.videos.getSubscriptions. Results will always be returned with the newest subscription video first.

These changes will take effect in one month, on January 16, 2012, but you should start passing offset as soon as possible.

If you have any questions about these changes, please let us know in the API Forum.

Effective today, the following Advanced API methods are deprecated:

• vimeo.groups.getFiles
• vimeo.groups.events.getMonth
• vimeo.groups.events.getPast
• vimeo.groups.events.getUpcoming

These methods will no longer work after February 29, 2012. We apologize for any inconvenience this may cause.