Vimeo Advanced API DocumentationLast Updated: Nov 26, 2008 02:15 pm
Comments/questions? Email ted (at vimeo dot com)

Test Methods

vimeo.test.login

Is the user logged in?

Authentication

Authentication is required with 'read' permission.

Returns

<user id="151542">
   <username>ted</username>
</user>

Error Codes

vimeo.test.echo

This will just repeat back any parameters that you send.

Authentication

Authentication is not required.

Returns

<foo>bar</foo>
<some_string>Hi-Ya!</some_strong>

vimeo.test.null

This is just a simple null/ping test...

Authentication

Authentication is required with 'read' permission.

Returns

This method returns an empty success response.
<rsp stat="ok"></rsp>

Authentication

vimeo.auth.getToken

Authentication

Authentication is not required.

Parameters

Returns

<auth>
   <token>12354</token>
   <perms>write</perms>
   <user id="151542" username="ted" fullname="Ted!" />
</auth>

Error Codes

vimeo.auth.getFrob

This is generally used by desktop applications. If the user
doesn't already have a token, you'll need to get the frob,
send it to us at /services/auth. Then, after the user, clicks continue on
your app, you call vimeo.auth.getToken($frob) and we give you the actual
token.

Authentication

Authentication is not required.

Returns

<frob>12354</frob>

vimeo.auth.checkToken

Checks the validity of the token. Returns the user associated with it.
Returns the same as vimeo.auth.getToken

Authentication

Authentication is not required.

Parameters

Returns

<auth>
   <token>12354</token>
   <perms>write</perms>
   <user id="151542" username="ted" fullname="Ted!" />
</auth>

Error Codes

Lists of videos

vimeo.videos.getList

This gets a list of videos for the specified user.

This is the functionality of "My Videos" or "Ted's Videos."

At the moment, this is the same list as vimeo.videos.getAppearsInList. If you need uploaded or appears in, those are available too.

Authentication

Authentication is not required.

Parameters

Returns

The default response is this:
<videos page="1" perpage="25" on_this_page="2">
	<video id="173727" owner="151542" title="At the beach" privacy="users" is_hd="0" />
	<video id="173726" owner="151542" title="The Kids" privacy="contacts" is_hd="0" />
</videos>
If you pass fullResponse=1 as a parameter, the video object is identical to the vimeo.videos.getInfo call.

vimeo.videos.getUploadedList

This gets a list of videos uploaded by the specified user.

If the calling user is logged in, this will return information that calling user has access to (including private videos). If the calling user is not authenticated, this will only return public information, or a permission denied error if none is available.

Authentication

Authentication is not required.

Parameters

Returns

The default response is this:
<videos page="1" perpage="25" on_this_page="2">
	<video id="173727" owner="151542" title="At the beach" privacy="users" is_hd="0" />
	<video id="173726" owner="151542" title="The Kids" privacy="contacts" is_hd="0" />
</videos>
If you pass fullResponse=1 as a parameter, the video object is identical to the vimeo.videos.getInfo call.

vimeo.videos.getAppearsInList

This gets a list of videos that the specified user appears in.

If the calling user is logged in, this will return information that calling user has access to (including private videos). If the calling user is not authenticated, this will only return public information, or a permission denied error if none is available.

Authentication

Authentication is not required.

Parameters

Returns

The default response is this:
<videos page="1" perpage="25" on_this_page="2">
	<video id="173727" owner="151542" title="At the beach" privacy="users" is_hd="0" />
	<video id="173726" owner="151542" title="The Kids" privacy="contacts" is_hd="0" />
</videos>
If you pass fullResponse=1 as a parameter, the video object is identical to the vimeo.videos.getInfo call.

vimeo.videos.getSubscriptionsList

This gets a list of subscribed videos for a particular user.

If the calling user is logged in, this will return information that calling user has access to (including private videos). If the calling user is not authenticated, this will only return public information, or a permission denied error if none is available.

Authentication

Authentication is not required.

Parameters

Returns

The default response is this:
<videos page="1" perpage="25" on_this_page="2">
	<video id="173727" owner="151542" title="At the beach" privacy="users" is_hd="0" />
	<video id="173726" owner="151542" title="The Kids" privacy="contacts" is_hd="0" />
</videos>
If you pass fullResponse=1 as a parameter, the video object is identical to the vimeo.videos.getInfo call.

vimeo.videos.getListByTag

This gets a list of videos by tag

If you specify a user_id, we'll only get video uploaded by that user
with the specified tag.

If the calling user is logged in, this will return information that calling user has access to (including private videos). If the calling user is not authenticated, this will only return public information, or a permission denied error if none is available.

Authentication

Authentication is not required.

Parameters

Returns

The default response is this:
<videos page="1" perpage="25" on_this_page="2">
	<video id="173727" owner="151542" title="At the beach" privacy="users" is_hd="0" />
	<video id="173726" owner="151542" title="The Kids" privacy="contacts" is_hd="0" />
</videos>
If you pass fullResponse=1 as a parameter, the video object is identical to the vimeo.videos.getInfo call.

vimeo.videos.getLikeList

Get a list of videos that the specified user likes.

If the calling user is logged in, this will return information that calling user has access to (including private videos). If the calling user is not authenticated, this will only return public information, or a permission denied error if none is available.

Authentication

Authentication is not required.

Parameters

Returns

The default response is this:
<videos page="1" perpage="25" on_this_page="2">
	<video id="173727" owner="151542" title="At the beach" privacy="users" is_hd="0" />
	<video id="173726" owner="151542" title="The Kids" privacy="contacts" is_hd="0" />
</videos>
If you pass fullResponse=1 as a parameter, the video object is identical to the vimeo.videos.getInfo call.

vimeo.videos.getContactsList

Get a list of videos made by the contacts of a specific user.

If the calling user is logged in, this will return information that calling user has access to (including private videos). If the calling user is not authenticated, this will only return public information, or a permission denied error if none is available.

Authentication

Authentication is not required.

Parameters

Returns

The default response is this:
<videos page="1" perpage="25" on_this_page="2">
	<video id="173727" owner="151542" title="At the beach" privacy="users" is_hd="0" />
	<video id="173726" owner="151542" title="The Kids" privacy="contacts" is_hd="0" />
</videos>
If you pass fullResponse=1 as a parameter, the video object is identical to the vimeo.videos.getInfo call.

vimeo.videos.getContactsLikeList

Get a list of videos that the specified users contacts like.

If the calling user is logged in, this will return information that calling user has access to (including private videos). If the calling user is not authenticated, this will only return public information, or a permission denied error if none is available.

Authentication

Authentication is not required.

Parameters

Returns

The default response is this:
<videos page="1" perpage="25" on_this_page="2">
	<video id="173727" owner="151542" title="At the beach" privacy="users" is_hd="0" />
	<video id="173726" owner="151542" title="The Kids" privacy="contacts" is_hd="0" />
</videos>
If you pass fullResponse=1 as a parameter, the video object is identical to the vimeo.videos.getInfo call.

vimeo.videos.search

Search videos!

If the calling user is logged in, this will return information that calling user has access to (including private videos). If the calling user is not authenticated, this will only return public information, or a permission denied error if none is available.

Authentication

Authentication is not required.

Parameters

Returns

The default response is this:
<videos page="1" perpage="25" on_this_page="2">
	<video id="173727" owner="151542" title="At the beach" privacy="users" is_hd="0" />
	<video id="173726" owner="151542" title="The Kids" privacy="contacts" is_hd="0" />
</videos>
If you pass fullResponse=1 as a parameter, the video object is identical to the vimeo.videos.getInfo call.

Error Codes

Dealing with specific videos

vimeo.videos.getInfo

Get all kinds of information about a photo.

If the calling user is logged in, this will return information that calling user has access to (including private videos). If the calling user is not authenticated, this will only return public information, or a permission denied error if none is available.

Authentication

Authentication is not required.

Parameters

Returns

<video id="17" privacy="anybody" is_uploading="0" is_transcoding="0" is_favorite="1" is_hd="0">
    <title>Cocoon</title>
    <caption>Performance art in college!</caption>
    <upload_date>2005-02-17 11:32:04</upload_date>
    <number_of_likes>12</number_of_likes>
    <number_of_plays>4626</number_of_plays>
    <number_of_comments>15</number_of_comments>
    <width>320</width>
    <height>240</height>
    <duration>60</duration>
    <owner nsid="102" id="102" username="zach" fullname="Zach Klein" />
    <tags>
        <tag id="133" author="102" raw="cocoon">cocoon</tag>
        <tag id="99876" author="102" raw="Wake Forest University">Wake Forest University</tag>
        <tag id="99877" author="102" raw="Performance Art">Performance Art</tag>
        <tag id="99878" author="102" raw="art">art</tag>
    </tags>
    <urls>
        <url type="videopage">http://vimeo.com/17/l:app-4</url>
    </urls>
    <thumbnails>
        <thumbnail width="96" height="54">http://...jpg</thumbnail>
        <thumbnail width="160" height="120">http://...jpg</thumbnail>
        <thumbnail width="460" height="259">http://...jpg</thumbnail>
    </thumbnails>
</video>

vimeo.videos.delete

Delete a video

The authenticated user must own the video and have granted delete permission

Authentication

Authentication is required with 'delete' permission.

Parameters

Returns

This method returns an empty success response.
<rsp stat="ok"></rsp>

vimeo.videos.getThumbnailUrl

Get a thumbnail URL for a given video/size

If you simply supply the width, we'll generate the height for you.
this is useful because you don't always know the dimensions.

Possible sizes are 160x120, 100x75 and 200x150

Also 160, 100, 200 and 460

Authentication

Authentication is not required.

Parameters

Returns

<thumbnail width="96" height="72">http://vimeo.com/someimage.jpg</thumbnail>

Error Codes

vimeo.videos.setTitle

Set the title of a video (overwrites previous title)

Authentication

Authentication is required with 'write' permission.

Parameters

Returns

This method returns an empty success response.
<rsp stat="ok"></rsp>

vimeo.videos.setCaption

Set a new caption for a video (overwrites previous caption)

Authentication

Authentication is required with 'write' permission.

Parameters

Returns

This method returns an empty success response.
<rsp stat="ok"></rsp>

vimeo.videos.setFavorite

Set a video as a favorite.

Authentication

Authentication is required with 'write' permission.

Parameters

Returns

This method returns an empty success response.
<rsp stat="ok"></rsp>

Error Codes

vimeo.videos.addTags

Add specified tags to the video, this does not replace any tags.

Tags should be comma separated lists.

If the calling user is logged in, this will return information that calling user has access to (including private videos). If the calling user is not authenticated, this will only return public information, or a permission denied error if none is available.

Authentication

Authentication is required with 'write' permission.

Parameters

Returns

This method returns an empty success response.
<rsp stat="ok"></rsp>

vimeo.videos.removeTag

Remove specified tag from the video.

Authentication

Authentication is required with 'write' permission.

Parameters

Returns

This method returns an empty success response.
<rsp stat="ok"></rsp>

Error Codes

vimeo.videos.clearTags

Remove ALL of the tags from the video

Authentication

Authentication is required with 'write' permission.

Parameters

Returns

This method returns an empty success response.
<rsp stat="ok"></rsp>

vimeo.videos.addCast

Add specified cast member to the video.

Add one cast member at a time.

If the calling user is logged in, this will return information that calling user has access to (including private videos). If the calling user is not authenticated, this will only return public information, or a permission denied error if none is available.

Authentication

Authentication is required with 'write' permission.

Parameters

Returns

This method returns an empty success response.
<rsp stat="ok"></rsp>

vimeo.videos.getCast

Get the cast members of the clip (included the creator)

If the calling user is logged in, this will return information that calling user has access to (including private videos). If the calling user is not authenticated, this will only return public information, or a permission denied error if none is available.

Authentication

Authentication is not required.

Parameters

Returns

<cast total="2">
   <member id="146938" is_creator="1" role="I had visions"
       username="amandalynferri" display_name="amandalynferri" realname="amandalynferri"
       profileurl="http://v5.ted.vimeo/amandalynferri/l:app-X"
       videosurl="http://v5.ted.vimeo/amandalynferri/videos/l:app-X">
       <portraits>
         <portrait width="30" height="30">http://90.media.vimeo.com/...jpg</portait>
         <portrait width="75" height="75">http://90.media.vimeo.com/...jpg</portait>
         <portrait width="300" height="300">http://40.media.vimeo.com/...jpg</portait>
       </portraits>
   </member>
   <member id="102" is_creator="0" role="SILF"
       username="zach" display_name="Zach Klein" realname="Zach Klein"
       profileurl="http://v5.ted.vimeo/zach/l:app-X"
       videosurl="http://v5.ted.vimeo/zach/videos/l:app-X">
       <portraits>
         <portrait width="30" height="30">http://60.media.vimeo.com/...jpg</portait>
         <portrait width="75" height="75">http://90.media.vimeo.com/...jpg</portait>
         <portrait width="300" height="300">http://80.media.vimeo.com/...jpg</portait>
       </portraits>
   </member>
</cast>

vimeo.videos.removeCast

Remove a specified cast member from the video.

Add one cast member at a time.

If the calling user is logged in, this will return information that calling user has access to (including private videos). If the calling user is not authenticated, this will only return public information, or a permission denied error if none is available.

Authentication

Authentication is required with 'write' permission.

Parameters

Returns

This method returns an empty success response.
<rsp stat="ok"></rsp>

vimeo.videos.setPrivacy

Set the privacy of the video

The possibe privacy settings are "anybody" "contacts" "nobody" "users"
- "anybody" - Anybody can view the video
- "contacts" - Only the the uploader's contacts can view the video
- "nobody" - Only the uploader can view the video
- "users" - Only specific users can view the video

Authentication

Authentication is required with 'write' permission.

Parameters

Returns

This method returns an empty success response.
<rsp stat="ok"></rsp>

Error Codes

Video Comments

vimeo.videos.comments.getList

Get a list of comments on a video

Authentication

Authentication is not required.

Parameters

Returns

<comments video_id="17">
   <comment id="118568" author="JetSeven" authorname="Jet Seven"
      datecreate="2007-03-27 01:45:02" permalink="http://v5.localhost/17">
        Did you leave for good after that? That would have been great.
       <portraits>
         <portrait width="30" height="30">http://60.media.vimeo.com/...jpg</portait>
         <portrait width="75" height="75">http://90.media.vimeo.com/...jpg</portait>
         <portrait width="300" height="300">http://80.media.vimeo.com/...jpg</portait>
       </portraits>
   </comment>
   <comment id="118630" author="zach" authorname="Zach Klein"
      datecreate="2007-03-27 08:09:45" reply_to_comment_id="118568"
      permalink="http://v5.localhost/17">
        Yep.
       <portraits>
         <portrait width="30" height="30">http://60.media.vimeo.com/...jpg</portait>
         <portrait width="75" height="75">http://90.media.vimeo.com/...jpg</portait>
         <portrait width="300" height="300">http://80.media.vimeo.com/...jpg</portait>
       </portraits>
   </comment>
</comments>

vimeo.videos.comments.addComment

Add a comment to a video.

Authentication

Authentication is required with 'write' permission.

Parameters

Returns

<comment id="123456789" />

Error Codes

vimeo.videos.comments.deleteComment

Delete a specific comment posted on a video page.

Authentication

Authentication is required with 'write' permission.

Parameters

Returns

This method returns an empty success response.
<rsp stat="ok"></rsp>

Error Codes

vimeo.videos.comments.editComment

Update a specific comment posted on a video page.

Authentication

Authentication is required with 'write' permission.

Parameters

Returns

This method returns an empty success response.
<rsp stat="ok"></rsp>

Error Codes

People (Users)

vimeo.people.findByUserName

Get a user id and full/display name with a username.

You shouldn't need this to get the User ID,
we allow you to use the username instead of User ID everywhere, it's much nicer that way.

Authentication

Authentication is not required.

Parameters

Returns

<user id="151542">
    <username>ted</username>
    <display_name>Ted!</display_name>
</user>

Error Codes

vimeo.people.findByEmail

Get a user id and full/display name via an Email Address.

You shouldn't need to use this to get the User ID,
we allow you to use the username instead of User ID everywhere,
it's much nicer that way.

Authentication

Authentication is not required.

Parameters

Returns

<user id="151542">
    <username>ted</username>
    <display_name>Ted!</display_name>
</user>

Error Codes

vimeo.people.getInfo

Get tons of info about a user.

Authentication

Authentication is not required.

Parameters

Returns

<person id="151542" is_staff="1">
    <username>ted</username>
    <display_name>Ted!</display_name>
    <location>NYC</location>
    <url>http://tedroden.com</url>
    <number_of_contacts>48</number_of_contacts>
    <number_of_uploads>21</number_of_uploads>
    <number_of_likes>408</number_of_likes>
    <number_of_videos>71</number_of_videos>
    <number_of_videos_appears_in>71</number_of_videos_appears_in>
    <profileurl>http://vimeo.com/ted/l:app-4</profileurl>
    <videosurl>http://vimeo.com/ted/videos/l:app-4</videosurl>
</person>

Error Codes

vimeo.people.getPortraitUrl

Get a portrait URL for a given user/size

Portraits are square, so you only need to pass one size parameter.
Possible sizes are 30, 40, 50, 75, 100, and 300

Authentication

Authentication is not required.

Parameters

Returns

<portrait width="300" height="300">http://vimeo.com/someimage.jpg</portrait>

Error Codes

vimeo.people.addContact

Add a user as a contact for the authenticated user.

If Jim is authenticated, and the $user is sally. Sally will be Jim's contact.
It won't work the other way around. Depending on Sally's settings, this may
send her an email notifying her that Jim Added her as a contact.

Authentication

Authentication is required with 'write' permission.

Parameters

Returns

This method returns an empty success response.
<rsp stat="ok"></rsp>

vimeo.people.removeContact

Remove a user as a contact for the authenticated user.

Authentication

Authentication is required with 'write' permission.

Parameters

Returns

This method returns an empty success response.
<rsp stat="ok"></rsp>

vimeo.people.getUploadStatus

This tells you how much space the user has remaining for uploads.

We provide info in bytes and kilobytes. It probably makes sense for you to use kilobytes.

Authentication

Authentication is required with 'read' permission.

Parameters

Returns

<user id="151542">
    <bandwidth usedkb="4149" maxkb="1235605" remainingkb="1231456"
               usedbytes="4248848" maxbytes="1265259521" remainingbytes="1261010673" />
</user>

vimeo.people.addSubscription

Subscribe to a user's videos.

Just like on the site, you can subscribe to videos a user "appears" in or "likes." Or both!

This will not remove any subscriptions. So if the user is subscribed to a user for both
"likes" and "appears," this will not change anything if you only specify one of them.
If you want to remove one, you must call vimeo.people.removeSubscription().

Authentication

Authentication is required with 'write' permission.

Parameters

Returns

This method returns an empty success response.
<rsp stat="ok"></rsp>

vimeo.people.removeSubscription

Unsubscribe to a user's videos.

Authentication

Authentication is required with 'write' permission.

Parameters

Returns

This method returns an empty success response.
<rsp stat="ok"></rsp>

Contacts

vimeo.contacts.getList

Get a list of contacts for a specific user.

Also, you can add contacts with vimeo.people.addContact and remove people with with vimeo.people.removeContact

Authentication

Authentication is not required.

Parameters

Returns

<contact id="151382"
      username="blakewhitman" display_name="Blake Whitman" realname="Blake Whitman"
      profileurl="http://v5.ted.vimeo/blakewhitman/l:app-1"
      videosurl="http://v5.ted.vimeo/blakewhitman/videos/l:app-1">
   <portraits>
       <portrait width="30" height="30">http://70.media.vimeo...jpg</portrait>
       <portrait width="75" height="75">http://40.media.vimeo...jpg</portrait>
       <portrait width="300" height="300">http://90.media.vimeo....jpg</portrait>
   </portraits>
</contact>

vimeo.groups.getMembers

Get a list of members of the group

Authentication

Authentication is not required.

Parameters

Returns

%userlist%

Error Codes

The Upload API

vimeo.videos.getUploadTicket

Generate a new upload Ticket.

You'll need to pass this to the uploader.
It's only good for one upload, only good for one user

Authentication

Authentication is required with 'write' permission.

Returns

<ticket id="88ce9e9a9b012" />

vimeo.videos.checkUploadStatus

Check the status of an upload started via the API

This is how you get the video_id of a clip uploaded from the API
If you never call this to check in, we assume it was abandoned and don't process it.

Authentication

Authentication is required with 'write' permission.

Parameters

Returns

<ticket id="88ce9e9a9b012" video_id="1234" is_uploading="1" is_transcoding="0" />

Error Codes