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
- 99: User not logged in / Insufficient permissions
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
- string frob (required) - A frob generated via vimeo.auth.getFrob
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
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
- string auth_token - - Just send the auth token
Returns
<auth>
<token>12354</token>
<perms>write</perms>
<user id="151542" username="ted" fullname="Ted!" />
</auth>
Error Codes
- 98: Login failed / Invalid auth token
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
- string user_id - User ID, this can be the ID number (151542) or the username (ted)
- int page - Which page to show.
- int per_page - How many results per page?
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
- string user_id - User ID, this can be the ID number (151542) or the username (ted)
- int page - Which page to show.
- int per_page - How many results per page?
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
- string user_id - User ID, this can be the ID number (151542) or the username (ted)
- int page - Which page to show.
- int per_page - How many results per page?
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
- string user_id - User ID, this can be the ID number (151542) or the username (ted) %user_default%
- int page - Which page to show.
- int per_page - How many results per page?
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
- string tag (required) - A single tag: "cat" "new york" "cheese"
- string user_id - User ID, this can be the ID number (151542) or the username (ted) %user_default%
- int page - Which page to show.
- int per_page - How many results per page?
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
- string user_id - User ID, this can be the ID number (151542) or the username (ted)
- int page - Which page to show.
- int per_page - How many results per page?
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
- string user_id - User ID, this can be the ID number (151542) or the username (ted)
- int page - Which page to show.
- int per_page - How many results per page?
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
- string user_id - User ID, this can be the ID number (151542) or the username (ted)
- int page - Which page to show.
- int per_page - How many results per page?
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
- string query (required) - The search terms
- string user_id - User ID, this can be the ID number (151542) or the username (ted)
- boolean contacts_only - Set this to 1, true, yes or 0, false, no. If yes, we'll only search the users contacts. If this is set, you must specifiy a user_id. Otherwise it will be ignored without error.
- int per_page - How many results per page?
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
- int video_id (required) - Get information from this video
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
- int video_id (required) - Delete this video!
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
- string video_id - The video ID
- string size - The size (WxH) of the thumbnail that you want. (example: the string "96x72" or "460")
Returns
<thumbnail width="96" height="72">http://vimeo.com/someimage.jpg</thumbnail>
Error Codes
- 901: Invalid size requested
vimeo.videos.setTitle
Set the title of a video (overwrites previous title)
Authentication
Authentication is required with 'write' permission.
Parameters
- int video_id (required) - Set the title of this video.
- string title (required) - The new title. 128 is the max length for this field, any longer and it will be trimmed.
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
- int video_id (required) - Set the caption to this video.
- string caption (required) - The new caption.
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
- int video_id (required) - Mark this video as a favorite.
- boolean favorite (required) - If this is "1", "true" or "yes," we'll set this as a favorite. Otherwise use "0", "false", "no."
Returns
This method returns an empty success response.
<rsp stat="ok"></rsp>
Error Codes
- 903: Invalid boolean value. Must b
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
- int video_id (required) - Add tags to this video.
- string tags (required) - Comma separated list of tags (lions, tigers, bears)
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
- int video_id (required) - Add tags to this video.
- string tag_id (required) - Tag to remove. This should be a tag id returned by vimeo.videos.getInfo
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
- int video_id (required) - Add tags to this video.
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
- int video_id (required) - Add tags to this video.
- string user (required) - The user to add. User ID, this can be the ID number (151542) or the username (ted)
- string role - The Role of the user in the video.
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
- int video_id (required) - We'll get the cast for this video id.
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
- int video_id (required) - Add tags to this video.
- string user (required) - The user to add. User ID, this can be the ID number (151542) or the username (ted)
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
- int video_id (required) - the id of the video to set privacy on
- string privacy (required) - The privacy Setting
- string users - A comma separated list of users who can view the video.
Returns
This method returns an empty success response.
<rsp stat="ok"></rsp>
Error Codes
- 904: Invalid privacy type
Video Comments
vimeo.videos.comments.getList
Get a list of comments on a video
Authentication
Authentication is not required.
Parameters
- int video_id (required) - Get the comments from this video.
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
- int video_id (required) - Add a comment to this video.
- string comment_text (required) - The text of the comment
- int reply_to_comment_id - If this is a reply to another comment, provide that comment ID. We only allow comments one level deep. So if you reply to a reply, we're going to add it as a reply to the original comment.
Returns
<comment id="123456789" />
Error Codes
- 1: Video not found. (Either the video wasn't found, or you don't have permission)
- 8: Blank comment.
vimeo.videos.comments.deleteComment
Delete a specific comment posted on a video page.
Authentication
Authentication is required with 'write' permission.
Parameters
- int video_id - The ID of the video that has the comment.
- int comment_id - The ID of the comment to delete.
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
- int video_id - The ID of the video that has the comment.
- int comment_id - The ID of the comment to delete.
- string comment_text (required) - The text of the comment
Returns
This method returns an empty success response.
<rsp stat="ok"></rsp>
Error Codes
- 8: Blank comment.
- 2: Comment not found.
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
- string username - The username to lookup
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
- string find_email - The username to lookup
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
- string user_id - The id of the user we want.
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
- string user - The username to lookup
- int size - The size of the portrait you you want. (defaults to 75)
Returns
<portrait width="300" height="300">http://vimeo.com/someimage.jpg</portrait>
Error Codes
- 901: Invalid size requested
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
- string user - The user to add. User ID, this can be the ID number (151542) or the username (ted)
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
- string user - The user to remove. User ID, this can be the ID number (151542) or the username (ted)
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
- string user - The user to check. User ID, this can be the ID number (151542) or the username (ted)
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
- string user - The user to remove. User ID, this can be the ID number (151542) or the username (ted)
- string type - with "likes" or "appears" or "likes,appears" or "appears,likes"
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
- string user - The user to remove. User ID, this can be the ID number (151542) or the username (ted)
- string type - with "likes" or "appears" or "likes,appears" or "appears,likes"
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
- string user_id - User ID, this can be the ID number (151542) or the username (ted)
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
- string group_id - the id of the group
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
- string ticket_id - The ticket number of the upload
Returns
<ticket id="88ce9e9a9b012" video_id="1234" is_uploading="1" is_transcoding="0" />
Error Codes