API Overview

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

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
X-api-key: MY_API_KEY

For simplicity, the examples below do not include auth headers, but they are required for every API request.

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.

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

Videos

Videos resource

List videos

Example
Request
GET https://amara.org/api/videos/?team=my-team HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 20
    },
    "objects": [
        {
            "activity_uri": "https://amara.org/api/videos/NI1hLjBxuTpk/activity/",
            "all_urls": [
                "http://www.youtube.com/watch?v=o0vnlylsQwc"
            ],
            "created": "2019-01-25T21:42:59Z",
            "description": "",
            "duration": 421,
            "id": "NI1hLjBxuTpk",
            "languages": [
                {
                    "code": "en",
                    "dir": "ltr",
                    "name": "English",
                    "published": false,
                    "resource_uri": "https://amara.org/api/videos/NI1hLjBxuTpk/languages/en/",
                    "subtitles_uri": "https://amara.org/api/videos/NI1hLjBxuTpk/languages/en/subtitles/"
                }
            ],
            "metadata": {},
            "original_language": "ase",
            "primary_audio_language_code": "ase",
            "project": null,
            "resource_uri": "https://amara.org/api/videos/NI1hLjBxuTpk/",
            "subtitle_languages_uri": "https://amara.org/api/videos/NI1hLjBxuTpk/languages/",
            "team": null,
            "thumbnail": "https://s3.amazonaws.com/s3.userdata.www.universalsubtitles.org/video/thumbnail/8000c0f9c2eae7b00eeb0dfcb0c35fcc93832e8a_480x270_crop-smart_upscale-True_q85.jpg",
            "title": "SBIE 2019 Stage 1",
            "urls_uri": "https://amara.org/api/videos/NI1hLjBxuTpk/urls/",
            "video_type": "Y"
        },
        ...
    ]
}
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_urlurlFilter by video URL.
teamslugFilter by team. Passing in null will return only videos that are in the public area.
projectslugFilter by team project. Passing in null will return only videos that don’t belong to a project.
order_byenumChange the list ordering.
order_by options
titleascending
-titledescending
createdolder videos first
-creatednewer videos
  • 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
Video objects
idvideo-idAmara video id.
primary_audio_language_codebcp-47Audio language code.
titlestringVideo title.
descriptionstringVideo description.
durationintegerVideo duration in seconds (or null if not known).
thumbnailurlURL to the video thumbnail.
creatediso-8601Video creation date/time.
teamslugSlug of the Video’s team (or null).
metadatadictDict mapping metadata names to values.
languageslistList of languages that have subtitles started. See below for a description.
video_typecharVideo type identifier.
all_urlslistList of URLs for the video (the first one is the primary video URL).
activity_uriuriVideo Activity Resource.
urls_uriurlVideo URL Resource.
subtitle_languages_uriuriSubtitle languages Resource.
resource_uriuriVideo Resource.
original_languagestringcontains a copy of primary_audio_language_code (deprecated).
Language data
codestringLanguage code.
namestringHuman readable label for the language.
publishedbooleanAre the subtitles publicly viewable?
dirstringLanguage direction (“ltr” or “rtl”).
subtitles_uriurlSubtitles Resource.
resource_uriurlSubtitles Language Resource.

View video details

Example
Request
GET https://amara.org/api/videos/NI1hLjBxuTpk/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "activity_uri": "https://amara.org/api/videos/NI1hLjBxuTpk/activity/",
    "all_urls": [
        "http://www.youtube.com/watch?v=o0vnlylsQwc"
    ],
    "created": "2019-01-25T21:42:59Z",
    "description": "",
    "duration": 421,
    "id": "NI1hLjBxuTpk",
    "languages": [
        {
            "code": "en",
            "dir": "ltr",
            "name": "English",
            "published": true,
            "resource_uri": "https://amara.org/api/videos/NI1hLjBxuTpk/languages/en/",
            "subtitles_uri": "https://amara.org/api/videos/NI1hLjBxuTpk/languages/en/subtitles/"
        }
    ],
    "metadata": {},
    "original_language": "ase",
    "primary_audio_language_code": "ase",
    "project": null,
    "resource_uri": "https://amara.org/api/videos/NI1hLjBxuTpk/",
    "subtitle_languages_uri": "https://amara.org/api/videos/NI1hLjBxuTpk/languages/",
    "team": null,
    "thumbnail": "https://userdata.amara.org/video/thumbnail/8000c0f9c2eae7b00eeb0dfcb0c35fcc93832e8a_480x270_crop-smart_upscale-True_q85.jpg",
    "title": "SBIE 2019 Stage 1",
    "urls_uri": "https://amara.org/api/videos/NI1hLjBxuTpk/urls/",
    "video_type": "Y"
}
GET
/api/videos/[video-id]/
  • video-id is the Amara video identifier
  • See above for a description of the response data

Add a video

Example
Request
POST https://amara.org/api/videos/ HTTP/1.1

{
    "title": "Dogs and Cats",
    "video_url": "http://example.com/video.mp4"
}
Response
HTTP/1.1 201 Created

{
    "activity_uri": "https://amara.org/api/videos/PO0pMxxtXvZA/activity/",
    "all_urls": [
        "http://example.com/video.mp4"
    ],
    "created": "2019-01-28T21:36:07.007551Z",
    "description": "",
    "duration": null,
    "id": "PO0pMxxtXvZA",
    "languages": [],
    "metadata": {},
    "original_language": null,
    "primary_audio_language_code": null,
    "project": null,
    "resource_uri": "https://amara.org/api/videos/PO0pMxxtXvZA/",
    "subtitle_languages_uri": "https://amara.org/api/videos/PO0pMxxtXvZA/languages/",
    "team": null,
    "thumbnail": "https://s3.amazonaws.com/s3.staging.amara.org/966359a2/images/video-no-thumbnail-wide.png",
    "title": "Dogs and Cats",
    "urls_uri": "https://amara.org/api/videos/PO0pMxxtXvZA/urls/",
    "video_type": "H"
}
POST
/api/videos/
Request fields
video_urlurlThe 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).
titlestringTitle of the video.
descriptionstringAbout this video.
durationintegerDuration in seconds, in case it can not be retrieved automatically by Amara.
primary_audio_language_codestringlanguage code for the main language spoken in the video.
thumbnailurlURL to the video thumbnail.
metadatadictDictionary 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.
teamstringTeam slug for the video or null to remove it from its team.
projectstringProject slug for the video or null to put it in the default project.

Delete a video

Example
Request
DELETE https://amara.org/api/videos/PO0pMxxtXvZA/ HTTP/1.1
Response
HTTP/1.1 204 No Content
DELETE
/api/videos/[video-id]/

In order to delete a video, it must be part of a team that you're an admin of.

Video URLs

List video URLs

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.

Example
Request
GET https://amara.org/api/videos/K1TIDcoIxhir/urls/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 2
    },
    "objects": [
        {
            "created": "2017-03-01T09:58:59Z",
            "id": 1640867,
            "original": true,
            "primary": true,
            "resource_uri": "https://amara.org/api/videos/K1TIDcoIxhir/urls/1640867/",
            "type": "Youtube",
            "url": "http://www.youtube.com/watch?v=aQ-xe-GSjdA",
            "videoid": "aQ-xe-GSjdA"
        },
        {
            "created": "2019-01-28T21:43:50Z",
            "id": 1839769,
            "original": false,
            "primary": false,
            "resource_uri": "https://amara.org/api/videos/K1TIDcoIxhir/urls/1839769/",
            "type": "HTML5",
            "url": "http://example.com/meet-amara.mp4",
            "videoid": ""
        }
    ]
}
GET
/api/videos/[video-id]/urls/

List results are paginated.

Video URL Objects
video-idstringAmara video ID.
creatediso-8601creation date/time.
urlurlURL string.
primarybooleanis this the primary URL for the video?
originalbooleanwas this the URL that was created with the video?
resource_uriuriVideo URL Resource.
videoidstringID on the Hosting platform.
typestringVideo type (YouTube, Vimeo, HTML5, etc.).
idintegerInternal ID for the object (deprecated, use resource_uri rather than trying to construct API URLs yourself).

Get details on a video URL

Example
Request
GET https://amara.org/api/videos/K1TIDcoIxhir/urls/1640867/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "created": "2017-03-01T09:58:59Z",
    "id": 1640867,
    "original": true,
    "primary": true,
    "resource_uri": "https://amara.org/api/videos/K1TIDcoIxhir/urls/1640867/",
    "type": "Youtube",
    "url": "http://www.youtube.com/watch?v=aQ-xe-GSjdA",
    "videoid": "aQ-xe-GSjdA"
}
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.

Make a video URL primary

Example
Request
PUT https://amara.org/api/videos/K1TIDcoIxhir/urls/1640867/ HTTP/1.1

{
    "primary": true
}
Response
HTTP/1.1 200 OK

{
    "created": "2017-03-01T09:58:59Z",
    "id": 1640867,
    "original": true,
    "primary": true,
    "resource_uri": "https://amara.org/api/videos/K1TIDcoIxhir/urls/1640867/",
    "type": "Youtube",
    "url": "http://www.youtube.com/watch?v=aQ-xe-GSjdA",
    "videoid": "aQ-xe-GSjdA"
}
PUT
[video-url-endpoint]

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

There is only 1 field:

primarybooleanPass in true to change the primary URL to this one.

Delete a video URL

Example
Request
DELETE https://amara.org/api/videos/K1TIDcoIxhir/urls/1839769/ HTTP/1.1
Response
HTTP/1.1 204 No Content
DELETE
[video-url-endpoint]

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

Subtitles

Subtitle language resource

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

List subtitle languages for a video

Example
Request
GET https://amara.org/api/videos/K1TIDcoIxhir/languages/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 2
    },
    "objects": [
        {
            "created": "2016-02-29T14:09:38Z",
            "description": "Help translate this video: http://amara.org/v/FWb4/\nVisit Amara: http://amara.org\n\nAmara is home to an award winning subtitle editor, many different video localization and accessibility communities, plus a range of professional solutions that make it easy to caption and translate video.",
            "id": 1040254,
            "is_original": true,
            "is_primary_audio_language": true,
            "is_rtl": false,
            "is_translation": false,
            "language_code": "en",
            "metadata": {},
            "name": "English",
            "num_versions": 1,
            "original_language_code": null,
            "published": true,
            "resource_uri": "https://amara.org/api/videos/K1TIDcoIxhir/languages/en/",
            "soft_limit_cpl": null,
            "soft_limit_cps": null,
            "soft_limit_lines": null,
            "soft_limit_max_duration": null,
            "soft_limit_min_duration": null,
            "subtitle_count": 20,
            "subtitles_complete": true,
            "subtitles_uri": "https://amara.org/api/videos/K1TIDcoIxhir/languages/en/subtitles/",
            "title": "Meet Amara",
            "versions": [
                {
                    "author": {
                        "id": "jGvdcg-jNoGc32ySWS13tD-Q4SM_0sb8-rU61IYh66o",
                        "uri": "https://amara.org/api/users/id$jGvdcg-jNoGc32ySWS13tD-Q4SM_0sb8-rU61IYh66o/",
                        "username": "dean"
                    },
                    "published": true,
                    "version_no": 1
                }
            ]
        },
        {
            "created": "2016-02-29T15:07:55Z",
            "description": "Help translate this video: http://amara.org/v/FWb4/\nVisit Amara: http://amara.org\n\nAmara is home to an award winning subtitle editor, many different video localization and accessibility communities, plus a range of professional solutions that make it easy to caption and translate video.",
            "id": 1040255,
            "is_original": false,
            "is_primary_audio_language": false,
            "is_rtl": false,
            "is_translation": false,
            "language_code": "zh-cn",
            "metadata": {},
            "name": "Chinese, Simplified",
            "num_versions": 0,
            "original_language_code": null,
            "published": false,
            "resource_uri": "https://amara.org/api/videos/K1TIDcoIxhir/languages/zh-cn/",
            "soft_limit_cpl": null,
            "soft_limit_cps": null,
            "soft_limit_lines": null,
            "soft_limit_max_duration": null,
            "soft_limit_min_duration": null,
            "subtitle_count": 0,
            "subtitles_complete": false,
            "subtitles_uri": "https://amara.org/api/videos/K1TIDcoIxhir/languages/zh-cn/subtitles/",
            "title": "Meet Amara",
            "versions": []
        }
    ]
}
GET
/api/videos/[video-id]/languages/

Get a list of subtitle languages for a video.

List results are paginated.

Subtitle Language data
language_codebcp-47Subtitle language.
namestringHuman-readable name for this language.
is_primary_audio_languagebooleanIs this language the primary language spoken in the video?
is_rtlbooleanIs this language RTL?
resource_uriuriSubtitle Language Resource.
creatediso-8601when the language was created.
titlestringVideo title, translated into this language.
descriptionstringVideo description, translated into this language.
metadatadictVideo metadata, translated into this language.
subtitles_completebooleanAre the subtitles complete for this language?
subtitle_countintegerNumber of subtitles for this language.
reviewerstringUsername of the reviewer for task-based teams.
approverstringUsername of the approver for task-based teams.
is_translationbooleanIs this language translated from other languages? (deprecated).
publishedbooleanAre the subtitles publicly viewable?
original_language_codestringSource translation language (deprecated).
num_versionsintegerNumber of subtitle versions, the length of the versions array should be used instead of this (deprecated).
idintegerInternal ID for the language (deprecated).
is_originalbooleanalias for is_primary_audio_language (deprecated).
versionslistList of subtitle version data. See below for details.
versions field data
authoruser-dataSubtitle author (see User fields).
version_nointegerNumber of the version.
publishedbooleanIs this version publicly viewable?

Get details on a single subtitle language

Example
Request
GET https://amara.org/api/videos/K1TIDcoIxhir/languages/en/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "created": "2016-02-29T14:09:38Z",
    "description": "Help translate this video: http://amara.org/v/FWb4/\nVisit Amara: http://amara.org\n\nAmara is home to an award winning subtitle editor, many different video localization and accessibility communities, plus a range of professional solutions that make it easy to caption and translate video.",
    "id": 1040254,
    "is_original": true,
    "is_primary_audio_language": true,
    "is_rtl": false,
    "is_translation": false,
    "language_code": "en",
    "metadata": {},
    "name": "English",
    "num_versions": 1,
    "original_language_code": null,
    "published": true,
    "resource_uri": "https://amara.org/api/videos/K1TIDcoIxhir/languages/en/",
    "soft_limit_cpl": null,
    "soft_limit_cps": null,
    "soft_limit_lines": null,
    "soft_limit_max_duration": null,
    "soft_limit_min_duration": null,
    "subtitle_count": 20,
    "subtitles_complete": true,
    "subtitles_uri": "https://amara.org/api/videos/K1TIDcoIxhir/languages/en/subtitles/",
    "title": "Meet Amara",
    "versions": [
        {
            "author": {
                "id": "jGvdcg-jNoGc32ySWS13tD-Q4SM_0sb8-rU61IYh66o",
                "uri": "https://amara.org/api/users/id$jGvdcg-jNoGc32ySWS13tD-Q4SM_0sb8-rU61IYh66o/",
                "username": "dean"
            },
            "published": true,
            "version_no": 1
        }
    ]
}
GET
/api/videos/[video-id]/languages/[language-code]/

See above for a description of the response data.

Create a subtitle language

Example
Request
POST https://amara.org/api/videos/K1TIDcoIxhir/languages/ HTTP/1.1

{
    "is_primary_audio_language": false,
    "language_code": "en"
}
Response
HTTP/1.1 201 Created

{
    "created": "2019-01-28T22:53:34.089958Z",
    "description": "Help translate this video: http://amara.org/v/FWb4/\nVisit Amara: http://amara.org\n\nAmara is home to an award winning subtitle editor, many different video localization and accessibility communities, plus a range of professional solutions that make it easy to caption and translate video.",
    "id": 1093874,
    "is_original": true,
    "is_primary_audio_language": true,
    "is_rtl": false,
    "is_translation": false,
    "language_code": "en",
    "metadata": {},
    "name": "English",
    "num_versions": 0,
    "original_language_code": null,
    "published": false,
    "resource_uri": "https://amara.org/api/videos/K1TIDcoIxhir/languages/en/",
    "soft_limit_cpl": null,
    "soft_limit_cps": null,
    "soft_limit_lines": null,
    "soft_limit_max_duration": null,
    "soft_limit_min_duration": null,
    "subtitle_count": 0,
    "subtitles_complete": false,
    "subtitles_uri": "https://amara.org/api/videos/K1TIDcoIxhir/languages/en/subtitles/",
    "title": "Meet Amara",
    "versions": []
}
POST
/api/videos/[video-id]/languages/
Request fields
language_codestringbcp-47 code for the language.
is_primary_audio_languagebooleanIs this the primary spoken language of the video? (optional).
subtitles_completebooleanAre the subtitles for this language complete? (optional).
is_originalbooleanAlias for is_primary_audio_language (deprecated).
is_completebooleanAlias for subtitles_complete (deprecated).
soft_limit_linesintegerControls the max number of lines per subtitle. A warning is shown in the editor if this limit is exceeded.
soft_limit_min_durationintegerControls min duration of subtitles in milliseconds. A warning is shown in the editor if this limit is exceeded.
soft_limit_max_durationintegerControls max duration of subtitles in milliseconds. This controls the message in the guidelines dialog.
soft_limit_cplintegerControls the max characters per line for subtitles. A warning is shown in the editor if this limit is exceeded.
soft_limit_cpsintegerControls the max characters per second for subtitles. A warning is shown in the editor if this limit is exceeded.

Update a subtitle language

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

Fetch subtitles data

Example
Request
GET https://amara.org/api/videos/K1TIDcoIxhir/languages/en/subtitles/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "actions_uri": "https://amara.org/api/videos/K1TIDcoIxhir/languages/en/subtitles/actions/",
    "author": {
        "id": "jGvdcg-jNoGc32ySWS13tD-Q4SM_0sb8-rU61IYh66o",
        "uri": "https://amara.org/api/users/id$jGvdcg-jNoGc32ySWS13tD-Q4SM_0sb8-rU61IYh66o/",
        "username": "dean"
    },
    "description": "Help translate this video: http://amara.org/v/FWb4/\nVisit Amara: http://amara.org\n\nAmara is home to an award winning subtitle editor, many different video localization and accessibility communities, plus a range of professional solutions that make it easy to caption and translate video.",
    "language": {
        "code": "en",
        "dir": "ltr",
        "name": "English"
    },
    "metadata": {},
    "notes_uri": "https://amara.org/api/videos/K1TIDcoIxhir/languages/en/subtitles/notes/",
    "resource_uri": "https://amara.org/api/videos/K1TIDcoIxhir/languages/en/subtitles/",
    "site_uri": "https://amara.org/en/videos/K1TIDcoIxhir/en/1040254/2294246/",
    "sub_format": "json",
    "subtitles": [
        {
            "end": 3153,
            "meta": {
                "new_paragraph": true,
                "region": null
            },
            "position": 1,
            "start": 830,
            "text": "Amara makes video globally accessible"
        },
        {
            "end": 5422,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 2,
            "start": 3153,
            "text": "with captions and translations."
        },
        {
            "end": 8770,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 3,
            "start": 5422,
            "text": "It was designed<br>with three audiences in mind."
        },
        {
            "end": 10952,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 4,
            "start": 8770,
            "text": "First, if you are a video creator,"
        },
        {
            "end": 12917,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 5,
            "start": 10952,
            "text": "Amara can help you make subtitles"
        },
        {
            "end": 15989,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 6,
            "start": 12917,
            "text": "with the easiest to learn<br>software in the world."
        },
        {
            "end": 18530,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 7,
            "start": 15989,
            "text": "It\u2019s collaborative, like Wikipedia,"
        },
        {
            "end": 22479,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 8,
            "start": 18530,
            "text": "so you can invite friends<br>and audience members to help out."
        },
        {
            "end": 25475,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 9,
            "start": 22479,
            "text": "Second, if you are<br>passionate about accessibility"
        },
        {
            "end": 26571,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 10,
            "start": 25475,
            "text": "like we are"
        },
        {
            "end": 30694,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 11,
            "start": 26571,
            "text": "you can join one of dozens of<br>communities on Amara that do things like"
        },
        {
            "end": 34169,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 12,
            "start": 30694,
            "text": "caption videos for deaf<br>and hard of hearing users"
        },
        {
            "end": 37474,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 13,
            "start": 34169,
            "text": "and translate videos<br>into dozens of languages."
        },
        {
            "end": 39430,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 14,
            "start": 37474,
            "text": "Third, if you are working with video"
        },
        {
            "end": 42861,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 15,
            "start": 39430,
            "text": "and need professional grade tools<br>or On Demand subtitles"
        },
        {
            "end": 44594,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 16,
            "start": 42861,
            "text": "Amara can help."
        },
        {
            "end": 46631,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 17,
            "start": 44594,
            "text": "So, whether you are an individual,"
        },
        {
            "end": 47927,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 18,
            "start": 46631,
            "text": "a community member"
        },
        {
            "end": 50454,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 19,
            "start": 47927,
            "text": "or an organization using Amara,"
        },
        {
            "end": 56000,
            "meta": {
                "new_paragraph": false,
                "region": null
            },
            "position": 20,
            "start": 50454,
            "text": "you are supporting Amara\u2019s mission<br>to ensure that everyone has access."
        }
    ],
    "title": "Meet Amara",
    "version_no": 1,
    "version_number": 1,
    "video": "Meet Amara",
    "video_description": "Help translate this video: http://amara.org/v/FWb4/\nVisit Amara: http://amara.org\n\nAmara is home to an award winning subtitle editor, many different video localization and accessibility communities, plus a range of professional solutions that make it easy to caption and translate video.",
    "video_title": "Meet Amara"
}
GET
/api/videos/[video-id]/languages/[language-code]/subtitles/
Query Parameters
sub_formatstringThe 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_numberintegerversion 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”.
versionintegerAlias for version_number (deprecated).
Response data
version_numberintegerversion number for the subtitles.
subtitlesstringSubtitle data. The format depends on the sub_format param.
authoruser-dataSubtitle author (see User fields).
sub_formatstringFormat of the subtitles.
languageobjectLanguage data (see below).
titlestringVideo title, translated into the subtitle’s language.
descriptionstringVideo description, translated into the subtitle’s language.
metadatastringVideo metadata, translated into the subtitle’s language.
video_titlestringVideo title, translated into the video’s language.
video_descriptionstringVideo description, translated into the video’s language.
notes_uriuriSubtitle notes resource.
actions_uriuriSubtitle actions resource.
resource_uriuriSubtitles resource.
site_uriurlURL to view the subtitles on site.
videostringCopy of video_title (deprecated).
version_nointegerCopy of version_number (deprecated).
Language field
codebcp-47Language of the subtitles.
namestringHuman-readable name for the language.
dirstringLanguage direction (ltr or rtl).

Fetch raw subtitles

Example
Request
GET https://amara.org/api/videos/K1TIDcoIxhir/languages/en/subtitles/?format=vtt HTTP/1.1
Response
HTTP/1.1 200 OK

WEBVTT

NOTE Paragraph

00:00:00.830 --> 00:00:03.153
Amara makes video globally accessible

00:00:03.153 --> 00:00:05.422
with captions and translations.

00:00:05.422 --> 00:00:08.770
It was designed
with three audiences in mind.

00:00:08.770 --> 00:00:10.952
First, if you are a video creator,

00:00:10.952 --> 00:00:12.917
Amara can help you make subtitles

00:00:12.917 --> 00:00:15.989
with the easiest to learn
software in the world.

00:00:15.989 --> 00:00:18.530
It’s collaborative, like Wikipedia,

00:00:18.530 --> 00:00:22.479
so you can invite friends
and audience members to help out.

00:00:22.479 --> 00:00:25.475
Second, if you are
passionate about accessibility

00:00:25.475 --> 00:00:26.571
like we are

00:00:26.571 --> 00:00:30.694
you can join one of dozens of
communities on Amara that do things like

00:00:30.694 --> 00:00:34.169
caption videos for deaf
and hard of hearing users

00:00:34.169 --> 00:00:37.474
and translate videos
into dozens of languages.

00:00:37.474 --> 00:00:39.430
Third, if you are working with video

00:00:39.430 --> 00:00:42.861
and need professional grade tools
or On Demand subtitles

00:00:42.861 --> 00:00:44.594
Amara can help.

00:00:44.594 --> 00:00:46.631
So, whether you are an individual,

00:00:46.631 --> 00:00:47.927
a community member

00:00:47.927 --> 00:00:50.454
or an organization using Amara,

00:00:50.454 --> 00:00:56.000
you are supporting Amara’s mission
to ensure that everyone has access.
GET
/api/videos/[video-id]/languages/[language-code]/subtitles/

Often you want just subtitles data in a standard format, without the rest of the data from the subtitles endpoint. 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

Add new subtitles

Example
Request
POST https://amara.org/api/videos/K1TIDcoIxhir/languages/en/subtitles/ HTTP/1.1

{
    "action": "publish",
    "sub_format": "vtt",
    "subtitles": "WEBVTT\n\n00:01.000 --> 00:04.000\nNever drink liquid nitrogen.\n\n00:05.000 --> 00:09.000\n- It will perforate your stomach.\n- You could die."
}
Response
HTTP/1.1 201 Created

{
    "actions_uri": "https://amara.org/api/videos/K1TIDcoIxhir/languages/en/subtitles/actions/",
    "author": {
        "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
        "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
        "username": "bendk"
    },
    "description": "",
    "language": {
        "code": "en",
        "dir": "ltr",
        "name": "English"
    },
    "metadata": {},
    "notes_uri": "https://amara.org/api/videos/K1TIDcoIxhir/languages/en/subtitles/notes/",
    "resource_uri": "https://amara.org/api/videos/K1TIDcoIxhir/languages/en/subtitles/",
    "site_uri": "https://amara.org/en/videos/K1TIDcoIxhir/en/1040254/2347578/",
    "sub_format": "vtt",
    "subtitles": "WEBVTT\n\nNOTE Paragraph\n\n00:00:01.000 --> 00:00:04.000\nNever drink liquid nitrogen.\n\n00:00:05.000 --> 00:00:09.000\n- It will perforate your stomach.\n- You could die.",
    "title": "",
    "version_no": 3,
    "version_number": 3,
    "video": "Meet Amara",
    "video_description": "Help translate this video: http://amara.org/v/FWb4/\nVisit Amara: http://amara.org\n\nAmara is home to an award winning subtitle editor, many different video localization and accessibility communities, plus a range of professional solutions that make it easy to caption and translate video.",
    "video_title": "Meet Amara"
}
POST
/api/videos/[video-id]/languages/[language-code]/subtitles/
Request fields
subtitlesstringThe subtitles to submit, as a string. The format depends on the sub_format param.
subtitles_urluriAlternatively, subtitles can be given as a text file URL. The format depends on the sub_format param.
sub_formatstringThe format used to parse the subs. The same formats as for fetching subtitles are accepted. (Defaults to dfxp).
titlestringGive a title to the new revision.
descriptionstringGive a description to the new revision.
actionstringName of the action to perform - optional, but recommended. If given, the is_complete param will be ignored. For more details, see the subtitle actions documentation.
is_completebooleanBoolean indicating if the complete subtitling set is available for this language - optional, defaults to false. (deprecated, use action instead).

Delete subtitles

Example
Request
DELETE https://amara.org/api/videos/K1TIDcoIxhir/languages/fr/subtitles/ HTTP/1.1
Response
HTTP/1.1 204 No Content
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 that correspond to the buttons in the upper-right hand corner of the subtitle editor (save, save a draft, approve, reject, etc). The available actions depend on several factors like the team of the video, if there is a completed draft, etc. Use the subtiitle actions resource 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.

List actions

Example
Request
GET https://amara.org/api/videos/K1TIDcoIxhir/languages/en/subtitles/actions/ HTTP/1.1
Response
HTTP/1.1 200 OK

[
    {
        "action": "save-draft",
        "complete": null,
        "label": "Save Draft"
    },
    {
        "action": "publish",
        "complete": true,
        "label": "Publish"
    }
]
GET
/api/videos/[video-id]/languages/[language-code]/subtitles/actions/

Get the list of available actions for a subtitle set.

Response data
actionstringAction name.
labelstringHuman-friendly string for the action.
completebooleanDoes this action complete the subtitles? true: mark the subtitles complete. false: mark the subtitles incomplete. null: do not change the subtitles_complete flag.

Perform actions

Example
Request
POST https://amara.org/api/videos/K1TIDcoIxhir/languages/en/subtitles/actions/ HTTP/1.1

{
    "action": "publish"
}
Response
HTTP/1.1 200 OK

""
POST
/api/videos/[video-id]/languages/[language-code]/subtitles/actions/

Perform an action on the subtitles. This is equivalent to opening the editor, not changing the subtitles, and clicking an actions button.

Request data
actionstringAction to perform.

Subtitles notes resource

Get/post subtitle editor notes.

Fetch notes

Example
Request
GET https://amara.org/api/videos/K1TIDcoIxhir/languages/en/subtitles/notes/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 1
    },
    "objects": [
        {
            "body": "Make sure to capitalize New York City",
            "created": "2019-01-30T14:25:40Z",
            "user": {
                "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
                "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
                "username": "bendk"
            }
        }
    ]
}
GET
/api/videos/[video-id]/languages/[language-code]/subtitles/notes
Response data
useruser-dataNote author (see User fields).
datetimeiso-8601When the note was created.
bodystringText of the note.

Add notes

Example
Request
POST https://amara.org/api/videos/K1TIDcoIxhir/languages/en/subtitles/notes/ HTTP/1.1

{
    "body": "Make sure to capitalize New York City"
}
Response
HTTP/1.1 201 Created

{
    "body": "Make sure to capitalize New York City",
    "created": "2019-01-30T14:25:40.386959Z",
    "user": {
        "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
        "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
        "username": "bendk"
    }
}
POST
/api/videos/[video-id]/languages/[language-code]/subtitles/notes/
Request data
bodystringNote body.

Users

User fields in response data

When we reference users from other resources, (team members, subtitle authors, etc.), we use a dict with the following fields:

usernamestringUsername.
idstringUser ID.
uriuriLink to the user API endpoint.

Example:

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

Specifying users in request data

There are a couple ways to specify users:

  • Username
  • User ID prefixed with "id$"

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

When you post data to an endpoint with a userfield, you can specify the user using either method. For example, to create a team member you can send this data:

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

Or this:

{
  "user": "alice",
  "role": "manager"
}

Get user data

Example
Request
GET https://amara.org/api/users/bendk/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "activity_uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/activity/",
    "avatar": "https://s3.amazonaws.com/s3.userdata.staging.amara.org/pictures/2a65623d70f1a1a1d9d926099a19ca010f26d1ba_JPG_100x100_crop-smart_upscale-True_q85.jpg",
    "biography": "",
    "created_by": null,
    "first_name": "new",
    "full_name": "",
    "homepage": "",
    "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
    "is_partner": false,
    "languages": [
        "en",
        "fr"
    ],
    "last_name": "",
    "num_videos": 4,
    "resource_uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
    "username": "bendk"
}
GET
/api/users/[identifier]
Parameters
identifieruser identifierSee Specifying users in request data.
Response data
usernameusernameusername.
idstringuser ID.
first_namestringFirst name.
last_namestringLast name.
homepageurlHomepage URL.
biographystringBio text.
num_videosintegerNumber of videos followed by the user.
languageslistList of language codes for languages the user speaks.
avatarurlURL to the user’s avatar image.
activity_uriuriUser Activity resource.
resource_uriuriUser resource.
full_namestringFull name of the user.

Create a user

Example
Request
POST https://amara.org/api/users/ HTTP/1.1

{
    "create_login_token": true,
    "email": "bob@example.com",
    "username": "bob-bobson"
}
Response
HTTP/1.1 201 Created

{
    "activity_uri": "https://amara.org/api/users/id$H-RZY6CTG6Xk1T3kEyp_DA0HCfKlx28Cd-D8b1VgWZo/activity/",
    "api_key": "5d1918f683249beb28fe2000f3b75a7f459273e5",
    "auto_login_url": "https://amara.org/en/auth/auto-login/9d7f4066699fc5cb104bb74767397a8f8aecd8a9/",
    "avatar": "https://www.gravatar.com/avatar/4b9bb80620f03eb3719e0a061c14283d?s=100&d=mm",
    "biography": "",
    "created_by": "bendk",
    "email": "bob@example.com",
    "first_name": "",
    "full_name": "",
    "homepage": "",
    "id": "H-RZY6CTG6Xk1T3kEyp_DA0HCfKlx28Cd-D8b1VgWZo",
    "is_partner": false,
    "languages": [],
    "last_name": "",
    "num_videos": 0,
    "resource_uri": "https://amara.org/api/users/id$H-RZY6CTG6Xk1T3kEyp_DA0HCfKlx28Cd-D8b1VgWZo/",
    "username": "bob-bobson"
}
POST
/api/users/
Request data
username (required)username30 chars or fewer alphanumeric chars, @, _ and are accepted.
email (required)emailA valid email address.
password (required)stringany number of chars, all chars allowed.
first_namestringAny chars, max 30 chars.
last_namestringAny chars, max 30 chars.
allow_3rd_party_loginbooleanIf set, account can be automatically linked to 3rd party account at first login.
create_login_tokenbooleanIf sent the response will also include a an auto_login_url field which will login the created user. Use this to allow users to login without explicitly setting their passwords. This URL expires in 2 hours.
find_unique_usernamebooleanIf 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.

Update your account

Example
Request
PUT https://amara.org/api/users/bendk/ HTTP/1.1

{
    "first_name": "Ben",
    "last_name": "Dean-Kawamura"
}
Response
HTTP/1.1 200 OK

{
    "activity_uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/activity/",
    "avatar": "https://s3.amazonaws.com/s3.userdata.staging.amara.org/pictures/2a65623d70f1a1a1d9d926099a19ca010f26d1ba_JPG_100x100_crop-smart_upscale-True_q85.jpg",
    "biography": "",
    "created_by": null,
    "email": "ben@pculture.org",
    "first_name": "Ben",
    "full_name": "",
    "homepage": "",
    "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
    "is_partner": false,
    "languages": [
        "en",
        "fr"
    ],
    "last_name": "Dean-Kawamura",
    "num_videos": 4,
    "resource_uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
    "username": "bendk"
}
PUT
/api/users/[identifier]/
Request data
emailemailA valid email address.
first_namestringAny chars, max 30 chars.
last_namestringAny chars, max 30 chars.

Activity

Activity types

Activity data is classified by type. Some types have extra data that is associated with them.

TypeCreated ByNotes/Extra Fields
video-addedVideo added to amara
comment-addedComment postedlanguage will be null for video comments and set for subtitle comments
version-addedSubtitle version added
video-title-changedVideo title changed
video-url-addedURL added to videourl will contain the new URL
video-url-editedPrimary video URL changeold_url/new_url will contain the old/new primary URL
video-url-deletedURL removed from videourl will contain the deleted URL
video-deletedVideo deleted from amaratitle will contain the deleted video’s title
Team Related Activity
member-joinedUser joined team
member-leftUser left team
Task Related Activity
version-approvedSubtitles approved
version-rejectedSubtitles sent back by approver
version-acceptedSubtitles approved by reviewer
version-declinedSubtitles sent back by reviewer

Video activity

Example
Request
GET https://amara.org/api/videos/K1TIDcoIxhir/activity/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 6
    },
    "objects": [
        {
            "date": "2019-01-29T22:22:48Z",
            "language": "fr",
            "language_uri": "https://amara.org/api/videos/K1TIDcoIxhir/languages/fr/",
            "type": "version-added",
            "user": {
                "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
                "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
                "username": "bendk"
            },
            "video": "K1TIDcoIxhir",
            "video_uri": "https://amara.org/api/videos/K1TIDcoIxhir/"
        },
        {
            "date": "2019-01-29T22:18:53Z",
            "language": "en",
            "language_uri": "https://amara.org/api/videos/K1TIDcoIxhir/languages/en/",
            "type": "version-added",
            "user": {
                "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
                "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
                "username": "bendk"
            },
            "video": "K1TIDcoIxhir",
            "video_uri": "https://amara.org/api/videos/K1TIDcoIxhir/"
        },
        {
            "date": "2019-01-29T22:05:53Z",
            "language": "en",
            "language_uri": "https://amara.org/api/videos/K1TIDcoIxhir/languages/en/",
            "type": "version-added",
            "user": {
                "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
                "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
                "username": "bendk"
            },
            "video": "K1TIDcoIxhir",
            "video_uri": "https://amara.org/api/videos/K1TIDcoIxhir/"
        },
        {
            "date": "2019-01-28T21:53:04Z",
            "language": null,
            "language_uri": null,
            "type": "video-url-deleted",
            "url": "http://example.com/meet-amara.mp4",
            "user": {
                "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
                "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
                "username": "bendk"
            },
            "video": "K1TIDcoIxhir",
            "video_uri": "https://amara.org/api/videos/K1TIDcoIxhir/"
        }
    ]
}
GET
/api/videos/[video-id]/activity/

List results are paginated.

Query Parameters
typestringActivity type. See Activity Types.
useruser identifierFilter by user who performed the action (see Specifying users in request data).
languagebcp-47Filter by the subtitle language.
beforeiso-8601Only include activity before this date/time.
afteriso-8601Only include activity after.
Response Data
typestringActivity type. See Activity Types.
dateiso-8601Date/time of the activity.
useruser-dataUser who performed the activity (see User fields).
videovideo-idVideo related to the activity (or null).
languagebcp-47Language of the subtitles related to the activity (or null).
video_uriuriLink to the video resource endpoint.
language_uriuriLink to the subtitle language resource endpoint.
Note
Depending on the activity type, extra fields may be present in the response data. See Activity Types.

Team activity

Example
Request
GET https://amara.org/api/teams/my-team/activity/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "meta": {
        "limit": 20,
        "next": "https://amara.org/api/teams/my-team/activity/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 34
    },
    "objects": [
        {
            "date": "2019-01-28T21:36:42Z",
            "language": null,
            "language_uri": null,
            "title": "Dogs and Cats",
            "type": "video-deleted",
            "user": {
                "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
                "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
                "username": "bendk"
            },
            "video": null,
            "video_uri": null
        },
        {
            "date": "2018-12-07T16:31:12Z",
            "language": "en",
            "language_uri": "https://amara.org/api/videos/bTCCPqZ5hDfA/languages/en/",
            "type": "version-added",
            "user": {
                "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
                "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
                "username": "bendk"
            },
            "video": "bTCCPqZ5hDfA",
            "video_uri": "https://amara.org/api/videos/bTCCPqZ5hDfA/"
        },
        {
            "date": "2018-10-29T17:35:15Z",
            "language": null,
            "language_uri": null,
            "type": "video-title-changed",
            "user": {
                "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
                "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
                "username": "bendk"
            },
            "video": "wmLoWX91VsJ8",
            "video_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/"
        }
    ]
}
GET
/api/teams/[slug]/activity/

List results are paginated.

Query Parameters
typestringActivity type. See Activity Types.
useruser identifierFilter by user who performed the action (see Specifying users in request data).
videovideo-idFilter by video.
video_languagebcp-47Filter by video language.
languagebcp-47Filter by the subtitle language.
beforeiso-8601Only include activity before this date/time.
afteriso-8601Only include activity after.
Response Data
typestringActivity type. See Activity Types.
dateiso-8601Date/time of the activity.
useruser-dataUser who performed the activity (see User fields).
videovideo-idVideo related to the activity (or null).
languagebcp-47Language of the subtitles related to the activity (or null).
video_uriuriLink to the video resource endpoint.
language_uriuriLink to the subtitle language resource endpoint.
Note
Depending on the activity type, extra fields may be present in the response data. See Activity Types.

User activity

Example
Request
GET https://amara.org/api/users/bendk/activity/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "meta": {
        "limit": 20,
        "next": "https://amara.org/api/users/bendk/activity/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 45
    },
    "objects": [
        {
            "date": "2019-01-29T22:22:48Z",
            "language": "fr",
            "language_uri": "https://amara.org/api/videos/K1TIDcoIxhir/languages/fr/",
            "type": "version-added",
            "user": {
                "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
                "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
                "username": "bendk"
            },
            "video": "K1TIDcoIxhir",
            "video_uri": "https://amara.org/api/videos/K1TIDcoIxhir/"
        },
        {
            "date": "2019-01-28T21:53:04Z",
            "language": null,
            "language_uri": null,
            "type": "video-url-deleted",
            "url": "http://example.com/meet-amara.mp4",
            "user": {
                "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
                "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
                "username": "bendk"
            },
            "video": "K1TIDcoIxhir",
            "video_uri": "https://amara.org/api/videos/K1TIDcoIxhir/"
        },
        {
            "date": "2018-09-24T19:08:07Z",
            "language": "en",
            "language_uri": "https://amara.org/api/videos/Z6TBY57kbpnp/languages/en/",
            "type": "comment-added",
            "user": {
                "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
                "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
                "username": "bendk"
            },
            "video": "Z6TBY57kbpnp",
            "video_uri": "https://amara.org/api/videos/Z6TBY57kbpnp/"
        }
    ]
}
GET
/api/users/[identifier]/activity/

List results are paginated.

URI Parameters
identifieruser identifierUser to find activity for. See Specifying users in request data.
Query Parameters
typestringActivity type Activity Types.
videovideo-idFilter by video.
video_languagebcp-47Filter by video language.
languagebcp-47Filter by the subtitle language.
teamslugFilter by team.
beforeiso-8601Only include activity before this date/time.
afteriso-8601Only include activity after.
Response Data
typestringActivity type. See Activity Types.
dateiso-8601Date/time of the activity.
useruser-dataUser who performed the activity (see User fields).
videovideo-idVideo related to the activity (or null).
languagebcp-47Language of the subtitles related to the activity (or null).
video_uriuriLink to the video resource endpoint.
language_uriuriLink to the subtitle language resource endpoint.
Note
Depending on the activity type, extra fields may be present in the response data. See Activity Types.

Legacy activity resource

Deprecated API endpoint that lists contains all amara activity. You should use the one of the team, video, or user query params to find the activity you want. New code should use the Video, Team, or User resources.

Example
Request
GET https://amara.org/api/activity/?video=K1TIDcoIxhir HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 6
    },
    "objects": [
        {
            "comment": null,
            "created": "2019-01-29T22:22:48Z",
            "id": 248188,
            "language": "fr",
            "language_url": "https://amara.org/api/videos/K1TIDcoIxhir/languages/fr/",
            "new_video_title": null,
            "resource_uri": "https://amara.org/api/activity/248188/",
            "type": 4,
            "type_name": "version-added",
            "user": "bendk",
            "video": "K1TIDcoIxhir",
            "video_uri": "https://amara.org/api/videos/K1TIDcoIxhir/"
        },
        {
            "comment": null,
            "created": "2019-01-29T22:18:53Z",
            "id": 248187,
            "language": "en",
            "language_url": "https://amara.org/api/videos/K1TIDcoIxhir/languages/en/",
            "new_video_title": null,
            "resource_uri": "https://amara.org/api/activity/248187/",
            "type": 4,
            "type_name": "version-added",
            "user": "bendk",
            "video": "K1TIDcoIxhir",
            "video_uri": "https://amara.org/api/videos/K1TIDcoIxhir/"
        },
        {
            "comment": null,
            "created": "2019-01-29T22:05:53Z",
            "id": 248186,
            "language": "en",
            "language_url": "https://amara.org/api/videos/K1TIDcoIxhir/languages/en/",
            "new_video_title": null,
            "resource_uri": "https://amara.org/api/activity/248186/",
            "type": 4,
            "type_name": "version-added",
            "user": "bendk",
            "video": "K1TIDcoIxhir",
            "video_uri": "https://amara.org/api/videos/K1TIDcoIxhir/"
        }
    ]
}
GET
/api/activity/
Query Parameters
teamslugShow only items related to a given team.
team-activitybooleanIf 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).
videovideo-idShow only items related to a given video.
languagebcp-47Show only items with a given language code.
beforeunix timestampOnly include items before this time.
afterunix timestampOnly include items after this time.
typeintegerShow only items with a given activity type. See below.
Type values
1Add video
2Change title
3Comment
4Add version
5Add video URL
6Add translation
7Subtitle request
8Approve version
9Member joined
10Reject version
11Member left
12Review version
13Accept version
14Decline version
15Delete video
Note
If both team and video are given as GET params, then team will be used and video will be ignored.

Messages

Post a message

Example
Request
POST https://amara.org/api/message/ HTTP/1.1

{
    "content": "Hello world",
    "subject": "Hello",
    "user": "id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8"
}
Response
HTTP/1.1 201 Created

{}
POST
/api/messages/

Send a message to a user or team.

Request data
useruser identifierRecipient user (see Specifying users in request data).
teamslugRecipient team.
subjectstringSubject of the message.
contentstringContent of the message.
Note
Send either the user or team field, but not both.

Teams

Teams resource

Get details on a team

Example
Request
GET https://amara.org/api/teams/ability/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "activity_uri": "https://amara.org/api/teams/ability/activity/",
    "applications_uri": null,
    "description": "ABILITY Magazine is consistently ranked in the Top 50 Magazines in the World \u2014 and is the leading magazine covering Health, Disability and Human Potential. We are an award-winning publication, distributed by Time-Warner. For over 20 years, our mission has been to provide new insights into our individual levels of ability.\r\n\r\nFrom Diabetes to Spinal Cord Injury and celebrity interviews to CEO profiles, ABILITY covers the latest on Health, Environmental Protection, Assistive Technology, Employment, Sports, Travel, Universal Design, Mental Health and much more. Our writers include MDs, PhDs, JDs, best-selling authors, U.S. Senators and advocates. Cover interviews consist of Movie and TV Celebrities, Business Leaders, Sports Figures, Presidents, First Ladies and more.",
    "is_visible": true,
    "languages_uri": "https://amara.org/api/teams/ability/languages/",
    "members_uri": "https://amara.org/api/teams/ability/members/",
    "membership_policy": "Open",
    "name": "ABILITY Magazine",
    "projects_uri": "https://amara.org/api/teams/ability/projects/",
    "resource_uri": "https://amara.org/api/teams/ability/",
    "slug": "ability",
    "tasks_uri": null,
    "type": "default",
    "video_policy": "Managers and admins"
}
GET
/api/teams/[slug]/
Team Data
namestringName of the team.
slugslugMachine name for the team slug (used in URLs).
typestringTeam type. See below for possible values.
descriptionstringTeam description.
team_visibilitystringWho can see the team? See below for possible values.
video_visibilitystringWho can see the team's videos? See below for possible values.
is_visiblebooleanLegacy visibility field. This will be True if team_visibility is public.
membership_policystringTeam membership policy. See below for possible values.
video_policystringWho can add videos to the team? See below for possible values.
activity_uriuriTeam activity resource.
members_uriuriTeam member list resource.
projects_uriuriTeam projects resource.
applications_uriuriTeam applications resource (or null if the membership policy is not by application).
languages_uriuriTeam preferred/blacklisted languages resource.
tasks_uriuriTeam tasks resource (or null if tasks are not enabled).
resource_uriuriTeam resource.
Team Type Values
defaultdefault team type
simplesimplified workflow team
collaborationcollaboration team
Team Visibility Values
privateOnly team members can view the team
unlistedTeam not listed in the directory, but publicly accessible for users with a link
publicAnyone can view the team (default)
Team Video Visibility Values
privateOnly team members can view the team’s videos
unlistedThe team’s videos not searchable, or listed in the directory, but publicly accessible for users with a link
publicAnyone can view the team’s videos (default)
Team Membership Policy Values
Open
Application
Invitation by any team member
Invitation by manager
Invitation by admin
Team Video Policy Values
Any team member
Managers and admins
Admins only

List teams

Example
Request
GET https://amara.org/api/teams/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "meta": {
        "limit": 20,
        "next": "https://amara.org/api/teams/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 1008
    },
    "objects": [
        {
            "activity_uri": "https://amara.org/api/teams/ability/activity/",
            "applications_uri": null,
            "description": "ABILITY Magazine is consistently ranked in the Top 50 Magazines in the World \u2014 and is the leading magazine covering Health, Disability and Human Potential. We are an award-winning publication, distributed by Time-Warner. For over 20 years, our mission has been to provide new insights into our individual levels of ability.\r\n\r\nFrom Diabetes to Spinal Cord Injury and celebrity interviews to CEO profiles, ABILITY covers the latest on Health, Environmental Protection, Assistive Technology, Employment, Sports, Travel, Universal Design, Mental Health and much more. Our writers include MDs, PhDs, JDs, best-selling authors, U.S. Senators and advocates. Cover interviews consist of Movie and TV Celebrities, Business Leaders, Sports Figures, Presidents, First Ladies and more.",
            "is_visible": true,
            "languages_uri": "https://amara.org/api/teams/ability/languages/",
            "members_uri": "https://amara.org/api/teams/ability/members/",
            "membership_policy": "Open",
            "name": "ABILITY Magazine",
            "projects_uri": "https://amara.org/api/teams/ability/projects/",
            "resource_uri": "https://amara.org/api/teams/ability/",
            "slug": "ability",
            "tasks_uri": null,
            "team_visibility": "public",
            "type": "default",
            "video_policy": "Managers and admins",
            "video_visibility": "public"
        },
        {
            "activity_uri": "https://amara.org/api/teams/ability/activity/",
            "applications_uri": null,
            "description": "ABILITY Magazine is consistently ranked in the Top 50 Magazines in the World \u2014 and is the leading magazine covering Health, Disability and Human Potential. We are an award-winning publication, distributed by Time-Warner. For over 20 years, our mission has been to provide new insights into our individual levels of ability.\r\n\r\nFrom Diabetes to Spinal Cord Injury and celebrity interviews to CEO profiles, ABILITY covers the latest on Health, Environmental Protection, Assistive Technology, Employment, Sports, Travel, Universal Design, Mental Health and much more. Our writers include MDs, PhDs, JDs, best-selling authors, U.S. Senators and advocates. Cover interviews consist of Movie and TV Celebrities, Business Leaders, Sports Figures, Presidents, First Ladies and more.",
            "is_visible": true,
            "languages_uri": "https://amara.org/api/teams/ability/languages/",
            "members_uri": "https://amara.org/api/teams/ability/members/",
            "membership_policy": "Open",
            "name": "ABILITY Magazine",
            "projects_uri": "https://amara.org/api/teams/ability/projects/",
            "resource_uri": "https://amara.org/api/teams/ability/",
            "slug": "ability",
            "tasks_uri": null,
            "team_visibility": "public",
            "type": "default",
            "video_policy": "Managers and admins",
            "video_visibility": "public"
        },
        {
            "activity_uri": "https://amara.org/api/teams/ability/activity/",
            "applications_uri": null,
            "description": "ABILITY Magazine is consistently ranked in the Top 50 Magazines in the World \u2014 and is the leading magazine covering Health, Disability and Human Potential. We are an award-winning publication, distributed by Time-Warner. For over 20 years, our mission has been to provide new insights into our individual levels of ability.\r\n\r\nFrom Diabetes to Spinal Cord Injury and celebrity interviews to CEO profiles, ABILITY covers the latest on Health, Environmental Protection, Assistive Technology, Employment, Sports, Travel, Universal Design, Mental Health and much more. Our writers include MDs, PhDs, JDs, best-selling authors, U.S. Senators and advocates. Cover interviews consist of Movie and TV Celebrities, Business Leaders, Sports Figures, Presidents, First Ladies and more.",
            "is_visible": true,
            "languages_uri": "https://amara.org/api/teams/ability/languages/",
            "members_uri": "https://amara.org/api/teams/ability/members/",
            "membership_policy": "Open",
            "name": "ABILITY Magazine",
            "projects_uri": "https://amara.org/api/teams/ability/projects/",
            "resource_uri": "https://amara.org/api/teams/ability/",
            "slug": "ability",
            "tasks_uri": null,
            "team_visibility": "public",
            "type": "default",
            "video_policy": "Managers and admins",
            "video_visibility": "public"
        }
    ]
}
GET
/api/teams/

List teams. Results are paginated. See above for a description of the returned data.

Create a team

Example
Request
POST https://amara.org/api/teams/ HTTP/1.1

{
    "name": "My Team",
    "slug": "my-team",
    "type": "collaboration"
}
Response
HTTP/1.1 201 Created

{
    "activity_uri": "https://amara.org/api/teams/my-team/activity/",
    "applications_uri": null,
    "description": "",
    "is_visible": true,
    "languages_uri": null,
    "members_uri": "https://amara.org/api/teams/my-team/members/",
    "membership_policy": "Invitation by admin",
    "name": "My Team",
    "projects_uri": "https://amara.org/api/teams/my-team/projects/",
    "resource_uri": "https://amara.org/api/teams/my-team/",
    "slug": "my-team",
    "tasks_uri": null,
    "team_visibility": "public",
    "type": "collaboration",
    "video_policy": "Admins only",
    "video_visibility": "public"
}
POST
/api/teams/

Create a team

Request data
name (required)stringName of the team.
slug (required)slugMachine name for the team (used in URLs).
type (required)stringTeam type. (See above for possible values).
descriptionstringTeam description.
team_visibilitystringWho can see the team? (See above for possible values).
video_visibilitystringWho can see the team's videos? (See above for possible values).
is_visiblebooleanLegacy 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.
membership_policystringTeam membership policy. (See above for possible values).
video_policystringWho can add videos to the team? (See above for possible values).
Note
Creating teams is restricted to Amara partners

Team member resource

List team members

Example
Request
GET https://amara.org/api/teams/my-team/members/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 3
    },
    "objects": [
        {
            "resource_uri": "https://amara.org/api/teams/my-team/members/id$qEAh9Rr8SWMvj3TNmo3kI41vOmueb6rzc-xtGcsCaII/",
            "role": "contributor",
            "user": {
                "id": "qEAh9Rr8SWMvj3TNmo3kI41vOmueb6rzc-xtGcsCaII",
                "uri": "https://amara.org/api/users/id$qEAh9Rr8SWMvj3TNmo3kI41vOmueb6rzc-xtGcsCaII/",
                "username": "@PCFQA"
            }
        },
        {
            "resource_uri": "https://amara.org/api/teams/my-team/members/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
            "role": "owner",
            "user": {
                "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
                "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
                "username": "bendk"
            }
        },
        {
            "resource_uri": "https://amara.org/api/teams/my-team/members/id$YHg9pnbZwzSajuCD7Uy6_4VicVdhhjnuQxeVcCIGdjg/",
            "role": "contributor",
            "user": {
                "id": "YHg9pnbZwzSajuCD7Uy6_4VicVdhhjnuQxeVcCIGdjg",
                "uri": "https://amara.org/api/users/id$YHg9pnbZwzSajuCD7Uy6_4VicVdhhjnuQxeVcCIGdjg/",
                "username": "bendk2"
            }
        }
    ]
}
GET
/api/teams/[slug]/members/

Get a list of members on a team. List results are paginated.

Response data
useruserUser associated with the membership (see User fields).
rolestringPossible values: owner, admin, manager, proj_lang_manager, contributor, or limited_contributor (for collaboration teams only).
languages_managedbcp-47 list(for proj_lang_manager only) the list of languages managed by the language manager.
projects_managedslug-list(for proj_lang_manager only) the list of projects managed by the project manager.

Get details on a single member

Example
Request
GET https://amara.org/api/teams/my-team/members/bendk/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "resource_uri": "https://amara.org/api/teams/my-team/members/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
    "role": "owner",
    "user": {
        "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
        "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
        "username": "bendk"
    }
}
GET
/api/teams/[slug]/members/[user-identifier]/
URI paramaters
slugslugTeam slug.
useruser identifierUser to fetch details for (see Specifying users in request data).
Response data
useruserUser associated with the membership (see User fields).
rolestringPossible values: owner, admin, manager, proj_lang_manager, contributor, or limited_contributor (for collaboration teams only).
languages_managedbcp-47 list(for proj_lang_manager only) the list of languages managed by the language manager.
projects_managedslug-list(for proj_lang_manager only) the list of projects managed by the project manager.

Add a member to a team

Example
Request
POST https://amara.org/api/teams/my-team/members/ HTTP/1.1

{
    "role": "contributor",
    "user": "dean"
}
Response
HTTP/1.1 201 Created

{
    "resource_uri": "https://amara.org/api/teams/my-team/members/id$jGvdcg-jNoGc32ySWS13tD-Q4SM_0sb8-rU61IYh66o/",
    "role": "contributor",
    "user": {
        "id": "jGvdcg-jNoGc32ySWS13tD-Q4SM_0sb8-rU61IYh66o",
        "uri": "https://amara.org/api/users/id$jGvdcg-jNoGc32ySWS13tD-Q4SM_0sb8-rU61IYh66o/",
        "username": "dean"
    }
}
POST
/api/teams/[team-slug]/members/
Request data
useruser identifierUser to add (see Specifying users in request data).
rolestringPossible values: owner, admin, manager, proj_lang_manager, contributor, or limited_contributor (for collaboration teams only).
languages_managedbcp-47 list(for proj_lang_manager only) the list of languages managed by the language manager.
projects_managedslug-list(for proj_lang_manager only) the list of projects managed by the project manager.

Change a team member's role

Example
Request
PUT https://amara.org/api/teams/my-team/members/dean/ HTTP/1.1

{
    "role": "manager"
}
Response
HTTP/1.1 200 OK

{
    "resource_uri": "https://amara.org/api/teams/my-team/members/id$jGvdcg-jNoGc32ySWS13tD-Q4SM_0sb8-rU61IYh66o/",
    "role": "manager",
    "user": {
        "id": "jGvdcg-jNoGc32ySWS13tD-Q4SM_0sb8-rU61IYh66o",
        "uri": "https://amara.org/api/users/id$jGvdcg-jNoGc32ySWS13tD-Q4SM_0sb8-rU61IYh66o/",
        "username": "dean"
    }
}
POST
/api/teams/[team-slug]/members/[user-identifier]/
URI paramaters
slugslugTeam slug.
useruser identifierUser to fetch details for (see Specifying users in request data).
Request data
rolestringPossible values: owner, admin, manager, proj_lang_manager, contributor, or limited_contributor (for collaboration teams only).
languages_managedbcp-47 list(for proj_lang_manager only) the list of languages managed by the language manager.
projects_managedslug-list(for proj_lang_manager only) the list of projects managed by the project manager.

Remove a user from a team

Example
Request
DELETE https://amara.org/api/teams/my-team/members/dean/ HTTP/1.1
Response
HTTP/1.1 204 No Content
DELETE
/api/teams/[team-slug]/members/[user-identifier]/
URI paramaters
slugslugTeam slug.
useruser identifierUser to fetch details for (see Specifying users in request data).

Projects resource

List team projects

Example
Request
GET https://amara.org/api/teams/my-team/projects/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 2
    },
    "objects": [
        {
            "created": "2019-01-30T19:54:26Z",
            "description": "",
            "guidelines": null,
            "modified": "2019-01-30T19:54:26Z",
            "name": "Cat Videos",
            "resource_uri": "https://amara.org/api/teams/my-team/projects/cat-videos/",
            "slug": "cat-videos",
            "workflow_enabled": false
        },
        {
            "created": "2019-01-30T19:54:32Z",
            "description": "",
            "guidelines": null,
            "modified": "2019-01-30T19:54:32Z",
            "name": "Dog Videos",
            "resource_uri": "https://amara.org/api/teams/my-team/projects/dog-videos/",
            "slug": "dog-videos",
            "workflow_enabled": false
        }
    ]
}
GET
/api/teams/[team-slug]/projects/
Response data
namestringProject name.
slugslugSlug for the project.
descriptionstringProject description.
guidelinesstringProject guidelines for users working on it.
creatediso-8601datetime when the project was created.
modifiediso-8601datetime when the project was last changed.
workflow_enabledbooleanAre tasks enabled for this project?
resource_uriuriProject details resource.

Get details on a project

Example
Request
GET https://amara.org/api/teams/my-team/projects/cat-videos/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "created": "2019-01-30T19:54:26Z",
    "description": "",
    "guidelines": null,
    "modified": "2019-01-30T19:54:26Z",
    "name": "Cat Videos",
    "resource_uri": "https://amara.org/api/teams/my-team/projects/cat-videos/",
    "slug": "cat-videos",
    "workflow_enabled": false
}
GET
/api/teams/[team-slug]/projects/[project-slug]

The data is the same as the listing resource.

Create a new project

Example
Request
POST https://amara.org/api/teams/my-team/projects/ HTTP/1.1

{
    "name": "Llama videos",
    "slug": "llama-videos"
}
Response
HTTP/1.1 201 Created

{
    "created": "2019-01-30T19:59:09.988373Z",
    "description": null,
    "guidelines": null,
    "modified": "2019-01-30T19:59:09.987841Z",
    "name": "Llama videos",
    "resource_uri": "https://amara.org/api/teams/my-team/projects/llama-videos/",
    "slug": "llama-videos",
    "workflow_enabled": false
}
POST
/api/teams/[team-slug]/projects/
Request data
name (required)stringProject name.
slug (required)slugSlug for the project.
descriptionstringProject description.
guidelinesstringGuidelines for users working on the project.

Update a project

Example
Request
PUT https://amara.org/api/teams/my-team/projects/llama-videos/ HTTP/1.1

{
    "description": "Collection of the craziest llama videos on the 'net"
}
Response
HTTP/1.1 200 OK

{
    "created": "2019-01-30T19:59:10Z",
    "description": "Collection of the craziest llama videos on the 'net",
    "guidelines": null,
    "modified": "2019-01-30T20:00:11.290201Z",
    "name": "Llama videos",
    "resource_uri": "https://amara.org/api/teams/my-team/projects/llama-videos/",
    "slug": "llama-videos",
    "workflow_enabled": false
}
PUT
/api/teams/[team-slug]/projects/[project-slug]/
Request data
namestringProject name.
descriptionstringProject description.
guidelinesstringGuidelines for users working on the project.

Delete a project

Example
Request
DELETE https://amara.org/api/teams/my-team/projects/llama-videos/ HTTP/1.1
Response
HTTP/1.1 204 No Content
DELETE
/api/teams/[team-slug]/projects/[project-slug]/

Team applications

List applications to your team

Example
Request
GET https://amara.org/api/teams/my-team/applications/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 1
    },
    "objects": [
        {
            "created": "2019-01-30T21:09:33Z",
            "id": 34368,
            "modified": null,
            "note": "Please let me join your team.",
            "resource_uri": "https://amara.org/api/teams/my-team/applications/34368/",
            "status": "Pending",
            "user": {
                "id": "YHg9pnbZwzSajuCD7Uy6_4VicVdhhjnuQxeVcCIGdjg",
                "uri": "https://amara.org/api/users/id$YHg9pnbZwzSajuCD7Uy6_4VicVdhhjnuQxeVcCIGdjg/",
                "username": "bendk2"
            }
        }
    ]
}
GET
/api/teams/[team-slug]/applications/
Query Parameters
statusstringInclude only applications with this status.
beforeintegerInclude only applications submitted before this time (as a unix timestamp).
afterintegerInclude only applications submitted after this time (as a unix timestamp).
useruser identifierInclude only applications from this user (see Specifying users in request data).
Response data
useruser-dataApplicant user data (see User fields).
notestringNote given by the applicant.
statusstringStatus value. Possible values are Denied, Approved, Pending, Member Removed and Member Left.
idintegerApplication ID.
creatediso-8601Creation date/time.
modifiediso-8601Last modified date/time.
resource_uriuriApplication resource.

Get details on an application

Example
Request
GET https://amara.org/api/teams/my-team/applications/34368/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "created": "2019-01-30T21:09:33Z",
    "id": 34368,
    "modified": null,
    "note": "Please let me join your team.",
    "resource_uri": "https://amara.org/api/teams/my-team/applications/34368/",
    "status": "Pending",
    "user": {
        "id": "YHg9pnbZwzSajuCD7Uy6_4VicVdhhjnuQxeVcCIGdjg",
        "uri": "https://amara.org/api/users/id$YHg9pnbZwzSajuCD7Uy6_4VicVdhhjnuQxeVcCIGdjg/",
        "username": "bendk2"
    }
}
GET
[application-uri]

See above for a description of the response data. Get the application-uri from the resource_uri field of the application listing.

Approve/Deny an application

Example
Request
PUT https://amara.org/api/teams/my-team/applications/34368/ HTTP/1.1

{
    "status": "Approved"
}
Response
HTTP/1.1 200 OK

{
    "created": "2019-01-30T21:09:33Z",
    "id": 34368,
    "modified": "2019-01-30T21:19:33.603028Z",
    "note": "Please let me join your team.",
    "resource_uri": "https://amara.org/api/teams/my-team/applications/34368/",
    "status": "Approved",
    "user": {
        "id": "YHg9pnbZwzSajuCD7Uy6_4VicVdhhjnuQxeVcCIGdjg",
        "uri": "https://amara.org/api/users/id$YHg9pnbZwzSajuCD7Uy6_4VicVdhhjnuQxeVcCIGdjg/",
        "username": "bendk2"
    }
}
PUT
[application-uri]
Request data
statusstringDenied to deny the application. Approved to approve it.

Get the application-uri from the resource_uri field of the application listing.

Team Languages

Preferred languages

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.

Team HTTP callbacks

Enterprise customers can register a URL for http callbacks so that activity on their teams will fire an HTTP POST requests to that URL.

To register your Team to receive HTTP notifications, please send your request to us at enterprise@amara.org and we will set it up for you. You can also contact us with inquiry about any custom notifications that are not listed in our general offering below.

Please indicate a URL where you’d like to get notified. Each team can have their own URL, or a common URL can be used for several teams. We recommend that the selected URL uses HTTPS protocol for safer communication.

Notification data

Here is the data we include in our HTTP callbacks. All callbacks are encoded as JSON. We can also customize the data per-partner. Please contact us for details.

General data

Generic notification data
primary_teamslugTeam the notification was registered for.
numberintegerNotification number. This will increment by 1 for each notification. You can use this number to keep track of notifications and ensure that you don't miss any.

Video notifications

Video notification data
eventstringevent type (see below for details).
amara_video_idstringAmara Video ID.
youtube_video_idstringYouTube video ID, or null if the video is not hosted on YouTube.
teamslugTeam the video is in.
projectslugProject the video is in.
Event types for videos
video-addedSent when a video is added to your team, or moved to your team from another team. Additional data: old_team (if video is moved from another team)
video-removedSent when a video is removed from your team, or moved to another team. Additional data: new_team (if video is moved to another team)
video-made-primarySent when one of the multiple URLs for a video on your team is set as the primary URL. Additional data: url
video-moved-projectSent when a video on your team is moved to a different project. Additional data: old_project
subtitles-publishedSent when a new subtitle version for a video on your team is published. Additional data: language_code, amara_version
subtitle-unpublishedSent when subtitles are deleted for a video on your team. Additional data: language_code

Team member notifications

Team member notification data
eventstringEvent type (see below for details).
usernamestringTeam member username.
teamstringTeam member team.
Event types for team members
member-addedSent when a user is added to your team
member-removedSent when a user is removed from your team
member-profile-changedSent when the information in a team member's profile is changed

API endpoints

List team notifications

Example
Request
GET https://amara.org/api/teams/my-team/notifications/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "meta": {
        "limit": 20,
        "next": "https://amara.org/api/teams/my-team/notifications/?limit=20&offset=20",
        "offset": 0,
        "previous": null,
        "total_count": 2
    },
    "objects": [
        {
            "data": {
                "event": "member-profile-changed",
                "number": 396,
                "team": "my-team",
                "username": "bendk"
            },
            "in_progress": false,
            "number": 2,
            "resource_uri": "https://amara.org/api/teams/my-team/notifications/396/",
            "response_status": 403,
            "timestamp": "2019-01-30T14:52:27Z",
            "url": "https://example.com/amara-notification/"
        },
        {
            "data": {
                "amara_version": 11,
                "amara_video_id": "w4M38DmXJtNt",
                "event": "subtitles-published",
                "language_code": "ru",
                "number": 395,
                "project": "my-project",
                "team": "my-team",
                "youtube_video_id": null
            },
            "error_message": "Response status: 403",
            "in_progress": false,
            "number": 1,
            "resource_uri": "https://amara.org/api/teams/my-team/notifications/395/",
            "response_status": 403,
            "timestamp": "2019-01-29T09:37:37Z",
            "url": "https://example.com/amara-notification/"
        }
    ]
}
GET
/api/teams/[team-slug]/notifications/
Response data
numberintegerNotification number.
urlurlURL of the POST request.
dataobjectData that we posted to the URL.
timestampiso-8601Date/time the notification was sent.
in_progressbooleanIs the request still in progress?
response_statusintegerHTTP response status code (or null).
error_messagestringString describing any errors that occured.
resource_uriuriLink to the details endpoint for the notification.

Get details on one notification

Example
Request
GET https://amara.org/api/teams/my-team/notifications/100/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "data": {
        "amara_video_id": "rpPT7YUOULVY",
        "event": "video-made-primary",
        "number": 100,
        "project": "my-project",
        "team": "my-team",
        "url": "https://example.com/video.mp4",
        "youtube_video_id": null
    },
    "in_progress": false,
    "number": 100,
    "resource_uri": "https://amara.org/api/teams/my-team/notifications/100/",
    "response_status": 403,
    "timestamp": "2017-12-20T20:36:31Z",
    "url": "https://example.com/amara-callback/"
}
GET
/api/teams/[team-slug]/notifications/[number]/

The data is the same as the team notifications list endpoint.

Tasks

This is used for old-style teams to manage work. Collaboration teams should use the Subtitles requests resource instead.

List tasks for a team

GET
/api/teams/[team-slug]/tasks/
Query Parameters
assigneeuser identifierUser to fetch details for (see Specifying users in request data).
priorityintegerShow only tasks with a given priority.
typestringShow only tasks of a given type.
video_idvideo-idShow only tasks that pertain to a given video.
completedbooleanShow only complete tasks.
completed-beforeintegerShow only tasks completed before a given date (as a unix timestamp).
completed-afterintegerShow only tasks completed before a given date (as a unix timestamp).
openbooleanShow only incomplete tasks.
order_byenumOrdering (see below).
order_by values
createdCreation date
-createdCreation date (descending)
modifiedLast update date
-modifiedLast update date (descending)
priorityPriority
-priorityPriority (descending)
typeTask type (details below)
-typeTask type (descending)
Response data
video_idvideo-idID of the video being worked on.
languagebcp-47Language code being worked on.
idintegerID for the task.
typestringType of task. Possible values: Subtitle, Translate, Review, or Approve.
assigneeuser-dataTask assignee (see User fields).
priorityintegerPriority for the task.
creatediso-8601Date/time when the task was created.
modifiediso-8601Date/time when the task was last updated.
completediso-8601Date/time when the task was completed (or null).
approvedstringApproval status of the task. Possible values: In Progress, Approved, or Rejected.
resource_uriuriTask resource link.

Get details on a specific task

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

See above for a description of the response data.

Create a new task

POST
/api/teams/[team-slug]/tasks/
Request data
video_id (required)video-idVideo ID.
language (required)bcp-47language code.
type (required)stringtask type to create. Must be Subtitle or Translate.
assigneeuser identifierUser to fetch details for (see Specifying users in request data).
priorityintegerPriority for the task.

Update an existing task

PUT
/api/teams/[team-slug]/tasks/[task-id]/
Request data
assigneeuser identifierUser to fetch details for (see Specifying users in request data).
priorityintegerPriority of the task.
send_backbooleanSend a truthy value to send the back back.
completebooleanSend a truthy value to complete/approve the task.
version_numberintegerSpecify the version number of the subtitles that were created for this task.
Note
If both send_back and approved are specified, then send_back will take preference. Delete an existing task

Delete a task

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

Subtitle requests

Subtitle requests are used by collaboration teams to track work on a video's subtitles. They are are extremely flexible and can involve multiple teams working together on a request.

This section is split up into 2 parts:

  • The first part describes the normal case where only 1 team is involved.
  • The second section describes the more complex case where multiple teams are involved in subtitle requests.

Single team

List Requests

Example
Request
GET https://amara.org/api/teams/my-team/subtitle-requests/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 4
    },
    "objects": [
        {
            "actions_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/ar/subtitles/actions/",
            "approver": null,
            "completed": null,
            "created": "2017-12-12T16:25:00Z",
            "due_date": null,
            "evaluation_teams": [],
            "job_id": "HKSUEX2",
            "language": "ar",
            "resource_uri": "https://amara.org/api/teams/my-team/subtitle-requests/HKSUEX2/",
            "reviewer": null,
            "source_team": "my-team",
            "status": "in-progress",
            "subtitler": null,
            "subtitles_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/ar/subtitles/",
            "team": "my-team",
            "video": "wmLoWX91VsJ8",
            "video_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/",
            "work_completed": null,
            "work_status": "needs-subtitler"
        },
        {
            "actions_uri": "https://amara.org/api/videos/bTCCPqZ5hDfA/languages/en/subtitles/actions/",
            "approver": null,
            "created": "2017-06-22T20:46:49Z",
            "due_date": null,
            "job_id": "EM1VLR4",
            "language": "en",
            "resource_uri": "https://amara.org/api/teams/my-team/subtitle-requests/EM1VLR4/",
            "reviewer": null,
            "source_team": null,
            "subtitler": {
                "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
                "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
                "username": "bendk"
            },
            "subtitles_uri": "https://amara.org/api/videos/bTCCPqZ5hDfA/languages/en/subtitles/",
            "video": "bTCCPqZ5hDfA",
            "video_uri": "https://amara.org/api/videos/bTCCPqZ5hDfA/",
            "work_completed": null,
            "work_status": "being-subtitled"
        },
        {
            "actions_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/fr/subtitles/actions/",
            "approver": null,
            "completed": null,
            "created": "2015-08-28T18:14:48Z",
            "due_date": null,
            "evaluation_teams": [],
            "job_id": "9TAM45J",
            "language": "fr",
            "resource_uri": "https://amara.org/api/teams/my-team/subtitle-requests/9TAM45J/",
            "reviewer": null,
            "source_team": "my-team",
            "status": "in-progress",
            "subtitler": null,
            "subtitles_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/fr/subtitles/",
            "team": "my-team",
            "video": "wmLoWX91VsJ8",
            "video_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/",
            "work_completed": null,
            "work_status": "needs-subtitler"
        },
        {
            "actions_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/en/subtitles/actions/",
            "approver": null,
            "completed": "2016-07-26T18:09:52Z",
            "created": "2015-08-28T18:14:43Z",
            "due_date": null,
            "evaluation_completed": null,
            "evaluation_status": "complete",
            "evaluation_teams": [
                "my-team"
            ],
            "evaluator": null,
            "job_id": "0HRVT57",
            "language": "en",
            "resource_uri": "https://amara.org/api/teams/my-team/subtitle-requests/0HRVT57/",
            "reviewer": null,
            "source_team": "my-team",
            "status": "complete",
            "subtitler": {
                "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
                "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
                "username": "bendk"
            },
            "subtitles_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/en/subtitles/",
            "team": "my-team",
            "video": "wmLoWX91VsJ8",
            "video_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/",
            "work_completed": null,
            "work_status": "complete"
        }
    ]
}
GET
/api/teams/[team-slug]/subtitle-requests/

List results are paginated.

Query Parameters
work_statusenumFilter by the status of work on the subtitles. See below for possible values.
videovideo-idFilter by video ID.
video_titlestringFilter by video title.
video_languagebcp-47Filter by video language.
languagebcp-47Filter by subtitle request language.
projectslugFilter by team project.
assigneeusernameFilter by assignee.
sortenumSort order. Defaults to -creation. See below for values.
Subtitle request data
job_idjob-idID for the request.
videovideo-idVideo ID for the request.
languagebcp-47Language code of the subtitle request.
work_statusenumStatus of work on the subtitles. See below for possible values.
creatediso-8601when the request was created.
work_completediso-8601when the subittle work was completed, or null.
subtitleruserUser creating the subtitles (see User fields).
revieweruserUser reviewing the subtitles (see User fields).
approveruserUser approving the subtitles (see User fields).
video_uriuriVideo API resource.
subtitles_uriuriSubtitles resource.
actions_uriuriSubtitle actions resource.
resource_uriuriSubtitle request details resource.
Work status values
in-progressWork in progress
availableAssignment currently available
assignedAssignment in progress
needs-subtitlerTranscribe/translate assignment available
being-subtitledTranscribe/translate assignment in progress
needs-reviewerReview assignment available
being-reviewedReview assignment in progress
needs-approverApproval assignment available
being-approvedApproval assignment in progress
completeSubtitles complete
Sort order values
-creationCreation date/time (latest first)
creationCreation date/time (earliest first)
-dueDue date/time (latest first)
dueDue date/time (earliest first)
-completionLatest completion date/time (latest first)
completionLatest completion date/time (earliest first)

Get details on a request

Example
Request
GET https://amara.org/api/teams/my-team/subtitle-requests/0HRVT57/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "actions_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/en/subtitles/actions/",
    "approver": null,
    "completed": "2016-07-26T18:09:52Z",
    "created": "2015-08-28T18:14:43Z",
    "due_date": null,
    "evaluation_completed": null,
    "evaluation_status": "complete",
    "evaluation_teams": [],
    "evaluator": null,
    "job_id": "0HRVT57",
    "language": "en",
    "resource_uri": "https://amara.org/api/teams/my-team/subtitle-requests/0HRVT57/",
    "reviewer": null,
    "source_team": "my-team",
    "status": "complete",
    "subtitler": {
        "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
        "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
        "username": "bendk"
    },
    "subtitles_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/en/subtitles/",
    "team": "my-team",
    "video": "wmLoWX91VsJ8",
    "video_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/",
    "work_completed": null,
    "work_status": "complete"
}
GET
/api/teams/[team-slug]/subtitle-requests/[job-id]/

The subtitle request data is the same as the listing endpoint

Create a request

Example
Request
POST https://amara.org/api/teams/my-team/subtitle-requests/ HTTP/1.1

{
    "language": "ru",
    "video": "wmLoWX91VsJ8"
}
Response
HTTP/1.1 201 Created

{
    "actions_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/ru/subtitles/actions/",
    "approver": null,
    "completed": null,
    "created": "2019-01-30T23:22:38.694080Z",
    "due_date": null,
    "evaluation_teams": [],
    "job_id": "C40JFAO",
    "language": "ru",
    "resource_uri": "https://amara.org/api/teams/my-team/subtitle-requests/C40JFAO/",
    "reviewer": null,
    "source_team": "my-team",
    "status": "in-progress",
    "subtitler": null,
    "subtitles_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/ru/subtitles/",
    "team": "my-team",
    "video": "wmLoWX91VsJ8",
    "video_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/",
    "work_completed": null,
    "work_status": "needs-subtitler"
}
POST
/api/teams/[team-slug]/subtitle-requests/
Request data
videovideo-idVideo ID. This must be part of the team identified in the URL path.
languagebcp-47Language code for the subtitles.
due_dateiso-8601Due date for the request.

You must be an admin of the team to create a subtitle request.

Update a request

Example

Assign a subtitle requests

Request
PUT https://amara.org/api/teams/my-team/subtitle-requests/C40JFAO/ HTTP/1.1

{
    "subtitler": "bendk"
}
Response
HTTP/1.1 200 OK

{
    "actions_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/ru/subtitles/actions/",
    "approver": null,
    "completed": null,
    "created": "2019-01-30T23:22:39Z",
    "due_date": null,
    "evaluation_teams": [],
    "job_id": "C40JFAO",
    "language": "ru",
    "resource_uri": "https://amara.org/api/teams/my-team/subtitle-requests/C40JFAO/",
    "reviewer": null,
    "source_team": "my-team",
    "status": "in-progress",
    "subtitler": {
        "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
        "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
        "username": "bendk"
    },
    "subtitles_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/ru/subtitles/",
    "team": "my-team",
    "video": "wmLoWX91VsJ8",
    "video_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/",
    "work_completed": null,
    "work_status": "being-subtitled"
}
Example

Unassign a request

Request
PUT https://amara.org/api/teams/my-team/subtitle-requests/C40JFAO/ HTTP/1.1

{
    "subtitler": null
}
Response
HTTP/1.1 200 OK

{
    "actions_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/ru/subtitles/actions/",
    "approver": null,
    "completed": null,
    "created": "2019-01-30T23:22:39Z",
    "due_date": null,
    "evaluation_teams": [],
    "job_id": "C40JFAO",
    "language": "ru",
    "resource_uri": "https://amara.org/api/teams/my-team/subtitle-requests/C40JFAO/",
    "reviewer": null,
    "source_team": "my-team",
    "status": "in-progress",
    "subtitler": null,
    "subtitles_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/ru/subtitles/",
    "team": "my-team",
    "video": "wmLoWX91VsJ8",
    "video_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/",
    "work_completed": null,
    "work_status": "needs-subtitler"
}
Example

Mark a request complete

Request
PUT https://amara.org/api/teams/my-team/subtitle-requests/CYAPTOZ/ HTTP/1.1

{
    "work_status": "complete"
}
Response
HTTP/1.1 200 OK

{
    "actions_uri": "https://amara.org/api/videos/Ey8lIpigXjRR/languages/en/subtitles/actions/",
    "approver": null,
    "completed": "2019-01-30T23:39:23.588554Z",
    "created": "2019-01-30T23:38:42Z",
    "due_date": null,
    "evaluation_teams": [],
    "job_id": "CYAPTOZ",
    "language": "en",
    "resource_uri": "https://amara.org/api/teams/my-team/subtitle-requests/CYAPTOZ/",
    "reviewer": null,
    "source_team": "my-team",
    "status": "complete",
    "subtitler": {
        "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
        "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
        "username": "bendk"
    },
    "subtitles_uri": "https://amara.org/api/videos/Ey8lIpigXjRR/languages/en/subtitles/",
    "team": "my-team",
    "video": "Ey8lIpigXjRR",
    "video_uri": "https://amara.org/api/videos/Ey8lIpigXjRR/",
    "work_completed": "2019-01-30T23:39:23.588554Z",
    "work_status": "complete"
}
PUT
/api/teams/[team-slug]/subtitle-requests/[job-id]/
Request data
subtitleruserUser to assign as the subtitler, or null to unassign the current subtitler (see Specifying users in request data).
revieweruserUser to assign as the reviewer, or null to unassign the current reviewer (see Specifying users in request data).
approveruserUser to assign as the approver, or null to unassign the current approver (see Specifying users in request data).
work_statusenumSet to complete to mark the subtitles complete. This is the only value we currently support.
due_dateiso-8601Due date for the request.

Delete a request

Example
Request
DELETE https://amara.org/api/teams/my-team/subtitle-requests/CYAPTOZ/ HTTP/1.1
Response
HTTP/1.1 204 No Content
DELETE
/api/teams/[team-slug]/subtitle-requests/[job-id]/

Multi-team

This section describes the API for multiple teams working together on a single request.

Team Terminology

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

Term Description
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.

When the docs say something like "source team only", it means only if the team identified by `[team-slug]' in the URl is the source team.

Note
The source team may also be the work team or an evaluation team for a request.

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 values
in-progressinitial work in progress
in-evaluationevaluation in progress
in-evaluation11st evaluation in progress
in-evaluation22nd evaluation in progress
in-evaluation[N]Nth evaluation in progress
completeall work complete
work_status values
needs-subtitlertranscribe/translate assignment available
being-subtitledtranscribe/translate assignment in progress
needs-reviewerreview assignment available
being-reviewedreview assignment in progress
needs-approverapproval assignment available
being-approvedapproval assignment in progress
completeinitial work complete
in-progressinitial work in progress
availableassignment currently available
assignedassignment in progress
evaluation_status values
upcomingevaluation not ready to be started
availableevaluation assignment currently available
assignedevaluation assignment in progress
completeevaluation complete

List Requests

Example
Request
GET https://amara.org/api/teams/my-team/subtitle-requests/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "meta": {
        "limit": 20,
        "next": null,
        "offset": 0,
        "previous": null,
        "total_count": 4
    },
    "objects": [
        {
            "actions_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/ar/subtitles/actions/",
            "approver": null,
            "completed": null,
            "created": "2017-12-12T16:25:00Z",
            "due_date": null,
            "evaluation_teams": [],
            "job_id": "HKSUEX2",
            "language": "ar",
            "resource_uri": "https://amara.org/api/teams/my-team/subtitle-requests/HKSUEX2/",
            "reviewer": null,
            "source_team": "my-team",
            "status": "in-progress",
            "subtitler": null,
            "subtitles_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/ar/subtitles/",
            "team": "my-team",
            "video": "wmLoWX91VsJ8",
            "video_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/",
            "work_completed": null,
            "work_status": "needs-subtitler"
        },
        {
            "actions_uri": "https://amara.org/api/videos/bTCCPqZ5hDfA/languages/en/subtitles/actions/",
            "approver": null,
            "created": "2017-06-22T20:46:49Z",
            "due_date": null,
            "job_id": "EM1VLR4",
            "language": "en",
            "resource_uri": "https://amara.org/api/teams/my-team/subtitle-requests/EM1VLR4/",
            "reviewer": null,
            "source_team": null,
            "subtitler": {
                "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
                "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
                "username": "bendk"
            },
            "subtitles_uri": "https://amara.org/api/videos/bTCCPqZ5hDfA/languages/en/subtitles/",
            "video": "bTCCPqZ5hDfA",
            "video_uri": "https://amara.org/api/videos/bTCCPqZ5hDfA/",
            "work_completed": null,
            "work_status": "being-subtitled"
        },
        {
            "actions_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/fr/subtitles/actions/",
            "approver": null,
            "completed": null,
            "created": "2015-08-28T18:14:48Z",
            "due_date": null,
            "evaluation_teams": [],
            "job_id": "9TAM45J",
            "language": "fr",
            "resource_uri": "https://amara.org/api/teams/my-team/subtitle-requests/9TAM45J/",
            "reviewer": null,
            "source_team": "my-team",
            "status": "in-progress",
            "subtitler": null,
            "subtitles_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/fr/subtitles/",
            "team": "my-team",
            "video": "wmLoWX91VsJ8",
            "video_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/",
            "work_completed": null,
            "work_status": "needs-subtitler"
        },
        {
            "actions_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/en/subtitles/actions/",
            "approver": null,
            "completed": "2016-07-26T18:09:52Z",
            "created": "2015-08-28T18:14:43Z",
            "due_date": null,
            "evaluation_completed": null,
            "evaluation_status": "complete",
            "evaluation_teams": [
                "my-team"
            ],
            "evaluator": null,
            "job_id": "0HRVT57",
            "language": "en",
            "resource_uri": "https://amara.org/api/teams/my-team/subtitle-requests/0HRVT57/",
            "reviewer": null,
            "source_team": "my-team",
            "status": "complete",
            "subtitler": {
                "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
                "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
                "username": "bendk"
            },
            "subtitles_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/en/subtitles/",
            "team": "my-team",
            "video": "wmLoWX91VsJ8",
            "video_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/",
            "work_completed": null,
            "work_status": "complete"
        }
    ]
}
GET
/api/teams/[team-slug]/subtitle-requests/

List results are paginated.

Query Parameters
typeenumFilter by request type. Defaults to local (see below for details).
statusenumFilter by the overall status (see the request status fields section).
work_statusenumFilter by work team status. (see the request status fields section).
evaluation_statusenumFilter by evaluation team status. (see the request status fields section).
videovideo-idFilter by video ID.
video_titlestringFilter by video title.
video_languagebcp-47Filter by video language.
languagebcp-47Filter by subtitle request language.
projectslugFilter by team project.
assigneeusernameFilter by assignee.
sortenumSort order. Defaults to -creation. See below for values.
type filter values
localThe simple case, requests where the team is both the source and work team.
outgoingRequest where the team is the source team, but not the work team.
incomingRequest where the team is the work team, but not the source team.
evaluationsRequest where the team is an evaluation team.
Response data for all teams
job_idjob-idID for the request.
videovideo-idVideo for the request.
languagebcp-47Language code of the subtitle request.
source_teamslugTeam that the video is part of.
teamslugTeam handling the request.
evaluation_teamslist of slugsTeam evaluating the request. Only present for requests for the team’s videos.
creatediso-8601When the request was created.
video_uriuriVideo API resource.
subtitles_uriuriSubtitles resource.
actions_uriuriSubtitle actions resource.
resource_uriuriSubtitle request details resource.
Extra data for the source team
statusenumOverall request status. (see the request status fields section).
completediso-8601(source team only) when the entire request was completed, or null.
Extra data for the work team
work_statusenumWork status (see the request status fields section).
subtitleruserUser creating the subtitles (see User fields).
revieweruserUser reviewing the subtitles (see User fields).
approveruserUser approving the subtitles (see User fields).
work_completediso-8601when the initial work was completed, or null.
Extra data for evaluation teams
evaluation_statusenumEvaluation status (see the request status fields section).
evaluatoruserUser evaluating the subtitles (see User fields).
evaluation_completediso-8601when the initial work was completed, or null.

Get details on a request

Example
Request
GET https://amara.org/api/teams/my-team/subtitle-requests/0HRVT57/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "actions_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/en/subtitles/actions/",
    "approver": null,
    "completed": "2016-07-26T18:09:52Z",
    "created": "2015-08-28T18:14:43Z",
    "due_date": null,
    "evaluation_completed": null,
    "evaluation_status": "complete",
    "evaluation_teams": [],
    "evaluator": null,
    "job_id": "0HRVT57",
    "language": "en",
    "resource_uri": "https://amara.org/api/teams/my-team/subtitle-requests/0HRVT57/",
    "reviewer": null,
    "source_team": "my-team",
    "status": "complete",
    "subtitler": {
        "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
        "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
        "username": "bendk"
    },
    "subtitles_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/en/subtitles/",
    "team": "my-team",
    "video": "wmLoWX91VsJ8",
    "video_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/",
    "work_completed": null,
    "work_status": "complete"
}
GET
/api/teams/[team-slug]/subtitle-requests/[job-id]/

The data is the same as above.

Create a request

Example
Request
POST https://amara.org/api/teams/my-team/subtitle-requests/ HTTP/1.1

{
    "language": "ru",
    "video": "wmLoWX91VsJ8"
}
Response
HTTP/1.1 201 Created

{
    "actions_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/ru/subtitles/actions/",
    "approver": null,
    "completed": null,
    "created": "2019-01-30T23:22:38.694080Z",
    "due_date": null,
    "evaluation_teams": [],
    "job_id": "C40JFAO",
    "language": "ru",
    "resource_uri": "https://amara.org/api/teams/my-team/subtitle-requests/C40JFAO/",
    "reviewer": null,
    "source_team": "my-team",
    "status": "in-progress",
    "subtitler": null,
    "subtitles_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/ru/subtitles/",
    "team": "my-team",
    "video": "wmLoWX91VsJ8",
    "video_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/",
    "work_completed": null,
    "work_status": "needs-subtitler"
}
POST
/api/teams/[team-slug]/subtitle-requests/
Request data
videovideo-idVideo ID. This must be part of the team identified in the URL path.
languagebcp-47Language code for the subtitles.
due_dateiso-8601Due date for the request.
teamslugWork team. This can be any team you are an admin of (defaults to the video's team).
evaluation_teamslist of slugsList of evaluation teams. They can be any team you are an admin of (defaults to the empty list).

Update a request

Example

Assign a subtitle requests

Request
PUT https://amara.org/api/teams/my-team/subtitle-requests/C40JFAO/ HTTP/1.1

{
    "subtitler": "bendk"
}
Response
HTTP/1.1 200 OK

{
    "actions_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/ru/subtitles/actions/",
    "approver": null,
    "completed": null,
    "created": "2019-01-30T23:22:39Z",
    "due_date": null,
    "evaluation_teams": [],
    "job_id": "C40JFAO",
    "language": "ru",
    "resource_uri": "https://amara.org/api/teams/my-team/subtitle-requests/C40JFAO/",
    "reviewer": null,
    "source_team": "my-team",
    "status": "in-progress",
    "subtitler": {
        "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
        "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
        "username": "bendk"
    },
    "subtitles_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/ru/subtitles/",
    "team": "my-team",
    "video": "wmLoWX91VsJ8",
    "video_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/",
    "work_completed": null,
    "work_status": "being-subtitled"
}
Example

Unassign a request

Request
PUT https://amara.org/api/teams/my-team/subtitle-requests/C40JFAO/ HTTP/1.1

{
    "subtitler": null
}
Response
HTTP/1.1 200 OK

{
    "actions_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/ru/subtitles/actions/",
    "approver": null,
    "completed": null,
    "created": "2019-01-30T23:22:39Z",
    "due_date": null,
    "evaluation_teams": [],
    "job_id": "C40JFAO",
    "language": "ru",
    "resource_uri": "https://amara.org/api/teams/my-team/subtitle-requests/C40JFAO/",
    "reviewer": null,
    "source_team": "my-team",
    "status": "in-progress",
    "subtitler": null,
    "subtitles_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/languages/ru/subtitles/",
    "team": "my-team",
    "video": "wmLoWX91VsJ8",
    "video_uri": "https://amara.org/api/videos/wmLoWX91VsJ8/",
    "work_completed": null,
    "work_status": "needs-subtitler"
}
Example

Mark a request complete

Request
PUT https://amara.org/api/teams/my-team/subtitle-requests/CYAPTOZ/ HTTP/1.1

{
    "work_status": "complete"
}
Response
HTTP/1.1 200 OK

{
    "actions_uri": "https://amara.org/api/videos/Ey8lIpigXjRR/languages/en/subtitles/actions/",
    "approver": null,
    "completed": "2019-01-30T23:39:23.588554Z",
    "created": "2019-01-30T23:38:42Z",
    "due_date": null,
    "evaluation_teams": [],
    "job_id": "CYAPTOZ",
    "language": "en",
    "resource_uri": "https://amara.org/api/teams/my-team/subtitle-requests/CYAPTOZ/",
    "reviewer": null,
    "source_team": "my-team",
    "status": "complete",
    "subtitler": {
        "id": "67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8",
        "uri": "https://amara.org/api/users/id$67oVmk_e_pxUfvha1Eg589UjELUa72jiKfBJCAUivL8/",
        "username": "bendk"
    },
    "subtitles_uri": "https://amara.org/api/videos/Ey8lIpigXjRR/languages/en/subtitles/",
    "team": "my-team",
    "video": "Ey8lIpigXjRR",
    "video_uri": "https://amara.org/api/videos/Ey8lIpigXjRR/",
    "work_completed": "2019-01-30T23:39:23.588554Z",
    "work_status": "complete"
}
PUT
/api/teams/[team-slug]/subtitle-requests/[job-id]/
Source team fields
teamslugChange the work team. This is only possible if work has not been started.
evaluation_teamsslug(source team only) Change the evaluation teams. This is only possible if evaluations have not been started.
due_dateiso-8601Due date for the request.
Work team fields
subtitleruserUser to assign as the subtitler, or null to unassign the current subtitler (see Specifying users in request data).
revieweruserUser to assign as the reviewer, or null to unassign the current reviewer (see Specifying users in request data).
approveruserUser to assign as the approver, or null to unassign the current approver (see Specifying users in request data).
work_statusenumSet to complete to mark the subtitles complete. This is the only value we currently support.
Evaluation team fields
evaluatoruserUser to assign as the evaluator, or null to unassign the current evaluator (see Specifying users in request data).

Delete a request

Example
Request
DELETE https://amara.org/api/teams/my-team/subtitle-requests/CYAPTOZ/ HTTP/1.1
Response
HTTP/1.1 204 No Content
DELETE
/api/teams/[team-slug]/subtitle-requests/[job-id]/

Only admins from the source team can delete a request.

Languages

List available languages

Example
Request
GET https://amara.org/api/languages/ HTTP/1.1
Response
HTTP/1.1 200 OK

{
    "languages": {
        "aa": "Afar",
        "ab": "Abkhazian",
        "ace": "Acehnese",
        "ae": "Avestan",
        "aeb": "Tunisian Arabic",
        "af": "Afrikaans",
        "aka": "Akan",
        "amh": "Amharic",
        "ami": "Amis",
        "an": "Aragonese",
        ...
        "zza": "Zazaki"
    }
}
GET
/api/languages/

Get a list of all supported languages for the Amara platform.