API Documentation

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

Overview

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 https://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 https://amara.org/api/videos/

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

GET https://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 https://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 https://amara.org/api/videos/?order_by=title

To create a video you can use

POST https://amara.org/api/videos/

To update the video with video id foo use:

PUT https://amara.org/api/videos/foo

API Changes / Versioning

Sometimes we need to make backwards incompatible changes to the API. Here’s our system for allowing our partners and other API consumers to deal with them:

  • All changes are announced on the Amara Development Blog and the API Changes mailing list.
  • When we make a change, we give clients between six weeks and three months of transition time, depending on the complexity of the changes, to update their code to work with the new system.
  • During the transition time, we return an HTTP header to indicate that the API will be changing. The name is X-API-DEPRECATED and the value is the date the API will change in YYYYMMDD format.
  • Clients can start using the new API during the transition time by sending the X-API-FUTURE header. The value should be the date of the API that you want to use, also in YYYYMMDD format. If the X-API-FUTURE date is >= the switchover date then the new API code will be used.
  • You can use X-API-FUTURE to test changes to your API client code and to deploy new code that works with the updated API. Using this method you can ensure your integration works seamlessly through the API change.
  • If you aren’t able to change your request headers, then you can also use the api-future query parameter (for example /api/videos/?api-future=20151021)

Languages

Languages Resource

API endpoint that lists all available languages on the Amara platform.

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

Videos

Videos Resource

List/Search/Lookup videos on Amara

Listing Videos

GET /api/videos/

List videos. You probably want to specify a query filter parameter to limit the results

List results are paginated.

Query Parameters:
 
  • video_url (url) – Filter by video URL
  • team (slug) – Filter by team. Passing in null will return only videos that are in the public area.
  • project (slug) – Filter by team project. Passing in null will return only videos that don’t belong to a project
  • order_by (string) –

    Change the list ordering. Possible values:

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

Note

  • If no query parameter is given, the last 10 public videos are listed.
  • If you pass in the project filter, you need to pass in a team

Get info on a specific video

GET /api/videos/(video-id)/
Response JSON Object:
 
  • id (video-id) – Amara video id
  • primary_audio_language_code (bcp-47) – Audio language code
  • title (string) – Video title
  • description (string) – Video description
  • duration (integer) – Video duration in seconds (or null if not known)
  • thumbnail (url) – URL to the video thumbnail
  • created (iso-8601) – Video creation date/time
  • team (slug) – Slug of the Video’s team (or null)
  • metadata (dict) – Dict mapping metadata names to values
  • languages (list) – List of languages that have subtitles started. See below for a a description.
  • video_type (char) – Video type identifier
  • all_urls (list) – List of URLs for the video (the first one is the primary video URL)
  • activity_uri (uri) – Video Activity Resource
  • urls_uri (url) – Video URL Resource
  • subtitle_languages_uri (uri) – Subtitle languages Resource
  • resource_uri (uri) – Video Resource
  • original_language (string) – contains a copy of primary_audio_language_code (deprecated)

Language data:

Response JSON Object:
 
  • code (string) – Language code
  • name (string) – Human readable label for the language
  • published (boolean) – Are the subtitles publicly viewable?
  • dir (string) – Language direction (“ltr” or “rtl”)
  • subtitles_uri (url) – Subtitles Resource
  • resource_uri (url) – Subtitles Language Resource

Adding a video

POST /api/videos/
Request JSON Object:
 
  • video_url (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)
  • title (string) – title of the video
  • description (string) – About this video
  • duration (integer) – Duration in seconds, in case it can not be retrieved automatically by Amara
  • primary_audio_language_code (string) – language code for the main language spoken in the video.
  • thumbnail (url) – URL to the video thumbnail
  • metadata (dict) – 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 (string) – team slug for the video or null to remove it from its team.
  • project (string) – project slug for the video or null to put it in the default project.

Note

  • 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 (except the video duration) override any information from the original provider or the file header.
  • 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 (deprecated).

Update an existing video

PUT /api/videos/(video-id)/

This uses the same fields as video creation, excluding video_url.

As with creating video, an update can not override the duration received from the provider or specified in the file header.

Delete an existing video

DELETE /api/videos/(video-id)/

This deletes a video.

If there are any subtitles/collaborations on the video, they will also be deleted.

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. team must also be given in this case.
  • 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.

Video URL Resource

Each video has at least 1 URL associated with it, but some can have more. This allows you to associate subtitles with the video on multiple video providers (e.g. a youtube version, a vimeo version, etc).

One video URL is flagged the primary URL. This is what will gets used in the embedder and editor.

List URLs for a video

GET /api/videos/(video-id)/urls/

List results are paginated.

Response JSON Object:
 
  • video-id (string) – Amara video ID
  • created (iso-8601) – creation date/time
  • url (url) – URL string
  • primary (boolean) – is this the primary URL for the video?
  • original (boolean) – was this the URL that was created with the video?
  • resource_uri (uri) – Video URL Resource
  • videoid (string) – ID on the Hosting platform
  • type (string) – Video type (Youtube, Vimeo, HTML5, etc.)
  • id (integer) – Internal ID for the object (deprecated, use resource_uri rather than trying to construct API URLs yourself).

Get details on a specific URL

GET (video-url-endpoint)

The response fields are the same as for the list endpoint

Use the resource_uri from the listing to find the video URL endpoint

Add a URL for a video

POST /api/videos/(video-id)/urls/
Request JSON Object:
 
  • url (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 (boolean) – If True, this URL will be made the primary URL
  • original (boolean) – Is this is the first url for the video?

Making a URL the primary URL for a video

PUT (video-url-endpoint)
Request JSON Object:
 
  • primary – Pass in true to make a video URL the primary for a video

Use the resource_uri from the listing to find the video URL endpoint

Deleting Video URLs

DELETE (video-url-endpoint)

Remove a video URL from a video

Use the resource_uri from the listing to find the video URL endpoint

Subtitles

Subtitle Language Resource

Container for subtitles in one language for a video. Subtitle languages are typically created when the first editing session is started.

To see all possible languages see Supported languages.

Listing languages for a video

GET /api/videos/(video-id)/languages/

Get a list of subtitle languages for a video

List results are paginated.

Response JSON Object:
 
  • language_code (bcp-47) – Subtitle language
  • name (string) – Human-readable name for this language
  • is_primary_audio_language (boolean) – Is this language the primary language spoken in the video?
  • is_rtl (boolean) – Is this language RTL?
  • resource_uri (uri) – Subtitle Language Resource
  • created (iso-8601) – when the language was created
  • title (string) – Video title, translated into this language
  • description (string) – Video description, translated into this language
  • metadata (dict) – Video metadata, translated into this language
  • subtitles_complete (boolean) – Are the subtitles complete for this language?
  • subtitle_count (integer) – Number of subtitles for this language
  • reviewer (string) – Username of the reviewer for task-based teams
  • approver (string) – Username of the approver for task-based teams
  • is_translation (boolean) – Is this language translated from other languages? (deprecated)
  • published (boolean) – Are the subtitles publicly viewable?
  • original_language_code (string) – Source translation language (deprecated)
  • num_versions (integer) – Number of subtitle versions, the length of the versions array should be used instead of this (deprecated)
  • id (integer) – Internal ID for the language (deprecated)
  • is_original (boolean) – alias for is_primary_audio_language (deprecated)
  • versions (list) – List of subtitle version data. See below for details.

Subtitle version data:

Response JSON Object:
 
  • author (user-data) – Subtitle author (see User fields)
  • version_no (integer) – number of the version
  • published (boolean) – is this version publicly viewable?

Note

original_language_code and is_translation fields are remnants from the old subtitle system. With the new editor, users can use multiple languages as a translation source. These fields are should not be relied on.

Getting details on a specific language

GET /api/videos/(video-id)/languages/(language-code)/

The response data is the same as the listing

Creating subtitle languages

POST /api/videos/(video-id)/languages/
Request JSON Object:
 
  • language_code (string) – bcp-47 code for the language
  • is_primary_audio_language (boolean) – Is this the primary spoken language of the video? (optional).
  • subtitles_complete (boolean) – Are the subtitles for this language complete? (optional).
  • is_original (boolean) – Alias for is_primary_audio_language (deprecated)
  • is_complete (boolean) – Alias for subtitles_complete (deprecated)
  • soft_limit_lines (integer) – Controls the max number of lines per subtitle. A warning is shown in the editor if this limit is exceeded.
  • soft_limit_min_duration (integer) – Controls min duration of subtitles in milliseconds. A warning is shown in the editor if this limit is exceeded.
  • soft_limit_max_duration (integer) – Controls max duration of subtitles in milliseconds. This controls the message in the guidelines dialog.
  • soft_limit_cpl (integer) – Controls the max characters per line for subtitles. A warning is shown in the editor if this limit is exceeded.
  • soft_limit_cps (integer) – Controls the max characters per second for subtitles. A warning is shown in the editor if this limit is exceeded.

Updating subtitle languages

PUT /api/videos/(video-id)/languages/(language-code)/

The request data is the same as when creating languages, except language_code is not allowed.

Subtitles Resource

Subtitle data in one language for a video.

Fetching subtitles for a given language

GET /api/videos/(video-id)/languages/(language-code)/subtitles/
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. If you want the latest private version (and have access to it) use “last”.
  • version – Alias for version_number (deprecated)
Response JSON Object:
 
  • version_number (integer) – version number for the subtitles
  • subtitles (object) – Subtitle data. The format depends on the sub_format param
  • author (user-data) – Subtitle author (see User fields)
  • sub_format (string) – Format of the subtitles
  • language (object) – Language data
  • title (string) – Video title, translated into the subtitle’s language
  • description (string) – Video description, translated into the subtitle’s language
  • metadata (string) – Video metadata, translated into the subtitle’s language
  • video_title (string) – Video title, translated into the video’s language
  • video_description (string) – Video description, translated into the video’s language
  • notes_uri (uri) – Subtitle notes resource
  • actions_uri (uri) – Subtitle actions resource
  • resource_uri (uri) – Subtitles resource
  • site_uri (url) – URL to view the subtitles on site
  • video (string) – Copy of video_title (deprecated)
  • version_no (integer) – Copy of version_number (deprecated)

Language data:

Response JSON Object:
 
  • code (bcp-47) – Language of the subtitles
  • name (string) – Human-readable name for the language
  • dir (string) – Language direction (“ltr” or “rtl”)

Getting subtitle data only

Sometimes you want just subtitles data without the rest of the data. This is possible using a special Accept header or the format query parameter. 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/(video-id)/languages/(language-code)/subtitles/?format=dfxp

GET /api/videos/(video-id)/languages/(language-code)/subtitles/
Accept: application/ttml+xml

Creating new subtitles

POST /api/videos/(video-id)/languages/(language-code)/subtitles/
Request JSON Object:
 
  • subtitles (object) – The subtitles to submit, as a string. The format depends on the sub_format param.
  • subtitles_url (object) – Alternatively, subtitles can be given as a text file URL. The format depends on the sub_format param.
  • sub_format (string) – The format used to parse the subs. The same formats as for fetching subtitles are accepted. Optional - defaults to “dfxp”.
  • title (string) – Give a title to the new revision
  • description (string) – Give a description to the new revision
  • action (string) – Name of the action to perform - optional, but recommended. If given, the is_complete param will be ignored. For more details, see the subtitles action documentation by following the actions_uri field.
  • is_complete (boolean) – Boolean indicating if the complete subtitling set is available for this language - optional, defaults to false. (deprecated, use action instead)

Deleting subtitles

DELETE /api/videos/(video-id)/languages/(language-code)/subtitles/

This will delete all subtitle versions for a language. It’s only allowed if the video is part of a team and the API user is an admin for that team.

Subtitle Actions Resource

Subtitle 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 with adding new subtitles using the action field of the subtitles resource.

Listing actions

GET /api/videos/(video-id)/languages/(language-code)/subtitles/actions/

Get a list of possible actions for a subtitle set.

Response JSON Object:
 
  • action (string) – Action name
  • label (string) – Human-friendly string for the action
  • complete (boolean) – 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.

Performing actions

POST /api/videos/(video-id)/languages/(language-code)/subtitles/actions/

Perform an action on a subtitle set. This is like opening the subtitles in the editor, not changing anything, and clicking an action button (Publish, Save Draft, etc.)

Request JSON Object:
 
  • action (string) – name of the action to perform

Subtitle Notes Resource

Subtitle notes saved in the editor.

Note

Subtitle notes are currently only supported for team videos

Fetching notes

GET /api/videos/(video-id)/languages/(language-code)/subtitles/notes
Response JSON Object:
 
  • user (username) – Username of the note author
  • datetime (iso-8601) – when the note was created
  • body (string) – text of the note.

Adding notes

POST /api/videos/(video-id)/languages/(language-code)/subtitles/notes/
Request JSON Object:
 
  • body (string) – note body

Users

Users Resource

Fetching user data

GET /api/users/[identifier]/
Parameters:
Response JSON Object:
 
  • username (username) – username
  • id (string) – user ID
  • first_name (string) – First name
  • last_name (string) – Last name
  • homepage (url) – Homepage URL
  • biography (string) – Bio text
  • num_videos (integer) – Number of videos followed by the user
  • languages (list) – List of language codes for languages the user speaks.
  • avatar (url) – URL to the user’s avatar image
  • activity_uri (uri) – User Activity resource
  • resource_uri (uri) – User resource
  • full_name (string) – Full name of the user.

Note

  • Many of these fields will be blank if the user hasn’t set them from their profile page
  • 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 (email) – A valid email address
  • password (string) – any number of chars, all chars allowed.
  • first_name (string) – Any chars, max 30 chars. (optional)
  • last_name (string) – Any chars, max 30 chars. (optional)
  • allow_3rd_party_login (boolean) – If set, account can be automatically linked to 3rd party account at first login. (optional)
  • create_login_token (boolean) – 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. (optional)
  • find_unique_username (boolean) – 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. (optional)

Note

The 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 data.

Updating user accounts

PUT /api/users/[username]
Parameters:
  • username (username) – must match the username of the auth credentials sent

Inputs the same fields as POST, except username, password, and find_unique_username.

User Identifiers

There are a couple ways to specify users:

  • Username
  • User ID prefixed with “id$” (id$abcdef123)

The user ID method is preferred since it’s possible for users to change their username.

User fields

Users are often contained in other resources, for example the team members, subtitle authors, etc. When those users are represented, we use a dict with the following fields:

  • username – Username
  • id – User ID
  • uri – Link to the user API endpoint

Example JSON:

{
  "user": {
    "username": "alice",
    "id": "abcdef",
    "uri": "https://amara.org/api/users/id$abcdef/"
  }
}

When you post data to an endpoint with a userfield, you can specify the user using any of the identifiers listed abose. For example, to create a team member you can send this data:

{
  "user": "id$abcdef",
  "role": "manager"
}

Activity

Video Activity Resource

GET /api/videos/(video-id)/activity/
Query Parameters:
 
  • type (string) – Filter by activity type (Activity Types)
  • user (user-identifier) – Filter by user who performed the action (see User Identifiers)
  • language (bcp-47) – Filter by the subtitle language
  • before (iso-8601) – Only include activity before this date/time
  • after (iso-8601) – Only include activity after
Response JSON Object:
 
  • type (string) – Activity type (Activity Types)
  • date (iso-8601) – Date/time of the activity
  • user (user-data) – User who performed the activity (see User fields)
  • video (video-id) – Video related to the activity (or null)
  • language (bcp-47) – Language of the subtitles related to the activity (or null)
  • video_uri (uri) – Link to the video resource endpoint
  • language_uri (uri) – Link to the subtitle language resource endpoint

Depending on the activity type, extra fields may be present in the response data (Activity Types).

Team Activity Resource

GET /api/teams/(slug)/activity/
Query Parameters:
 
  • type (string) – Filter by activity type (Activity Types)
  • user (user-identifier) – Filter by user who performed the action (see User Identifiers)
  • video (video-id) – Filter by video
  • video_language (bcp-47) – Filter by video language
  • language (bcp-47) – Filter by the subtitle language
  • before (iso-8601) – Only include activity before this date/time
  • after (iso-8601) – Only include activity after

Response data is the same as the video activity resource.

User Activity Resource

GET /api/users/(username)/activity/
Query Parameters:
 
  • type (string) – Filter by activity type (Activity Types)
  • video (video-id) – Filter by video
  • video_language (bcp-47) – Filter by video language
  • language (bcp-47) – Filter by the subtitle language
  • team (slug) – Filter by team
  • before (iso-8601) – Only include activity before this date/time
  • after (iso-8601) – Only include activity after

Response data is the same as the video activity resource.

Activity Types

An activity type classifies the activity. Some types have extra data that is associated with them

Type Created When | Notes/Extra Fields
video-added Video added to amara  
comment-added Comment posted language will be null for video comments and set for subtitle comments
version-added Subtitle version added  
video-title-changed Video title changed  
video-url-added URL added to video url will contain the new URL
video-url-edited Primary video URL change old_url/new_url will contain the old/new primary URL
video-url-deleted URL removed from video url will contain the deleted URL
video-deleted Video deleted from amara title will contain the deleted video’s title
Team Related Activity
member-joined User joined team  
member-left User left team  
Task Related Activity
version-approved Subtitles approved  
version-rejected Subtitles sent back by approver  
version-accepted Subtitles approved by reviewer  
version-declined Subtitles sent back by reviewer  

Legacy Activity Resource

Deprecated API endpoint that lists contains all amara activity. You should use the team/video/user query param to find the activity you want. New code should use the Video, Team, or User, resources (see above).

List activity

GET /api/activity/
Query Parameters:
 
  • team (slug) – Show only items related to a given team
  • team-activity (boolean) – 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. Possible values:

    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
  • language (bcp-47) – Show only items with a given language code
  • before (timestamp) – Only include items before this time
  • after (timestamp) – Only include items after this time

Note

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

Get details on one activity item

GET /api/activity/[activity-id]/
Response JSON Object:
 
  • type (integer) – activity type. The values are listed above
  • date (datetime) – date/time of the activity
  • video (video-id) – ID of the video
  • video_uri (uri) – Video Resource
  • language (bcp-47) – language for the activity
  • language_url (uri) – Subtile Language Resource
  • resource_uri (uri) – Activity Resource
  • user (username) – username of the user user associated with the activity, or null
  • comment (string) – comment body for comment activity, null for other types
  • new_video_title (string) – new title for the title-change activity, null for other types
  • id (integer) – object id (deprecated use resource_uri if you need to get details on a particular activity)

Messages

Message Resource

POST /api/message/

Send a message to a user/team

Request JSON Object:
 
  • user (user-identifier) – Recipient (see User Identifiers)
  • team (slug) – Recipient team’s slug
  • subject (string) – Subject of the message
  • content (string) – Content of the message

Note

You can only send either user or team, not both.

Teams

Team Resource

Get a list of teams

GET /api/teams/

Get a paginated list of all teams

Response JSON Object:
 
  • name (string) – Name of the team
  • slug (slug) – Machine name for the team slug (used in URLs)
  • type (string) –

    Team type. Possible values:

    • default – default team type
    • simple – simplified workflow team
    • collaboration – collaboration team
  • description (string) – Team description
  • team_visibility (string) –

    Should non-team members be able to view the team? Possible values:

    • private – Only team members can view the team
    • unlisted – Team not listed in the directory, but publicly accessible for users with a link
    • public – Anyone can view the team (default)
  • video_visibility (string) –

    Should non-team members be able to view the team’s videos? Possible values:

    • private – Only team members can view the team’s videos
    • unlisted – The team’s videos not searchable, or listed in the directory, but publicly accessible for users with a link
    • public – Anyone can view the team’s videos (default)
  • is_visible (boolean) – Legacy visibility field. This will be True if team_visibility is public.
  • membership_policy (string) –

    Team membership policy. Possible values:

    • Open
    • Application
    • Invitation by any team member
    • Invitation by manager
    • Invitation by admin
  • video_policy (string) –

    Team video policy. Possible values:

    • Any team member
    • Managers and admins
    • Admins only
  • activity_uri (uri) – Team activity resource
  • members_uri (uri) – Team member list resource
  • projects_uri (uri) – Team projects resource
  • applications_uri (uri) – Team applications resource (or null if the membership policy is not by application)
  • languages_uri (uri) – Team preferred/blacklisted languages resource
  • tasks_uri (uri) – Team tasks resource (or null if tasks are not enabled)
  • resource_uri (uri) – Team resource
GET /api/teams/(team-slug)/

Get details on a single team

The data is the same as the list endpoint

Updating team settings

PUT /api/teams/(team-slug)
Request JSON Object:
 
  • name (string) – Name of the team
  • slug (slug) – Machine name for the team (used in URLs)
  • description (string) – Team description
  • team_visibility (string) –

    Should non-team members be able to view the team? Possible values:

    • private – Only team members can view the team
    • unlisted – Team not listed in the directory, but publicly accessible for users with a link
    • public – Anyone can view the team (default)
  • video_visibility (string) –

    Should non-team members be able to view the team’s videos? Possible values:

    • private – Only team members can view the team’s videos
    • unlisted – The team’s videos not searchable, or listed in the directory, but publicly accessible for users with a link
    • public – Anyone can view the team’s videos (default)
  • is_visible (boolean) – Legacy visibility field. If set to True, this will set both team_visibility and video_visibility to public. If set to False, it will set them both to private`. When reading this field, it is True if ``team_visibility is set to public
  • membership_policy (string) –

    Team membership policy. Possible values:

    • Open
    • Application
    • Invitation by any team member
    • Invitation by manager
    • Invitation by admin
  • video_policy (string) –

    Team video policy. Possible values:

    • Any team member
    • Managers and admins
    • Admins only

Creating a team

Amara partners can create teams via the API.

POST /api/teams/
Request JSON Object:
 
  • name (required) (string) – Name of the team
  • slug (required) (slug) – Machine name for the team (used in URLs)
  • type (required) (string) –

    Team type. Possible values:

    • default – default team type
    • simple – simplified workflow team
    • collaboration – collaboration team
  • description (string) – Team description
  • team_visibility (string) –

    Should non-team members be able to view the team? Possible values:

    • private – Only team members can view the team
    • unlisted – Team not listed in the directory, but publicly accessible for users with a link
    • public – Anyone can view the team (default)
  • video_visibility (string) –

    Should non-team members be able to view the team’s videos? Possible values:

    • private – Only team members can view the team’s videos
    • unlisted – The team’s videos not searchable, or listed in the directory, but publicly accessible for users with a link
    • public – Anyone can view the team’s videos (default)
  • is_visible (boolean) – Legacy visibility field. If set to True, this will set both team_visibility and video_visibility to public. If set to False, it will set them both to private`. When reading this field, it is True if ``team_visibility is set to public
  • membership_policy (string) –

    Team membership policy. Possible values:

    • Open
    • Application
    • Invitation by any team member
    • Invitation by manager
    • Invitation by admin
  • video_policy (string) –

    Team video policy. Possible values:

    • Any team member
    • Managers and admins
    • Admins only

Members Resource

API endpoint for team memberships

Listing members of a team

GET /api/teams/(team-slug)/members/
Response JSON Object:
 
  • user (user) – User associated with the membership (see User fields)
  • role (string) – Possible values: owner, admin, manager, or contributor

Get info on a team member

GET /api/teams/(team-slug)/members/(user-identifier)/

The data is in the same format as the listing endpoint.

See User Identifiers for possible values for user-identifier

Adding a member to the team

POST /api/teams/(team-slug)/members/
Request JSON Object:
 
  • user (user-identifier) – User to add (see User Identifiers)
  • role (string) – Possible values: owner, admin, manager, or contributor

Change a team member’s role

PUT /api/teams/(team-slug)/members/(username)/
Request JSON Object:
 
  • role (string) – Possible values: owner, admin, manager, or contributor

Removing a user from a team

DELETE /api/teams/(team-slug)/members/(username)/

Projects Resource

List a team’s projects

GET /api/teams/(team-slug)/projects/
Response JSON Object:
 
  • name (string) – project name
  • slug (slug) – slug for the project
  • description (string) – project description
  • guidelines (string) – Project guidelines for users working on it
  • created (datetime) – datetime when the project was created
  • modified (datetime) – datetime when the project was last changed
  • workflow_enabled (boolean) – Are tasks enabled for this project?
  • resource_uri (uri) – Project details resource

Get details on a project

GET /api/teams/(team-slug)/projects/(project-slug)/

The data is the same as the listing endpoint

Creating a project

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

Updating a project

PUT /api/teams/(team-slug)/projects/(project-slug)/

Uses the same data as the POST method

Delete a project

DELETE /api/teams/(team-slug)/projects/(project-slug)/

Tasks Resource

List all tasks for a team

GET /api/teams/(team-slug)/tasks/
Query Parameters:
 
  • assignee (user-identifier) – Show only tasks assigned to a username (see User Identifiers)
  • priority (integer) – Show only tasks with a given priority
  • type (string) – Show only tasks of a given type
  • video_id (video-id) – Show only tasks that pertain to a given video
  • order_by (string) –

    Apply sorting to the task list. Possible values:

    • created Creation date
    • -created Creation date (descending)
    • modified Last update date
    • -modified Last update date (descending)
    • priority Priority
    • -priority Priority (descending)
    • type Task type (details below)
    • -type Task type (descending)
  • completed (boolean) – Show only complete tasks
  • completed-before (integer) – Show only tasks completed before a given date (as a unix timestamp)
  • completed-after (integer) – Show only tasks completed before a given date (as a unix timestamp)
  • open (boolean) – Show only incomplete tasks

Get details on a specific task

GET /api/teams/(team-slug)/tasks/(task-id)/
Response JSON Object:
 
  • video_id (video-id) – ID of the video being worked on
  • language (bcp-47) – Language code being worked on
  • id (integer) – ID for the task
  • type (string) – type of task. Possible values: Subtitle, Translate, Review, or Approve
  • assignee (user-data) – Task assignee (see User fields)
  • priority (integer) – Priority for the task
  • created (datetime) – Date/time when the task was created
  • modified (datetime) – Date/time when the task was last updated
  • completed (datetime) – Date/time when the task was completed (or null)
  • approved (string) – Approval status of the task. Possible values: In Progress, Approved, or Rejected
  • resource_uri – Task resource

Create a new task

POST /api/teams/(team-slug)/tasks/
Request JSON Object:
 
  • video_id (video-id) – Video ID
  • language (bcp-47) – language code
  • type (string) – task type to create. Must be Subtitle or Translate
  • assignee (user-identifier) – Task assignee (User Identifiers)
  • priority (integer) – Priority for the task (optional)

Update an existing task

PUT /api/teams/(team-slug)/tasks/(task-id)/
Request JSON Object:
 
  • assignee (user-identifier) – Task assignee (User Identifiers)
  • priority (integer) – priority of the task
  • send_back (boolean) – send a truthy value to send the back back (optional)
  • complete (boolean) – send a truthy value to complete/approve the task (optional)
  • version_number (integer) – 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)/

Notifications Resource

This endpoint can be used to view notifications sent to your team. See HTTP Callbacks for Teams for details on how to set up notifications.

List notifications

GET /api/teams/(team-slug)/notifications/
Response JSON Object:
 
  • number (integer) – Notification number
  • url (url) – URL of the POST request
  • data (object) – Data that we posted to the URL.
  • timestamp (iso-8601) – date/time the notification was sent
  • in_progress (boolean) – Is the request still in progress?
  • response_status (integer) – HTTP response status code (or null)
  • error_message (string) – String describing any errors that occured
  • resource_uri (uri) – Link to the details endpoint for the notification

List results are paginated

Get details for a notification

GET /api/teams/(team-slug)/notifications/(number)/

This returns information on a single notification. The data has the same format as in the listing endpoint.

Applications Resource

This endpoint only works for teams with membership by application.

List applications

GET /api/teams/(team-slug)/applications
Query Parameters:
 
  • status (string) – Include only applications with this status
  • before (integer) – Include only applications submitted before this time (as a unix timestamp)
  • after (integer) – Include only applications submitted after this time (as a unix timestamp)
  • user (user-identifier) – Include only applications from this user (see User Identifiers)

List results are paginated

Get details on a single application

GET /api/teams/(team-slug)/applications/(application-id)/:
Response JSON Object:
 
  • user (user-data) – Applicant user data (see User fields)
  • note (string) – note given by the applicant
  • status (string) – status value. Possible values are Denied, Approved, Pending, Member Removed and Member Left
  • id (integer) – application ID
  • created (datetime) – creation date/time
  • modified (datetime) – last modified date/time
  • resource_uri (uri) – Application resource

Approve/Deny an application

PUT /api/teams/(team-slug)/applications/(application-id)/
Request JSON Object:
 
  • status (string) – Denied to deny the application and Approved to approve it.

Preferred Languages Resource

Preferred languages will have tasks auto-created for each video.

PUT /api/teams/(team-slug)/languages/preferred/

Send a list of language codes as data.

Blacklisted Languages Resource

Subtitles for blacklisted languages will not be allowed.

PUT /api/teams/(team-slug)/languages/blacklisted/

Send a list of language codes as data.

Subtitle Request Resource

This API endpoint is used for subtitle requests for teams new team that use the collaboration model.

Subtitle requests are extremely flexible and can involve multiple teams working together on a request. This section describes the simple case where only a single team is involved.

This section describes a simplified version of the subtitle request API, leaving out functionality that’s only needed for multi-team requests. See the next section for the full API.

Listing Requests

GET /api/teams/(team-slug)/subtitle-requests/
Query Parameters:
 
  • work_status (string) –

    Filter by the status of work on the subtitles. Possible values:

    • in-progress – work in progress
    • available – assignment currently available
    • assigned – assignment in progress
    • needs-subtitler – transcribe/translate assignment available
    • being-subtitled – transcribe/translate assignment in progress
    • needs-reviewer – review assignment available
    • being-reviewed – review assignment in progress
    • needs-approver – approval assignment available
    • being-approved – approval assignment in progress
    • complete – work complete
  • video (video-id) – Filter by video ID
  • video_title (string) – Filter by video title
  • video_language (bcp-47) – Filter by video language
  • language (bcp-47) – Filter by subtitle request language
  • project (slug) – Filter by team project
  • assignee (username) – Filter by assignee
  • sort (string) –

    Sort order. Possible values:

    • -creation (default) – creation date/time (latest first)
    • creation – creation date/time (earliest first)
    • -due – due date/time (latest first)
    • due – due date/time (earliest first)
    • -completion – latest completion date/time (latest first)
    • completion – latest completion date/time (earliest first)
Response JSON Object:
 
  • job_id (job-id) – ID for the request
  • video (video-id) – Video for the request
  • language (bcp-47) – Language code of the subtitle request
  • work_status (string) –

    Status of work on the subtitles. Possible values:

    • needs-subtitler – transcribe/translate assignment available
    • being-subtitled – transcribe/translate assignment in progress
    • needs-reviewer – review assignment available
    • being-reviewed – review assignment in progress
    • needs-approver – approval assignment available
    • being-approved – approval assignment in progress
    • complete – work complete
  • created (datetime) – when the request was created.
  • work_completed (datetime) – when the subittle work was completed, or null.
  • subtitler (user) – user creating the subtitles (see User fields)
  • reviewer (user) – user reviewing the subtitles (see User fields).
  • approver (user) – user approving the subtitles (see User fields).
  • video_uri (uri) – Video API resource
  • subtitles_uri (uri) – Subtitles resource
  • actions_uri (uri) – Subtitle actions resource
  • resource_uri (uri) – Subtitle request details resource

List results are paginated.

Request Details

GET /api/teams/(team-slug)/subtitle-requests/(job-id)/

Response data is the same as above.

Creating Requests

POST /api/teams/(team-slug)/subtitle-requests/
Request JSON Object:
 
  • video (video-id) – Video ID. This must be part of the team identified in the URL path
  • language (bcp-47) – language code for the subtitles

The API user must be an admin of the team to create a subtitle request.

Updating Requests

PUT /api/teams/(team-slug)/subtitle-requests/(job-id)/
Request JSON Object:
 
  • subtitler (user) – User to assign as the subtitler, or null to unassign the current subtitler (see User Identifiers).
  • reviewer (user) – User to assign as the reviewer, or null to unassign the current reviewer (see User Identifiers).
  • approver (user) – User to assign as the approver, or null to unassign the current approver (see User Identifiers).
  • work_status (string) – Set to “complete” to mark the subtitles complete. This is the only value we currently support.

Deleting Requests

DELETE /api/teams/(team-slug)/subtitle-requests/(job-id)/

Examples:

Assigning a user:

PUT /api/teams/my-team/subtitle-requests/abc123/

{
    "subtitler": "alice"
}

Unassigning a user:

PUT /api/teams/my-team/subtitle-requests/abc123/

{
    "subtitler": null
}

Marking a subtitle request complete

PUT /api/teams/my-team/subtitle-requests/abc123/

{
    "work_status": "complete"
}

Endorsing Subtitles

If you have an assignment, you can use the Subtitles Resource to submit subtitles. Use the endorse action to endorse them, moving the request to the next stage. You can also use the Subtitle Actions Resource to endorse the subtitles without submiting any changes.

Subtitle Request Resource (Multiple Teams)

This API endpoint is used for subtitle requests for teams new team that use the collaboration model.

Subtitle requests are extremely flexible and can involve multiple teams working together on a request. This section describes the complex cases where multiple teams handle a request together.

This section starts with some general concepts for multi-team requests, then describes the full subtitle request API.

Team Terminology

Several teams can be involved in a subtitle request. We use these terms to distinguish the teams:

  • source team – Team that owns the video.
  • work team – Team that is creating the subtitles. We say this team does the initial work to differentiate it from the evaluations.
  • evaulation teams – Teams that are checking the work of the work team. Each request can have 0-3 evaluation teams.
  • Note that the source team may also be the work team or an evaluation team for a request.

All subtitle request endpoints are contained inside /api/teams/(team-slug)/subtitle-requests/. When the docs say something like “source team only”, it refers to the team corresponding to (team-slug) in the URL.

Request Status Fields

The main concept to understand for multi-team requests is we use several status fields for the requests: status, work_status, and evaluation_status. The status field that we return depends on the team’s relationship to the request This gives each team a different view of the request. Each team gets the details revelant to it’s work, but not details about the work being done by other teams.

As an example, consider a request that has 2 evaluation teams. As the request progresses, here are the values that we will return for the various status fields:

status work_status evaluation_status (team1) evaluation_status (team2)
in-progress needs-subtitler pending pending
in-progress being-subtitled pending pending
in-progress needs-reviewer pending pending
in-progress being-reviewed pending pending
in-progress needs-approver pending pending
in-progress being-approved pending pending
in-evaluation1 complete available pending
in-evaluation1 complete assigned pending
in-evaluation2 complete complete available
in-evaluation2 complete complete assigned
complete complete complete complete
  • status will be returned to the source team
  • work_status will be returned to the work team
  • evaluation_status will be returned to evaluation teams
  • If the source team is also the work or evaluation team, then it will see multiple status fields.
  • status, work_status, and evaluation_status are also available as filters to use when listing requests.

Listing Requests

GET /api/teams/(team-slug)/subtitle-requests/
Query Parameters:
 
  • type (string) –

    Type of request. Possible values:

    • local (default) – The simple case, requests where the team is both the source and work team.
    • outgoing – Request where the team is the source team, but not the work team.
    • incoming – Request where the team is the work team, but not the source team.
    • evaluations – Request where the team is the evaluation team.
  • status (string) –

    (source team only) Filter by overall status. Possible values:

    • in-progress – initial work in progress
    • in-evaluation – evaluation in progress
    • in-evaluation1 – 1st evaluation in progress
    • in-evaluation2 – 2nd evaluation in progress
    • in-evaluation[N] – Nth evaluation in progress
    • complete – all work complete
  • work_status (string) –

    (work team only) Filter by status of the intial work (not including evaluations).

    • in-progress – initial work in progress
    • available – assignment currently available
    • assigned – assignment in progress
    • needs-subtitler – transcribe/translate assignment available
    • being-subtitled – transcribe/translate assignment in progress
    • needs-reviewer – review assignment available
    • being-reviewed – review assignment in progress
    • needs-approver – approval assignment available
    • being-approved – approval assignment in progress
    • complete – initial work complete
  • evaluation_status (string) –

    (evaluation teams only) Filter by status of the evaluation. Possible values:

    • upcoming – evaluation not ready to be started
    • in-progress – evaluation in progress
    • available – evaluation assignment currently available
    • assigned – evaluation assignment in progress
    • complete – evaluation complete
  • video (video-id) – Filter by video ID
  • video_title (string) – Filter by video title
  • video_language (bcp-47) – Filter by video language
  • language (bcp-47) – Filter by subtitle request language
  • project (slug) – Filter by team project
  • assignee (username) – Filter by assignee
  • sort (string) –

    Sort order. Possible values:

    • -creation (default) – creation date/time (latest first)
    • creation – creation date/time (earliest first)
    • -due – due date/time (latest first)
    • due – due date/time (earliest first)
    • -completion – latest completion date/time (latest first)
    • completion – latest completion date/time (earliest first)
Response JSON Object:
 
  • job_id (job-id) – ID for the request
  • video (video-id) – Video for the request
  • language (bcp-47) – Language code of the subtitle request
  • source_team (slug) – Team that the video is part of
  • team (slug) – Team handling the request (source team only)
  • evaluation_teams (slug-list) – Team evaluating the request. Only present for requests for the team’s videos.
  • status (string) –

    (source team only) Overall request status. Possible values:

    • in-progress – initial work in progress
    • in-evaluation1 – 1st evaluation in progress
    • in-evaluation2 – 2nd evaluation in progress
    • in-evaluation[N] – Nth evaluation in progress
    • complete – all work complete
  • work_status (string) –

    (work team only) Status of the intial work (not including evaluations). Possible values:

    • needs-subtitler – transcribe/translate assignment available
    • being-subtitled – transcribe/translate assignment in progress
    • needs-reviewer – review assignment available
    • being-reviewed – review assignment in progress
    • needs-approver – approval assignment available
    • being-approved – approval assignment in progress
    • complete – initial work complete
  • evaluation_status (string) –

    (evaluation teams only) Status of the evaluation. Possible values:

    • upcoming – evaluation not ready to be started
    • available – evaluation assignment currently available
    • assigned – evaluation assignment in progress
    • complete – evaluation complete
  • created (datetime) – when the request was created.
  • completed (datetime) – (source team only) when the entire request was completed, or null.
  • work_completed (datetime) – (work team only) when the initial work was completed, or null.
  • evaluation_completed (datetime) – (evaluation team only) when the initial work was completed, or null.
  • subtitler (user) – (work team only) user creating the subtitles (see User fields)
  • reviewer (user) – (work team only) user reviewing the subtitles (see User fields).
  • approver (user) – (work team only) user approving the subtitles (see User fields).
  • evaluator (user) – (evaluation teams only) user evaluating the subtitles (see User fields).
  • video_uri (uri) – Video API resource
  • subtitles_uri (uri) – Subtitles resource
  • actions_uri (uri) – Subtitle actions resource
  • resource_uri (uri) – Subtitle request details resource

List results are paginated.

Request Details

GET /api/teams/(team-slug)/subtitle-requests/(job-id)/

Response data is the same as above.

Creating Requests

POST /api/teams/(team-slug)/subtitle-requests/
Request JSON Object:
 
  • video (video-id) – Video ID. This must be part of the team identified in the URL path
  • language (bcp-47) – language code for the subtitles
  • team (slug) – Team to work on the subtitles. This can be any team you are an admin of. (optional, defaults to the team the video is a part of.)
  • evaluation_teams (list-of-slugs) – Teams to evaluate the subtitles after the initial work is done. They can be any team you are an admin of. (optional)

The API user must be an admin of the source team to create a subtitle request.

Updating Requests

PUT /api/teams/(team-slug)/subtitle-requests/(job-id)/
Request JSON Object:
 
  • subtitler (user) – (work team only) User to assign as the subtitler, or null to unassign the current subtitler (see User Identifiers).
  • reviewer (user) – (work team only) User to assign as the reviewer, or null to unassign the current reviewer (see User Identifiers).
  • approver (user) – (work team only) User to assign as the approver, or null to unassign the current approver (see User Identifiers).
  • work_status (string) – (work team only) Set to “complete” to mark the subtitles complete. This is the only value we currently support.
  • team (slug) – (source team only) Change the team working on the subtitle request. This is only possible if work has not been started.
  • evaluation_teams (slug) – (source team only) Change the teams evaluating on the subtitle request. This is only possible if evaluations have not been started.
  • evaluator (user) – (evaluation teams only) User to assign as the evaluator, or null to unassign the current evaluator (see User Identifiers).

Deleting Requests

DELETE /api/teams/(team-slug)/subtitle-requests/(job-id)/