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.

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

Endpoint Documentation

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
  • 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
  • visibile (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.

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
  • 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 fro task-based teams
  • approver (string) – Username of the approver for task-based teams
  • is_translation (boolean) – Is this language translated from other languages? (deprecated)
  • 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 (string) – Subtitle author’s username
  • 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 is 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)

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
  • 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 headers 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. 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)

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/[username]/
Response JSON Object:
 
  • username (username) – username
  • 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)
  • 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 and find_unique_username.

Activity

Video Activity Resource

GET /api/videos/(video-id)/activity/
Query Parameters:
 
  • type (string) – Filter by activity type (Activity Types)
  • user (string) – Filter by user who performed the action
  • 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 (username) – User who performed the activity
  • video (video-id) – Video related to the activity (or null)
  • language (bcp-47) – Language of the subtitles related to the activity (or null)
  • user_uri (uri) – Link to the user resource endpoint
  • 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 (string) – Filter by user who performed the action
  • 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-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

Response JSON Object:
 
  • user (username) – Recipient User’s username
  • 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)
  • description (string) – Team description
  • is_visible (boolean) – Should this team’s videos be publicly visible?
  • membership_policy (string) –

    Team membership policy. One of:

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

    Team video policy. One of:

    • Any team member
    • Managers and admins
    • Admins only
  • activity_uri (uri) – Team activity resource
  • members_uri (uri) – Team member list resource
  • safe_members_uri (uri) – “Safe” team members 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) – (required) Name of the team
  • slug (slug) – (required) Manchine name for the team (used in URLs)
  • description (string) – Team description
  • is_visible (boolean) – Should this team be publicly visible?
  • membership_policy (string) –

    Team membership policy. One of:

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

    Team video policy. One of:

    • 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:
 
  • username (username) – username
  • role (string) – One of: owner, admin, manager, or contributor

Get info on a team member

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

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

Adding a member to the team

POST /api/teams/(team-slug)/members/
Request JSON Object:
 
  • username (username) – username of the user to add
  • role (string) – One of: owner, admin, manager, or contributor

Change a team member’s role

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

Removing a user from a team

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

Safe Members 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 the email field is included in the POST data, we will create a user and send an email to the email account.

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 (username) – Show only tasks assigned to a username
  • 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)
    • 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. One of Subtitle, Translate, Review, or Approve
  • assignee (username) – username of the task assignee (or null)
  • priority (integer) – Priority for the task
  • created (datetime) – Date/time when the task was created
  • completed (datetime) – Date/time when the task was completed (or null)
  • approved (string) – Approval status of the task. One of 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 (username) – Username of the task assignee (optional)
  • priority (integer) – Priority for the task (optional)

Update an existing task

PUT /api/teams/(team-slug)/tasks/(task-id)/
Request JSON Object:
 
  • assignee (username) – Username of the task assignee or null to unassign
  • 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)/

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 (username) – Include only applications from this user

List results are paginated

Get details on a single application

GET /api/teams/(team-slug)/applications/(application-id)/:
Response JSON Object:
 
  • user (username) – Username of the applicant
  • 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. At this point it’s only used by a limited number of teams, but we hope to make it available to everyone in the near future.

Listing Requests

GET /api/teams/(team-slug)/subtitle-requests/
Query Parameters:
 
  • state (string) – Filter by state. This can be any valid state value (see below), or in-progress meaning any state except complete.
  • video (video-id) – Filter by video
  • video_language (bcp-47) – Filter by video request language
  • language (bc4-47) – Filter by subtitle request language
  • project (slug) – Filter by project
  • assignee (username) – Filter by username
Response JSON Object:
 
  • job_id (job-id) – ID for the request
  • team (slug) – Team handling the request
  • video (video-id) – Video for the request
  • language (bcp-47) – Language code of the subtitle request
  • state (string) –

    current state of the request. One of:

    • needs-subtitler
    • being-subtitled
    • needs-reviewer
    • being-reviewed
    • needs-approver
    • being-approved
    • complete
  • created (datetime) – when the request was created
  • completed (datetime) – when the request was completed, or null
  • resource_uri (uri) – Subtitle request details resource

Request Details

GET /api/subtitle-requests/(job-id)/
Response JSON Object:
 
  • job_id (job-id) – ID for the request
  • team (slug) – Team handling the request
  • video (video-id) – Video for the request
  • language (bcp-47) – Language code of the subtitle request
  • state (string) –

    current state of the request. One of:

    • needs-subtitler
    • being-subtitled
    • needs-reviewer
    • being-reviewed
    • needs-approver
    • being-approved
    • complete
  • created (datetime) – when the request was created
  • completed (datetime) – when the request was completed, or null
  • subtitler (username) – user creating the subtitles
  • reviewer (username) – user reviewing the subtitles
  • approver (username) – user approving the subtitles
  • video_uri (uri) – Video API resource
  • subtitler_uri (uri) – User resource for the subtitler
  • reviewer_uri (uri) – User resource for the reviewer
  • approver_uri (uri) – User resource for the approver
  • subtitles_uri (uri) – Subtitles resource
  • actions_uri (uri) – Subtitle actions resource
  • resource_uri (uri) – Subtitle request details resource
  • Results are ordered by creation time
  • List results are paginated.

Note

Depending on the team settings, there may or may not be a reviewer/approver working on a request.

Listing Remote Requests

Remote requests are requests for videos on your team, but being handled by a different team.

Note

The API providers less details on remote requests, since another team is responsible for them. In particular, the state field is much more granular and there is no link to the details URI.

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

    Filter by state. This can be:

    • complete – subtitles complete
    • in-progress – subtitles still being worked on
  • video (video-id) – Filter by video
  • video_language (bcp-47) – Filter by video request language
  • language (bc4-47) – Filter by subtitle request language
  • project (slug) – Filter by project
Response JSON Object:
 
  • job_id (job-id) – ID for the request
  • team (slug) – Team handling the request
  • video (video-id) – Video for the request
  • language (bcp-47) – Language code of the subtitle request
  • state (string) –

    current state of the request. One of:

    • complete
    • in-progress
  • created (datetime) – when the request was created
  • completed (datetime) – when the request was completed, or null

Creating Requests

POST /api/subtitle-requests/
Request JSON Object:
 
  • video (video-id) – Video ID. This must be part of a team that you are an admin for.
  • 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)

Updating Requests

PUT /api/subtitle-requests/(job-id)/
Request JSON Object:
 
  • subtitler (username) – Username to assign as the subtitler, or null to unassign the current subtitler
  • reviewer (username) – Username to assign as the reviewer, or null to unassign the current reviewer
  • approver (username) – Username to assign as the approver, or null to unassign the current approver
  • team (slug) – Change the team working on the subtitle request. This is only possible if work has not been started.
  • state (string) – Change the state of the subtitler request. The only valid value is “complete” which marks the subtitle request complete.

Assigning a user:

PUT /api/subtitle-requests/abc123/

{
    "subtitler": "alice"
}

Unassigning a user:

PUT /api/subtitle-requests/abc123/

{
    "subtitler": null
}

Marking a subtitle request complete

PUT /api/subtitle-requests/abc123/

{
    "state": "complete"
}

Moving a subtitle request to another team

PUT /api/subtitle-requests/abc123/

{
    "team": "other-team-slug"
}

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.