<commit_before>API Documentation
=================

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

.. note:: The v1 of the API is deprecated, but can still be accessed through
    http://www.universalsubtitles.org/api/1.0/documentation/ . Users should migrate
    to the v2 of the API. If you're missing a feature on the API, please `let us
    know <https://universalsubtitles.tenderapp.com/>`_ .

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
<http://www.universalsubtitles.org/en/profiles/edit/>`_ page. At the bottom of
the page you will find a "Generate new key" button . Clicking on it will fetch
your user the needed API key.

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

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

So a sample request would look like this::

   $ curl  -H 'X-api-username: site_username' -H 'X-apikey: the_apy_key'  https://staging.universalsubtitles.org/api2/partners/videos/

Data Formats
------------

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

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

    Accept: application/json

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

API endpoint
------------

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

Possible environments:

* Staging: https://staging.universalsubtitles.org/
* Production: https://www.universalsubtitles.org/

Therefore, most clients should be making requests against:
https://www.universalsubtitles.org/api2/partners/

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

    $ curl  -H 'X-api-username: site_username' -H 'X-apikey: the_apy_key' --user basic_auth_username:basic_auth_password https://staging.universalsubtitles.org/api2/partners/videos/

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

Available Resources
-------------------

The following resources are available to end users:

VideoResource
~~~~~~~~~~~~~

Represents a video on Amara.

Listing videos::

    GET https://www.universalsubtitles.org/api2/partners/videos/

Parameters:

  * `video_url`: list only videos with the given URL, useful for finding out information about a video already on Amara.
  * `order_by`: Applies sorting to the video list. Possible values:

    * `title`: ascending
    * `-title`: descending
    * `created`: older videos first
    * `-created` : newer videos

Creating Videos::

  POST https://www.universalsubtitles.org/api2/partners/videos/

Parameters:

  * `video_url` : The url for the video. Any url that Amara accepts will work here. You can send the URL for a file (e.g. http:///www.example.com/my-video.ogv) , or a link to one of our accepted providers (youtube, vimeo, dailymotion, blip.tv)
  * `title` : The title for the video
  * `description` : About this video
  * `duration` : Duration in seconds

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

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

Video Detail::

  GET https://www.universalsubtitles.org/api2/partners/videos/[video-id]/

The video listing resource already returns a `resource_uri` for each video to
be used when retrieving the details.<commit_msg>Document filtering by team and project<commit_after>API Documentation
=================

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

.. note:: The v1 of the API is deprecated, but can still be accessed through
    http://www.universalsubtitles.org/api/1.0/documentation/ . Users should migrate
    to the v2 of the API. If you're missing a feature on the API, please `let us
    know <https://universalsubtitles.tenderapp.com/>`_ .

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
<http://www.universalsubtitles.org/en/profiles/edit/>`_ page. At the bottom of
the page you will find a "Generate new key" button . Clicking on it will fetch
your user the needed API key.

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

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

So a sample request would look like this::

   $ curl  -H 'X-api-username: site_username' -H 'X-apikey: the_apy_key'  https://staging.universalsubtitles.org/api2/partners/videos/

Data Formats
------------

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

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

    Accept: application/json

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

API endpoint
------------

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

Possible environments:

* Staging: https://staging.universalsubtitles.org/
* Production: https://www.universalsubtitles.org/

Therefore, most clients should be making requests against:
https://www.universalsubtitles.org/api2/partners/

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

    $ curl  -H 'X-api-username: site_username' -H 'X-apikey: the_apy_key' --user basic_auth_username:basic_auth_password https://staging.universalsubtitles.org/api2/partners/videos/

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

Available Resources
-------------------

The following resources are available to end users:

VideoResource
~~~~~~~~~~~~~

Represents a video on Amara.

Listing videos::

    GET https://www.universalsubtitles.org/api2/partners/videos/

Parameters:

  * `video_url`: list only videos with the given URL, useful for finding out information about a video already on Amara.
  * `order_by`: Applies sorting to the video list. Possible values:

    * `title`: ascending
    * `-title`: descending
    * `created`: older videos first
    * `-created` : newer videos

  * `team`: Only show videos that belong to a team identified by ``slug``.
  * `project`: Only show videos that belong to a project with the given slug.
    Passing in ``null`` will return only videos that don't belong to a project.

Creating Videos::

  POST https://www.universalsubtitles.org/api2/partners/videos/

Parameters:

  * `video_url` : The url for the video. Any url that Amara accepts will work here. You can send the URL for a file (e.g. http:///www.example.com/my-video.ogv) , or a link to one of our accepted providers (youtube, vimeo, dailymotion, blip.tv)
  * `title` : The title for the video
  * `description` : About this video
  * `duration` : Duration in seconds

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

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

Video Detail::

  GET https://www.universalsubtitles.org/api2/partners/videos/[video-id]/

The video listing resource already returns a `resource_uri` for each video to
be used when retrieving the details.
{'fraction_non_alphanumeric': 0.09728586535072259, 'fraction_numerical': 0.003054870168017859, 'mean_word_length': 3.7874015748031495, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 18, 'lorem ipsum': 0, 'www.': 16, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '856733', 'n_tokens_mistral': 2490, 'n_tokens_neox': 2400, 'n_words': 1082}