Skip to content
Find file
Fetching contributors…
Cannot retrieve contributors at this time
912 lines (644 sloc) 28.6 KB

API Documentation

This is the documentation of v2 of Amara's API. Please contact us if you’d like to use the Amara API for commercial purposes.


The v1 of the API is deprecated, but can still be accessed through . Users should migrate to the v2 of the API. If you're missing a feature on the API, please let us know .


Before interacting with the API, you must have an API key. In order to get one, create a user on the Amara website, then go to the edit profile page. At the bottom of the page you will find a "Generate new key" button . Clicking on it will fetch your user the needed API key.

Every request must have the username and the API keys as headers. For example:

X-api-username: my_username_here
X-apikey: my_api_key_here

So a sample request would look like this:

$ curl -H 'X-api-username: my_username_here' -H 'X-apikey: my_api_key_here' \

Data Formats

The API accepts request data and will output the following formats: JSON, XML and YAML. Unless you have a strong reason not to, we recommend using the JSON format, as it's the one that gets the most usage (and therefore more testing).

To specify the format, add the Accept header appropriately, for example:

Accept: application/json

You can also specify the desired format in the url, sending the request variable format=json.

API endpoint

The endpoint for the API is the environment base URL + /api2/partners/.

Possible environments:

  • Staging:
  • Production:

Therefore, most clients should be making requests against:

All API requests should go through https. The staging environment might need HTTP basic auth, please contact us to request credentials. When basic auth is needed on staging, you end up with a request like this:

$ curl -H 'X-api-username: my_username_here' -H 'X-apikey: my_api_key_here' \
    --user basic_auth_username:basic_auth_password \

If you're under a partnership, you might have a different base URL. Please contact us if you're not sure.

API interaction overview

All resources share a common structure when it comes to the basic data operations.

  • GET request is used to viewing data
  • POST request is used for creating new items
  • PUT request is used for updating existing items
  • DELETE request is used for deleting existing items

For example, in order to request a list of teams the user is current on, you would issue the following request:

To view a detail of the test team, you could do:

Example response

    "created": "2012-04-18T09:26:59",
    "deleted": false,
    "description": "",
    "header_html_text": "",
    "is_moderated": false,
    "is_visible": true,
    "logo": null,
    "max_tasks_per_member": null,
    "membership_policy": "Open",
    "name": "test",
    "projects_enabled": false,
    "resource_uri": "/api2/partners/teams/test/",
    "slug": "test",
    "subtitle_policy": "Anyone",
    "task_assign_policy": "Any team member",
    "task_expiration": null,
    "translate_policy": "Anyone",
    "video_policy": "Any team member",
    "workflow_enabled": false

Many of the available resources will allow you to filter the response by a certain field. Filters are specified as GET parameters on the request. For example, if you wanted to view all videos belong to a team called "butterfly-club", you could do:

In addition to filters, you can request that the response is ordered in some way. To order videos by title, you would do

Each resource section will contain a list of relevant options.

Here is an example of creating a new team via curl.

curl -i -X POST -H "Accept: application/json" \
    -H 'X-api-username: my_username_here' -H 'X-apikey: my_api_key_here' \
    -H "Content-Type: application/json" \
    --data '{"name": "Team name", "slug": "team-name"}' \

You can use the same fields that you get back when requesting a team detail.

To update a team, you could issue a request like this:

curl -i -X PUT -H "Accept: application/json" \
    -H 'X-api-username: my_username_here' -H 'X-apikey: my_api_key_here' \
    -H "Content-Type: application/json" \
    --data '{"name": "My team name"}' \


The above example only includes the name field for illustration. When sending a PUT request, always include all fields. For a list of all fields, see the response to a GET request.

Partner video ids

If you are a partner, you can set the id field for a video. Simply supply the usePartnerId parameter in your request and we will use your id for look ups. The parameter can be sent as a parameter to any kind of API call. This is useful if you already have a database of video ids and don't want to maintain a mapping between those ids and Amara ids.

For example, let's say you have an Amara video with the id of yxsSV807Dcho. Your application uses numeric id internally and you would like to tell Amara to remember that this video has an id of 12345 on your system. You can modify the video like this:

curl -i -X PUT -H "Accept: application/json" \
    -H 'X-api-username: my_username_here' -H 'X-apikey: my_api_key_here' \
    -H "Content-Type: application/json" \
    --data '{"usePartnerId": true, "id": "12345"}' \

And then, you can start referencing the video by the numeric id when interacting with the API. For example, the following call will retrieve the above video.

curl -i -X GET -H "Accept: application/json" \
    -H 'X-api-username: my_username_here' -H 'X-apikey: my_api_key_here' \
    -H "Content-Type: application/json" \

Available Resources

The following resources are available to end users:

Video Resource

Represents a video on Amara.

Listing videos

Creating Videos:

When submitting URLs of external providers (i.e. youtube, vimeo), the metadata (title, description, duration) can be fetched from them. If you're submitting a link to a file (mp4, flv) then you can make sure those attributes are set with these parameters. Note that these parameters do override any information from the original provider.

Information about a specific video can be retrieved from the URL:

Video Detail:

The video listing resource already returns a resource_uri for each video to be used when retrieving the details.

Updating a video object:

With the same parameters for creation. Note that through out our system, a video cannot have it's URLs changed. So you can change other video attributes (title, description) but the URL sent must be the same original one.

Moving videos between teams and projects

In order to move a video from one team to another, you can make a request to change the video where you change the team value in the Video Resource.

In order to move the video from Team A to Team B, you would make the following request.

curl -i -X PUT -H "Accept: application/json" \
    -H 'X-api-username: my_username_here' -H 'X-apikey: my_api_key_here' \
    -H "Content-Type: application/json" \
    --data '{"team": "team_b"}' \

Please note that the value that is sent as the team is the team's slug. The user making the change must have permission to remove a video from the originating team and permission to add a video to the target team.

Setting the team value to null will remove it from its current team.

A similar mechanism can be used to change what project a given video is filed under. The important difference is that when moving a video to different project, the team must be specified in the payload even if it doesn't change.

    "team:" "team-slug",
    "project": "new-project"

Example response:

    "all_urls": [
    "created": "2012-05-15T06:05:14",
    "description": "Concierto Grupo NOMOI \n(Torrevieja 17/05/2009)\nProyecto TRANSMOSFERA\nAcci\u00f3n interactiva de m\u00fasica, teatro e imagen.\nJuan Pablo Zaragoza - V\u00eddeo y Guitarra sintetizada\nJos\u00e9 Mar\u00eda Pastor - Electr\u00f3nica\nRaul Ferrandez - Voz y acci\u00f3n teatral",
    "duration": null,
    "id": "PUuHIcJ5mq5S",
    "languages": [],
    "original_language": null,
    "project": null,
    "resource_uri": "/api2/partners/videos/PUuHIcJ5mq5S/",
    "site_url": "",
    "team": null,
    "thumbnail": "",
    "title": "Concierto NOMOI (Torrevieja 17/05/2009)"

Video Language Resource

Represents a language for a given video on Amara.

Listing video languages:

Creating Video Languages:

Information about a specific video language can be retrieved from the URL:

Example response:

    "completion": "100%",
    "created": "2012-05-17T12:25:54",
    "description": "",
    "id": "8",
    "is_original": false,
    "is_translation": false,
    "language_code": "cs",
    "num_versions": 1,
    "original_language_code": "en",
    "percent_done": 0,
    "resource_uri": "/api2/partners/videos/Myn4j5OI7BxL/languages/8/",
    "site_url": "",
    "subtitle_count": 11,
    "title": "\"Postcard From 1952\" - Explosions in The Sky",
    "versions": [
            "author": "honza",
            "status": "published",
            "text_change": "1.0",
            "time_change": "1.0",
            "version_no": 0

Subtitles Resource

Represents the subtitle set for a given video language.

Fetching subtitles for a given language:

If no version is specified, the latest public version will be returned. For videos that are not under moderation it will be the latest one. For videos under moderation only the latest published version is returned. If no version has been accepted in review, no subtitles will be returned.

Creating new subtitles for a language:

This will create a new subtitle version with the new subtitles.

Example response:

    "description": "Centipede - Knife Party\nFireworks - Pyro Spectaculars by Souza\n\n( Sittin' On ) The Dock of the Bay - Otis Redding\nLights - Journey\nFrisco Blues - John Lee Hooker\nSan Francisco ( Be Sure to Wear Flowers in Your Hair ) - Scott McKenzie  \nI Left My Heart in San Francisco - Tony Bennett\n\nIf you didn't understand what was happening, you should probably watch it again.\nThis has been a Seventh Movement effort.",
    "note": "",
    "resource_uri": "",
    "site_url": "http://example-host/api2/partners/videos/TRUFD3IyncAt/en/1/",
    "sub_format": "srt",
    "subtitles": [
            "end": 4,
            "id": 1,
            "start": 3,
            "start_of_paragraph": false,
            "text": "This is a cool bridge"
            "end": 5,
            "id": 2,
            "start": 4,
            "start_of_paragraph": false,
            "text": "Really cool"
            "end": 6,
            "id": 3,
            "start": 5,
            "start_of_paragraph": false,
            "text": "I love it"
    "title": "The Golden Gate Way",
    "version_no": 0,
    "video": "The Golden Gate Way",
    "video_description": "Centipede - Knife Party\nFireworks - Pyro Spectaculars by Souza\n\n( Sittin' On ) The Dock of the Bay - Otis Redding\nLights - Journey\nFrisco Blues - John Lee Hooker\nSan Francisco ( Be Sure to Wear Flowers in Your Hair ) - Scott McKenzie  \nI Left My Heart in San Francisco - Tony Bennett\n\nIf you didn't understand what was happening, you should probably watch it again.\nThis has been a Seventh Movement effort.",
    "video_title": "The Golden Gate Way"

Language Resource

Represents a listing of all available languages on the Amara platform.

Listing available languages:

User Resource

One can list and create new users through the API.

Listing users:

User datail:

Creating Users:

The response also includes the 'api_key' for that user. If clients wish to make requests on behalf of this newly created user through the api, they must hold on to this key, since it won't be returned in the detailed view.

Example response:

    "avatar": "",
    "biography": "The guy with a boring name.",
    "first_name": "John",
    "full_name": "John Smith",
    "homepage": "",
    "last_name": "Smith",
    "num_videos": 8,
    "resource_uri": "/api2/partners/users/jsmith/",
    "username": "jsmith"

Video Url Resource

One can list, update, delete and add new video urls to an existing video.

Listing video urls

Video URL detail:

Where the url-id can be fetched from the list of urls.

Updating video-urls:

Creating video-urls:

To delete a url:

If this is the only URL for a video, the request will fail. A video must have at least one URL.

Team Resource

You can list existing teams:

You can view details for an existing team:

Creating a team:

Updating a team:

Deleting a team:


You can only create new teams if you have been granted this privilege. Contact us if you require a partner account.

Policy values

Membership policy:

  • Open
  • Application
  • Invitation by any team member
  • Invitation by manager
  • Invitation by admin

Video policy:

  • Any team member
  • Managers and admins
  • Admins only

Task assign policy:

  • Anyone
  • Any team member
  • Only managers and admins
  • Only admins

Example response

    "created": "2012-04-18T09:26:59",
    "deleted": false,
    "description": "",
    "header_html_text": "",
    "is_moderated": false,
    "is_visible": true,
    "logo": null,
    "max_tasks_per_member": null,
    "membership_policy": "Open",
    "name": "test",
    "projects_enabled": false,
    "resource_uri": "/api2/partners/teams/test/",
    "slug": "test",
    "subtitle_policy": "Anyone",
    "task_assign_policy": "Any team member",
    "task_expiration": null,
    "translate_policy": "Anyone",
    "video_policy": "Any team member",
    "workflow_enabled": false

Team Member Resource

This resource allows you to change team membership information without the target user's input. This resource is only applicable to:

  • Teams associated with the partner's account
  • Users who are already members of one of the partner's teams

You can list existing members of a team:

Adding a new member to a team:

Updating a team member (e.g. changing their role):

Removing a user from a team:

Example of adding a new user:

    "username": "test-user",
    "role": "manager"


  • owner
  • admin
  • manager
  • contributor


Changed behavior: the previous functionality was moved the Safe Team Member Resource documented below.


If a user belongs to a partner team, any admin or above on any of the partner's teams can move the user anywhere within the partner's teams. Moving is done by first adding the user to the target team and then by removing the user from the originating team.

Safe Team Member Resource

This resource behaves the same as the normal Team Member resource with one small difference. When you add a user to a team, we will send an invitation to the user to join the team. If the user doesn't exist, we will create it. The standard Team Member resource simply adds the user to the team and returns.


Adding a new member to a team:

Project Resource

List all projects for a given team:

Project detail:

Create a new project:

Example payload for creating a new project:

    "name": "Project name",
    "slug": "project-slug",
    "description": "This is an example project.",
    "guidelines": "Only post family-friendly videos."


You can only create projects for a specific team.

Update an existing project:

For example, to change the project's name:

    "name": "Project"

Delete a project:

Task Resource

List all tasks for a given team:

Task detail:

Create a new task:

Update an existing task:

Delete an existing task:


  • approved - If the team supports workflows, you can set the stage in which the task finds itself.

    • In Progress
    • Approved
    • Rejected
  • assignee - The username of the user that this task will be assigned to

  • language

  • priority - An arbitrary integer denoting priority level; each team can set their own policy regarging priority of tasks

  • video_id - The unique identifier of the video this task relates to

  • type - Type of the task
    • Subtitle
    • Translate
    • Review
    • Approve
  • version_no - Subtitle version number (required for Approve and Review tasks)

  • completed - null if the task hasn't been completed yet; a datetime string it has

An example response:

    "approved": null,
    "assignee": "johnsmith",
    "language": "en",
    "priority": 1,
    "resource_uri": "/api2/partners/teams/all-star/tasks/3/",
    "type": "Subtitle",
    "video_id": "Myn4j5OI7BxL",
    "completed": "2012-07-18T14:08:07"

Activity resource

This resource is read-only.

List activity items:

Activity types:

  1. Add video
  2. Change title
  3. Comment
  4. Add version
  5. Add video URL
  6. Add translation
  7. Subtitle request
  8. Approve version
  9. Member joined
  10. Reject version
  11. Member left
  12. Review version
  13. Accept version
  14. Decline version
  15. Delete video

Activity item detail:

Example response:

    "type": 1,
    "comment": null,
    "created": "2012-07-12T07:02:19",
    "id": "1339",
    "language": "en",
    "new_video_title": "",
    "resource_uri": "/api2/partners/activity/1339/",
    "user": "test-user"

Message Resource

The message resource allows you to send messages to user and teams.

You can only send the user parameter or the team parameter at once.

Application resource

For teams with membership by application only.

List application items:

Application item detail:

Example response:

   "created": "2012-08-09T17:48:48",
   "id": "12",
   "modified": null,
   "note": "",
   "resource_uri": "/api2/partners/teams/test-team/applications/12/",
   "status": "Pending",
   "user": "youtube-anonymous"


To delete an Application:

Applications can have their statuses updated:

Note that if an application is pending (has the status='Pending'), the API can set it to whatever new status. Else, if the application has already been approved or denied, you won't be able to set the new status. For cases were an approval was wrongly issues, you'd want to remove the team member. Otherwise you'd want to invite the user to the team.

Jump to Line
Something went wrong with that request. Please try again.