API Documentation

Amara provides a REST API to interactive with the site. Please contact us if you’d like to use the Amara API for commercial purposes.

Note

This documentation is for the upcoming Amara API. It is currently being actively developed and not yet fully functional. See the API changes blog post for more info.

Authentication

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-api-key: my_api_key_here

Note

You can also use the deprecated X-apikey header to specify your key

So a sample request would look like this:

GET amara.org/api/videos/
Request Headers:
 
  • X-api-username – <Username>
  • X-api-key – <API key>

Data Formats

The API accepts request data in the several formats. Use the Content-Type HTTP header to specify the format of your request:

Format Content-Type
JSON (recommended) application/json
XML application/xml
YAML application/yaml

In this documentation, we use the term “Request JSON Object” to specify the fields of the objects sent as the request body. Replace “JSON” with “XML” or “YAML” if you are using one of those input formats.

Here’s an example of request data formated as JSON:

{"field1": "value1", "field2": "value2", ... }

By default we will return JSON output. You can the Accept header to select a different output format. You can also use the format query param to select the output formats. The value is the format name in lower case (for example format=json).

We also support text/html as an output format and application/x-www-form-urlencoded and multipart/form-data as input formats. However, this is only to support browser friendly endpoints. It should not be used in API client code.

Paginated Responses

Many listing API endpoints are paginated to prevent too much data from being fetched and returned at one time (for example the video listing API). These endpoints are marked with paginated in their descriptions. Paginated responses only return limited number of results per request, alongside links to the next/previous page.

Here’s an example paginated response from the Teams listing:

{
    "meta": {
        "previous": null,
        "next": "http://amara.org/api/teams?limit=20&offset=20",
        "offset": 0,
        "limit": 20,
        "total_count": 151
    },
    "objects": [
        {
            "name": "",
            "slug": "tedx-import",
            "description": "",
            "is_visible": true,
            "membership_policy": "Open",
            "video_policy": "Any team member"
        },
        ...
    ]
}
  • The meta field contains pagination information, including next/previous links, the total number of results, and how many results are listed per page
  • The objects field contains the objects for this particular page

Browser Friendly Endpoints

All our API endpoints can be viewed in a browser. This can be very nice for exploring the API and debugging issues. To view API endpoints in your browser simply log in to amara as usual then paste the API URL into your address bar.

Value Formats

  • Dates/times use ISO 8601 formatting
  • Language codes use BCP-47 formatting

Use HTTPS

All API requests should go through https. This is important since an HTTP request will send your API key over the wire in plaintext.

The only exception is when exploring the API in a browser. In this case you will be using the same session-based authentication as when browsing the site.

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

To view a list of videos on the site you can use

GET amara.org/api/videos/

To get info about the video with id “foo” you can use

GET amara.org/api/videos/foo

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:

GET amara.org/api/videos/?team=butterfly-club

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

GET amara.org/api/videos/?order_by=title

To create a video you can use

POST amara.org/api/videos/

To update the video with video id foo use:

PUT amara.org/api/videos/foo

Available Resources

The following resources are available to end users:

Videos Resource

Get info for a specific video

GET /api/videos/[video-id]/
Response JSON Object:
 
  • id – Amara video id
  • primary_audio_language_code – language code for the audio language
  • title – Video title
  • description – Video description
  • duration – Video duration in seconds (or null if not known)
  • thumbnail – URL to the video thumbnail
  • created – Video creation date/time
  • team – Slug of the Video’s team (or null)
  • metadata – Dict mapping metadata names to values
  • languages – List of languages that have subtitles started (see below)
  • all_urls – List of URLs for the video (the first one is the primary video URL)
  • resource_uri – API uri for the video
  • original_language – contains a copy of the primary_audio_language_code data (deprecated)

Language data:

Response JSON Object:
 
  • code – Language code
  • name – Human readable label for the language
  • visibile – Are the subtitles publicly viewable?
  • dir – Language direction (“ltr” or “rtl”)
  • subtitles_uri – API URI for the subtitles
  • resource_uri – API URI for the video language

Listing videos

GET /api/videos/

paginated

Query Parameters:
 
  • video_url – list only videos with the given URL, useful for finding out information about a video already on Amara.
  • team – Only show videos that belong to a team identified by slug.
  • project – Only show videos that belong to a project with the given slug. Passing in null will return only videos that don’t belong to a project.
  • order_by

    Applies sorting to the video list. Possible values:

    • title: ascending
    • -title: descending
    • created: older videos first
    • -created : newer videos

Creating Videos

POST /api/videos/
Request JSON Object:
 
  • video_url – The url for the video. Any url that Amara accepts will work here. You can send the URL for a file (e.g. http:///www.example.com/my-video.ogv), or a link to one of our accepted providers (youtube, vimeo, dailymotion, blip.tv)
  • title – title of the video
  • description – About this video
  • duration – Duration in seconds
  • primary_audio_language_code – language code for the main language spoken in the video.
  • thumbnail – URL to the video thumbnail
  • metadata – Dictionary of metadata key/value pairs. These handle extra information about the video. Right now the type keys supported are “speaker-name” and “location”. Values can be any string.
  • team – team slug for the video or null to remove it from its team.
  • project – project slug for the video or null to put it in the default project.

Note

Deprecated: For all fields, if you pass an empty string, we will treat it as if the field was not present in the input.

Deprecated: For slug and project, You can use the string “null” as a synonym for the null object.

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 override any information from the original provider.

Updating a video object

PUT /api/videos/[video-id]/

With the same parameters for creation, excluding video_url. 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

To move a video from one team to another, you can make a put request with a team value. Similarly, you can move a video to a different project using the project field. 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.

Note

To move a video to a different project, the team must be specified in the payload even if it doesn’t change.

Video URL Resource

Listing video urls

GET /api/videos/[video-id]/urls/

paginated

Parameters:
  • video-id – Amara video ID
Response JSON Object:
 
  • created – creation date/time
  • url – URL string
  • primary – is this the primary URL for the video?
  • original – was this the URL that was created with the video?
  • resource_uri – API URL for the video URL
  • id – Internal ID for the object (deprecated, use resource_uri instead to create URLs for the object)

Adding a video url

POST /api/videos/[video-id]/urls/
Parameters:
  • video-id – Amara Video ID
Request JSON Object:
 
  • url – Video URL. This can be any URL that works in the add video form for the site (mp4 files, youtube, vimeo, etc). Note: The URL cannot be in use by another video.
  • primary – If True, this URL will be made the primary URL
  • original – Is this is the first url for the video?

Get details on a single URL

GET [url-resource-uri]
Parameters:
  • url-resource-url – resource_uri returned from the video URLs listing

The response fields are the same as for the list endpoint

Make a URL the primary URL for a video

PUT [url-resource-uri]
Parameters:
  • url-resource-url – resource_uri returned from the video URLs listing
Request JSON Object:
 
  • primary – True to make the URL the primary URL. This will unset the primary flag for all other URLs.
  • original – Is this is the first url for the video?

Deleting URLs

DELETE [url-resource-uri]
Parameters:
  • url-resource-url – resource_uri returned from the video URLs listing

Video Language Resource

Container for subtitles in a language for a video on Amara.

Listing video languages

GET /api/videos/[video-id]/languages/

paginated

Response JSON Object:
 
  • language_code – BCP 47 code for this language
  • name – Human-readable name for this language
  • is_primary_audio_language – Is this language the primary language spoken in the video?
  • is_rtl – Is this language RTL?
  • resource_uri – API URL for the language
  • created – date/time the language was created
  • title – Video title, translated into this language
  • description – Video description, translated into this language
  • metadata – Video metadata, translated into this language
  • subtitles_complete – Are the subtitles complete for this language?
  • subtitle_count – Number of subtitles for this language
  • reviewer – Username of the reviewer fro task-based teams
  • approver – Username of the approver for task-based teams
  • is_translation – Is this language translated from other languages (deprecated)
  • original_language_code – Source translation language (deprecated)
  • num_versions – Number of subtitle versions, the length of the versions array should be used instead of this (deprecated)
  • id – Internal ID for the language (deprecated)
  • is_original – alias for is_primary_audio_language (deprecated)
  • versions – List of subtitle version data
  • versions.author – Subtitle author’s username
  • versions.version_no – number of the version
  • versions.published – is this version publicly viewable?

Creating Video Languages

POST /api/videos/[video-id]/languages/
Form Parameters:
 
  • language_code – bcp-47 code for the language
  • is_primary_audio_language – Boolean indicating if this is the primary spoken language of the video (optional).
  • subtitles_complete – Boolean indicating if the subtitles for this languagge is complete (optional).
  • is_original – Alias for is_primary_audio_language (deprecated)
  • is_complete – Alias for subtitles_complete (deprecated)

Getting details on a specific language

GET /api/videos/[video-id]/languages/[lang-identifier]/
Parameters:
  • lang-identifier – language code to fetch. deprecated: this can also be value from the id field

See also

To list available languages, see Language Resource.

Subtitles Resource

Get/create subtitles for a video

Fetching subtitles for a given language

GET /api/videos/[video-id]/languages/[language-code]/subtitles/
Parameters:
  • video-id – Amara Video ID
  • language-code – BCP-47 language code. deprecated: you can also specify the internal ID for a langauge
Query Parameters:
 
  • sub_format – The format to return the subtitles in. This can be any format that amara supports including dfxp, srt, vtt, and sbv. The default is json, which returns subtitle data encoded list of json dicts.
  • version_number – version number to fetch. Versions are listed in the VideoLanguageResouce request. If none is specified, the latest public version will be returned.
  • version – Alias for version_number (deprecated)
Response JSON Object:
 
  • version_number – version number for the subtitles
  • subtitles – Subtitle data (str)
  • sub_format – Format of the subtitles
  • language – Language data
  • language.code – BCP-47 language code
  • language.name – Human readable name for the language
  • language.dir – Language direction (“ltr” or “rtl”)
  • title – Video title, translated into the subtitle’s language
  • description – Video description, translated into the subtitle’s language
  • metadata – Video metadata, translated into the subtitle’s language
  • video_title – Video title, translated into the video’s language
  • video_description – Video description, translated into the video’s language
  • resource_uri – API URI for the subtitles
  • site_uri – URI to view the subtitles on site
  • video – Copy of video_title (deprecated)
  • version_no – Copy of version_number (deprecated)

Getting subtitle data only

Sometimes you want just subtitles data without the rest of the data. This is possible using a special Accept headers or format query strings. This can be used to download a DFXP, SRT, or any other subtitle format that Amara supports. If one of these is used, then the sub_format param will be ignored.

Format Accept header format query param
DFXP application/ttml+xml dfxp
SBV text/sbv sbv
SRT text/srt srt
SSA text/ssa ssa
WEBVTT text/vtt vtt

Examples:

GET /api/videos/abcdef/languages/en/subtitles/?format=dfxp
GET /api/videos/abcdef/languages/en/subtitles/
Request Headers:
 

Creating new subtitles

POST /api/videos/[video-id]/languages/[language-code]/subtitles/
Parameters:
  • video-id – Amara Video ID
  • language-code – BCP-47 language code. deprecated: you can also specify the internal ID for a langauge
Request JSON Object:
 
  • subtitles – The subtitles to submit
  • sub_format – The format used to parse the subs. The same formats as for fetching subtitles are accepted. Optional - defaults to dfxp.
  • title – Give a title to the new revision
  • description – Give a description to the new revision
  • action – Name of the action to perform - optional, but recommended. If given, the is_complete param will be ignored. See the Subtitles Action Resource for details.
  • is_complete – Boolean indicating if the complete subtitling set is available for this language - optional, defaults to false. (deprecated, use action instead)

Subtitles Action Resource

Actions are operations on subtitles. Actions correspond to the buttons in the upper-right hand corner of the subtitle editor (save, save a draft, approve, reject, etc). This resource is used to list and perform actions on the subtitle set.

Note

You can also perform an action together a new set of subtitles using the action param of the Subtitles Resource.

Get the list of possible actions:

GET /api/videos/[video-id]/languages/[lang-identifier]/subtitles/actions/
Parameters:
  • video-id – ID of the video
  • lang-identifier – subtitle language code
Response JSON Object:
 
  • action – Action name
  • label – Human-friendly string for the action
  • complete – Does this action complete the subtitles? If true, then when the action is performed, we will mark the subtitles complete. If false, we will mark them incomplete. If null, then we will not change the subtitles_complete flag.

Perform an action on a subtitle set

POST /api/videos/[video-id]/languages/[lang-identifier]/subtitles/actions/
Query Parameters:
 
  • video-id – ID of the video
  • lang-identifier – subtitle language code
Request JSON Object:
 
  • action – name of the action to perform

Subtitles Notes Resource

Get/Create notes saved in the editor.

Note

Subtitle notes are currently only supported for team videos

Get the list of notes:

GET /api/videos/[video-id]/languages/[lang-identifier]/subtitles/notes
Query Parameters:
 
  • video-id – ID of the video
  • lang-identifier – subtitle language code
Response JSON Object:
 
  • user – Username of the note author
  • created – date/time that the note was created
  • body – text of the note.

Create a new note

POST /api/videos/[video-id]/languages/[lang-identifier]/subtitles/actions/
Query Parameters:
 
  • video-id – ID of the video
  • lang-identifier – subtitle language code
Request JSON Object:
 
  • body – note body

Languages Resource

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

Listing available languages:

GET /api/languages/
Request JSON Object:
 
  • languages – maps language codes to language names

Users Resource

Fetching user data

GET /api/users/[username]/
Response JSON Object:
 
  • username – username
  • first_name – First name
  • last_name – Last name
  • homepage – Homepage URL
  • biography – Bio text
  • num_videos – Number of videos followed by the user
  • languages – List of languages the user speaks
  • avatar – URL to the user’s avatar image
  • resource_uri – User API URI
  • full_name – Full name of the user.

Note

Many of these fields will be blank if the user hasn’t set them from their profile page

Note

The full_name field is not used in the amara interface and there is no requirement that it needs to be first_name + last_name. This field is for API consumers that want to create users to match their internal users and use the full names internally instead of first + last.

Creating Users

POST /api/users/
Request JSON Object:
 
  • username – username. 30 chars or fewer alphanumeric chars, @, _ and - are accepted.
  • email – A valid email address
  • password – any number of chars, all chars allowed.
  • first_name – Any chars, max 30 chars. Optional.
  • last_name – Any chars, max 30 chars. Optional.
  • create_login_tokenoptional, if sent the response will also include a url that when visited will login the created user. Use this to allow users to login without explicitly setting their passwords. This URL expires in 2 hours
  • find_unique_usernameoptional, if username is taken, we will find a similar, unused, username for the new user. If passed, make sure you check the username returned since it might not be the same one that you passed in. If set, usernames can only be a maximum of 24 characters to make room for potential extra characters.
Response JSON Object:
 
  • username – username
  • first_name – First name
  • last_name – Last name
  • homepage – Homepage URL
  • biography – Bio text
  • num_videos – Number of videos created by the user
  • languages – List of languages the user speaks
  • avatar – URL to the user’s avatar image
  • resource_uri – User API URI
  • email – User’s email
  • api_key – User API Key
  • full_name – Full name

Note

This response includes the email and api_key, which aren’t included in the normal GET response. If clients wish to make requests on behalf of this newly created user through the api, they must hold on to this key.

Updating Your Account

PUT /api/users/[username]

Use PUT to update your user account. username must match the username of the auth credentials sent. PUT inputs the same fields as POST, except username, create_login_token, and find_unique_username.

Team Resource

Get a list of teams

GET /api/teams/

paginated

Response JSON Object:
 
  • name – Name of the team
  • slug – Machine name for the team slug (used in URLs)
  • description – Team description
  • is_visible – Should this team’s videos be publicly visible?
  • membership_policy – See below for possible values
  • video_policy – See below for possible values

Get a list of teams

GET /api/teams/[team-slug]/

Returns one entry from the team list resource data.

Updating a team

PUT /api/teams/[team-slug]:
Request JSON Object:
 
  • name – (required) Name of the team
  • slug – (required) Manchine name for the team (used in URLs)
  • description – Team description
  • is_visible – Should this team be publicly visible?
  • membership_policy – See below for possible values
  • video_policy – See below for possible values

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

Team Member Resource

Get info on a team member

GET /api/teams/[team-slug]/members/[username]
Request JSON Object:
 
  • username – username
  • role – One of: owner, admin, manager, or contributor

Litsing all team members

GET /api/teams/[team-slug]/members/

Returns a list of team member data. Each item is the same as above.

Add a new member to a team

POST /api/teams/[team-slug]/members/
Response JSON Object:
 
  • username – username of the user to add
  • role – One of: owner, admin, manager, or contributor

Change a team member’s role

PUT /api/teams/[team-slug]/members/[username]/
Response JSON Object:
 
  • role – One of: owner, admin, manager, or contributor

Removing a user from a team

DELETE /api/teams/[team-slug]/members/[username]/

Safe Team Member Resource

This resource behaves the same as the normal Team Member resource except with couple differences for the POST action to add members

  • An invitation is sent to the user to join the team instead of simply adding them
  • If no user exists with the username, and an email field is included in the POST data, we will create a user and send an email to the email account.

Project Resource

List a team’s projects

GET /api/teams/[team-slug]/projects/
Response JSON Array of Objects:
 
  • name – project name
  • slug – machine-name for the project
  • description – project description
  • guidelines – Project guidelines for users working on it
  • resource_uri – API URI for project details
  • created – datetime when the project was created
  • modified – datetime when the project was last changed
  • workflow_enabled – Are tasks enabled for this project?

Get details on a project

GET /api/teams/[team-slug]/projects/[project-slug]/

Returns the same data as the project list resource

Create a new project

POST /api/teams/[team-slug]/projects/
Request JSON Object:
 
  • name – project name
  • slug – machine-name for the project
  • description – project description (optional)
  • guidelines – Project guidelines for users working on it (optional)

Updating a project

PUT /api/teams/[team-slug]/projects/[project-slug]/

Inputs the same data is the create project resource

Delete a project

DELETE /api/teams/[team-slug]/projects/[project-slug]/

Task Resource

List all tasks for a given team

GET /api/teams/[team-slug]/tasks/
Query Parameters:
 
  • assignee – Show only tasks assigned to a username
  • priority – Show only tasks with a given priority
  • type – Show only tasks of a given type
  • video_id – Show only tasks that pertain to a given video
  • order_by

    Apply sorting to the task list. Possible values:

    • created Creation date
    • -created Creation date (descending)
    • priority Priority
    • -priority Priority (descending)
    • type Task type (details below)
    • -type Task type (descending)
  • completed – Show only complete tasks
  • completed-before – Show only tasks completed before a given date (unix timestamp)
  • completed-after – Show only tasks completed before a given date (unix timestamp)
  • open – Show only incomplete tasks
Response JSON Array of Objects:
 
  • video_id – ID of the video being worked on
  • language – Language code being worked on
  • id – ID for the task
  • type – type of task. One of Subtitle, Translate, Review, or Approve
  • assignee – username of the task assignee (or null)
  • priority – Integer priority for the task
  • completed – Date/time when the task was completed (or null)
  • approved – Approval status of the task. One of In Progress, Approved, or Rejected
  • resource_uri – API URL for the task

Task detail

GET /api/teams/[team-slug]/tasks/[task-id]/

Returns the same data as the task list API

Create a new task

POST /api/teams/[team-slug]/tasks/
Request JSON Object:
 
  • video_id – Video ID
  • language – language code
  • type – task type to create. Must be Subtitle or Translate
  • assignee – Username of the task assignee (optional)
  • priority – Priority for the task (optional)

Update an existing task

PUT /api/teams/[team-slug]/tasks/[task-id]/
Request JSON Object:
 
  • assignee – Username of the task assignee or null to unassign
  • priority – priority of the task
  • send_back – send a truthy value to send the back back (optional)
  • complete – send a truthy value to complete/approve the task (optional)
  • version_number – Specify the version number of the subtitles that were created for this task (optional)

Note

If both send_back and approved are specified, then send_back will take preference.

Delete an existing task

DELETE /api/teams/[team-slug]/tasks/[task-id]/

Team Applications resource

For teams with membership by application only.

List applications

GET /api/teams/[team-slug]/applications

paginated

Query Parameters:
 
  • status – Include only applications with this status
  • integer before (timestamp) – Include only applications submitted before this time.
  • after (timestamp) – Include only applications submitted after this time.
  • user (username) – Include only applications from this user
Response JSON Array of Objects:
 
  • user – Username of the applicant
  • note – note given by the applicant
  • status – status value. Possible values are Denied, Approved, Pending, Member Removed and Member Left
  • id – application ID
  • created – creation date/time
  • modified – last modified date/time
  • resource_uri – API URI for the application

Get details on a single application

GET /api/teams/[team-slug]/applications/[application-id]/:

Returns the same data as one entry from the listing endpoint.

Approve/Deny an application

PUT /api/teams/[team-slug]/applications/[application-id]/
Request JSON Object:
 
  • statusDenied to deny the application and Approved to approve it.

Activity Resource

This resource is read-only.

List activity items:

GET /api/activity/

paginated

Query Parameters:
 
  • team (slug) – Show only items related to a given team
  • team-activity – If team is given, we normally return activity on the team’s videos. If you want to see activity for the team itself (members joining/leaving and team video deletions, then add team-activity=1)
  • video (video-id) – Show only items related to a given video
  • type (integer) – Show only items with a given activity type (see below for values)
  • language (language-code) – Show only items with a given language
  • before (integer) – A unix timestamp in seconds
  • after (integer) – A unix timestamp in seconds
Response JSON Array of Objects:
 
  • type – activity type as an integer
  • created – date/time of the activity
  • video – ID of the video
  • video_uri – API URI for the video
  • language – language for the activity
  • language_url – API URI for the video language
  • resource_uri – API URI for the activity
  • user – username of the user user associated with the activity, or null
  • comment – comment body for comment activity, null for other types
  • new_video_title – new title for the title-change activity, null for other types
  • id – object id (deprecated use resource_uri if you need to get details on a particular activity)

Note

If both team and video are given as GET params, then team will be used and video will be ignored.

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:

GET /api/activity/[activity-id]/

Returns the same data as one entry from the listing.

Message Resource

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

POST /api/message/
Request JSON Object:
 
  • user – Recipient User’s username
  • team – Recipient Team’s slug
  • subject – Subject of the message
  • content – Content of the message