\nThis is an ongoing effort to provide an API for tatoeba.org.\nThis API is currently read-only, but open to the public without authentification.\nFeedback is welcome.\n
\n\nEndpoints can be divided in two categories.\n
/v1 prefix: it is safe to build upon them./unstable prefix: these may change at any point\n in the future, in terms of behavior, required parameters or response format./unstable to /v1. For backward compatibility,\nall /v1 endpoints can also be used with /unstable prefix instead.\n",
"contact": {
"name": "API support",
"email": "team@tatoeba.org"
},
"version": "1.0"
},
"servers": [
{
"url": "https://api.tatoeba.org",
"description": "Tatoeba's production server"
},
{
"url": "https://api.dev.tatoeba.org",
"description": "Tatoeba's development server"
}
],
"paths": {
"/v1/audios/{id}/file": {
"get": {
"tags": [
"Audio"
],
"summary": "Get an audio file",
"description": "Download an audio recording of a sentence.",
"operationId": "8372deb69b48176795eaea0c45b3267d",
"responses": {
"200": {
"description": "Success."
},
"400": {
"description": "Invalid parameter."
},
"403": {
"description": "The audio author does not allow reuse outside of Tatoeba."
},
"404": {
"description": "There is no audio with that ID, or it was removed."
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"description": "The audio identifier.",
"required": true,
"schema": {
"$ref": "#/components/schemas/Audio/properties/id"
}
}
]
},
"/unstable/audios": {
"get": {
"tags": [
"Audio"
],
"summary": "Search audio recordings",
"description": "Get the list of all audio recordings matching criteria.",
"operationId": "1461cd9e56c89d0a7160a248524cb632",
"responses": {
"200": {
"description": "Success.",
"content": {
"application/json": {
"schema": {
"properties": {
"data": {
"description": "Array of audio objects matching the provided filters.",
"type": "array",
"items": {
"$ref": "#/components/schemas/AudioWithExtraInfo"
}
},
"paging": {
"$ref": "#/components/schemas/Paging"
}
},
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/ClientErrorResponse"
},
"500": {
"$ref": "#/components/responses/ServerErrorResponse"
}
}
},
"parameters": [
{
"name": "lang",
"in": "query",
"description": "Only return audio recordings in that language.",
"schema": {
"$ref": "#/components/schemas/LanguageCode"
},
"examples": {
"1": {
"summary": "audio recordings in Esperanto",
"value": "epo"
},
"2": {
"summary": "audio recordings in Sundanese",
"value": "sun"
}
}
},
{
"name": "author",
"in": "query",
"description": "Only return audio recordings contributed by this user.",
"schema": {
"type": "string",
"example": "kevin"
}
},
{
"name": "limit",
"in": "query",
"description": "Maximum number of audio recordings in the response.",
"schema": {
"type": "integer",
"example": "20"
}
},
{
"$ref": "#/components/parameters/after"
}
]
},
"/v1/sentences/{id}": {
"get": {
"tags": [
"Sentences"
],
"summary": "Get a sentence",
"description": "Get sentence text as well as metadata about this sentence and related sentences.",
"operationId": "33a2db5ccb628358074a151063ca18b7",
"responses": {
"200": {
"description": "Success.",
"content": {
"application/json": {
"schema": {
"properties": {
"data": {
"$ref": "#/components/schemas/SentenceWithTranslations",
"description": "Sentence of the provided id."
}
},
"type": "object"
}
}
}
},
"400": {
"$ref": "#/components/responses/ClientErrorResponse",
"description": "Invalid ID parameter."
},
"404": {
"$ref": "#/components/responses/NotFoundErrorResponse",
"description": "There is no sentence with that ID or it has been deleted."
},
"500": {
"$ref": "#/components/responses/ServerErrorResponse"
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"description": "The sentence identifier.",
"schema": {
"$ref": "#/components/schemas/Sentence/properties/id"
}
},
{
"$ref": "#/components/parameters/include",
"description": "Specify which additional associated data to return along with the sentence and its translations."
},
{
"name": "showtrans",
"in": "query",
"description": "Specify which translations to return along with the sentence. The default is none.",
"schema": {
"type": "enum",
"enum": [
"all",
"none"
]
},
"examples": {
"1": {
"summary": "return all translations",
"value": "all"
},
"2": {
"summary": "return no translation",
"value": "none"
}
}
},
{
"$ref": "#/components/parameters/showtrans:lang"
},
{
"$ref": "#/components/parameters/showtrans:is_direct"
},
{
"$ref": "#/components/parameters/showtrans:is_unapproved"
},
{
"$ref": "#/components/parameters/showtrans:is_orphan"
},
{
"$ref": "#/components/parameters/showtrans:owner"
},
{
"$ref": "#/components/parameters/showtrans:is_native"
},
{
"$ref": "#/components/parameters/showtrans:has_audio"
}
]
},
"/v1/sentences": {
"get": {
"tags": [
"Sentences"
],
"summary": "Search sentences",
"description": "Allows to search for sentences based on some criteria. By default, all sentences are returned, including sentences you might want to filter out, such as unapproved or orphaned (that is, likely not proofread) ones. To filter sentences, use any combination of the parameters described below.\n\nUse & (the usual operator to combine query parameters) to combine filters with logical AND.
| Example | Result |
|---|---|
lang=epo | \n Only sentences both in Esperanto and having audio. | \n
tag=OK | \n Only sentences having both an OK tag and a colloquial tag. | \n
Use , to combine several values of a filter with logical OR.
| Example | Result |
|---|---|
lang=srp,hrv,bos | \n Only sentences in Serbian, Croatian, or Bosnian. | \n
tag=idiom,proverb | \n Only sentences tagged as idiom or proverb (or both). | \n
Use ! as value prefix to make a logical NOT (applied to the entire list of values). It can be used to exclude sentences matched by the filter.
| Example | Result |
|---|---|
tag=!colloquial | \nExclude sentences tagged as colloquial. | \n
tag=!idiom,proverb | \nExclude sentences tagged as idiom or proverb or both. (In other words, only sentences neither tagged as idiom nor proverb.) | \n
tag=!idiom | \nExclude sentences that are both tagged as idiom and proverb. (Should a sentence be tagged as idiom but not proverb, it won't be excluded.) | \n
Translation filters are filters which name starts with trans: (or !trans:, covered later).
| Example | Result |
|---|---|
trans:lang=epo | \n Only sentences having direct translation(s) in Esperanto. | \n
trans:lang=epo | \n Only sentences having translation(s) in Esperanto owned by \"gillux\". | \n
trans:count=0 | \n Only sentences not having any translation at all. | \n
Each translation filter belongs to a group. First, filters belonging to the same group are applied together to the translations with a logical AND, and then each group result is combined with a logical AND.
\nFilters starting with the same prefix belong to the same group, and trans: is just one of these groups. It is possible to create any number of groups using the prefix trans:n:, n consisting of one of more digits.
| Example | Result |
|---|---|
trans:1:lang=epo | \n Only sentences both having translation(s) in Esperanto and in Sundanese. | \n
trans:1:lang=epo | \n Only sentences both having translation(s) in Esperanto owned by \"gillux\" and in Sundanese owned by \"ajip\". | \n
trans:1:lang=epo | \n Only sentences both having orphan and non-orphan translation(s) in Esperanto. | \n
By prefixing a group number n with an exclamation mark, it is possible to perform a logical NOT on a specific group before it is combined with other groups. This can be used to exclude sentences having translation(s) matched by the group.
| Example | Result |
|---|---|
trans:1:lang=epo | \n Only sentences having indirect translation(s) in Esperanto. | \n
trans:!1:lang=epo | \n Exclude sentences having direct translation(s) in Esperanto. | \n
trans:1:lang=epo | \n Combination of the two above: only sentences having indirect, but not any direct translation(s) in Esperanto (note that trans:1: and trans:!1: are considered as different groups because the prefix is not strictly equal). | \n
trans:!1:lang=epo | \n Exclude sentences having translation(s) in Esperanto or Sundanese (or both). Why or? Because in boolean algebra: !epo AND !sun ⟺ !(epo OR sun) | \n
Note that groups such as trans:1: are not a subgroup of the trans: group; they are all groups of the same level.
!trans: prefixThe prefix !trans: works just like trans:, except it is a separate group of groups in which a final logical NOT is performed on the top of all the groups it encompasses. This can be used to exclude sentences having translations matched by several groups at once.
| Example | Result |
|---|---|
!trans:1:lang=epo | \n Exclude sentences both having translation(s) in Esperanto and in Sundanese. | \n
!trans:1:lang=epo | \n Exclude sentences both having translation(s) in Esperanto owned by \"gillux\" and in Sundanese owned by \"ajip\". | \n
!trans:1:lang=epo | \n Exclude sentences both having orphan and non-orphan translation(s) in Esperanto. | \n
!trans: can also be used as an equivalent prefix for trans:!0: when this would otherwise be the only group.
| Example | Result |
|---|---|
trans:0:lang=epo | \n Sentences having translation(s) in Esperanto and not having any translation in Sundanese. | \n
trans:lang=epo | \n Same as above. | \n
By default, this endpoint only returns translations matched by translations filters.
\n\n| Example | Returned sentences | Returned translations |
|---|---|---|
lang=eng | \n English sentences. | \nNone. | \n
lang=eng | \n English sentences having translation(s) in Javanese. | \nJavanese translations. | \n
lang=eng | \n English sentences having indirect translation(s). | \nIndirect translations. | \n
lang=eng | \n English sentences having indirect translation(s) in Javanese | \nIndirect Javanese translations. | \n
Note that only non-excluding translation filters are taken into account.
\n\n| Example | Returned sentences | Returned translations |
|---|---|---|
lang=eng | \n English sentences not having any translations in Javanese. | \nNone. | \n
lang=eng | \n Same as above. | \nNone. | \n
lang=eng | \n English sentences having translations not in Javanese. | \nTranslations not in Javanese. | \n
This behavior is what happens when using the parameter showtrans=matching, which is the default value for showtrans. You may also use showtrans=all or showtrans=none to respectively return all or no translations, regardless of the translation filters in use.
Alternatively, you can manually specify a custom set of criteria to filter returned translations by using parameters starting with showtrans:. These parameters work the same way as translation filters, and support group filters.
| Example | Returned sentences | Returned translations |
|---|---|---|
lang=eng | \n English sentences having translation(s) in Polish. | \nTranslations in Marathi (if any). | \n
lang=eng | \n English sentences having translation(s) in Polish. | \nTranslations not in Marathi (if any). | \n
lang=eng | \n English sentences having translation(s) in Polish. | \nDirect translations owned by native speakers (if any). | \n
lang=eng | \n English sentences having translation(s) in Polish. | \nBoth direct translations in Marathi and translations in Javanese owned by native speakers (if any). | \n
lang=eng | \n Error, invalid showtrans filter. | \n|
lang=eng | \n Error, invalid showtrans filter. | \n
is_orphan filter in a way that makes sense.",
"schema": {
"$ref": "#/components/schemas/NegatableMemberList"
},
"examples": {
"1": {
"summary": "sentences owned by gillux",
"value": "gillux"
},
"2": {
"summary": "sentences owned by gillux or ajip",
"value": "gillux,ajip"
},
"3": {
"summary": "sentences orphan or owned by a different member than gillux",
"value": "!gillux"
},
"4": {
"summary": "sentences orphan or owned by a member who is neither gillux nor ajip",
"value": "!gillux,ajip"
}
}
},
{
"name": "is_orphan",
"in": "query",
"description": "Limit to orphan sentences (if value is yes) or sentences owned by someone (if value is no). Make sure to combine with owner filter in a way that makes sense.",
"schema": {
"$ref": "#/components/schemas/Boolean"
}
},
{
"name": "is_unapproved",
"in": "query",
"description": "Limit to unapproved sentences (if value is yes) or exclude unapproved sentences (if value is no).",
"schema": {
"$ref": "#/components/schemas/Boolean"
}
},
{
"name": "is_native",
"in": "query",
"description": "Limit to sentences owned by a self-identified native speaker (if value is yes) or not owned by a self-identified native speaker (if the value is no). Tip: combine is_native=no with is_orphan=no to limit to sentences owned by a self-identified non-native speaker.",
"schema": {
"$ref": "#/components/schemas/Boolean"
}
},
{
"name": "has_audio",
"in": "query",
"description": "Limit to sentences having one or more audio recordings (if value is yes) or no audio recording (if value is no).",
"schema": {
"$ref": "#/components/schemas/Boolean"
}
},
{
"name": "tag",
"in": "query",
"description": "Limit to sentences having the provided tag. This parameter can be provided multiple times to search for sentences having multiple tags at the same time.",
"schema": {
"$ref": "#/components/schemas/NegatableTagList"
},
"examples": {
"1": {
"summary": "sentences tagged as OK",
"value": "OK"
},
"2": {
"summary": "sentences tagged as idiom",
"value": "idiom"
},
"3": {
"summary": "sentences tagged as idiom or proverb (or both)",
"value": "idiom,proverb"
},
"4": {
"summary": "exclude sentences tagged as OK",
"value": "!OK"
},
"5": {
"summary": "exclude sentences tagged as idiom or proverb (or both)",
"value": "!idiom,proverb"
}
}
},
{
"name": "list",
"in": "query",
"description": "Limit to sentences present on the provided list id. This parameter can be provided multiple times to search for sentences present on multiple lists at the same time.",
"schema": {
"$ref": "#/components/schemas/NegatableListIdList"
},
"examples": {
"1": {
"summary": "sentences on list 123",
"value": "123"
},
"2": {
"summary": "sentences on list 123 or list 456 (or both)",
"value": "123,456"
},
"3": {
"summary": "exclude sentences on list 123",
"value": "!123"
},
"4": {
"summary": "exclude sentences on list 123 or list 456 (or both)",
"value": "!123,456"
}
}
},
{
"name": "origin",
"in": "query",
"description": "Limit according to sentence origin. All sentences fall in two sets: unknown and known. The set known is composed of two subsets: original + translation.",
"schema": {
"type": "enum",
"enum": [
"original",
"translation",
"known",
"unknown"
]
},
"examples": {
"1": {
"summary": "sentences not added as translations of other sentences",
"value": "original"
},
"2": {
"summary": "sentences added as translations of other sentences",
"value": "translation"
},
"3": {
"summary": "sentences we know have been added or not as translations of other sentences",
"value": "known"
},
"4": {
"summary": "sentences we do not know whether or not they have been added as translations of other sentences",
"value": "unknown"
}
}
},
{
"name": "license",
"in": "query",
"description": "Limit according to sentence license. Unless this parameter is provided, sentences having a licensing issue are excluded by default.",
"schema": {
"$ref": "#/components/schemas/SentenceLicenseList"
},
"examples": {
"1": {
"summary": "sentences published under CC BY 2.0 FR",
"value": "CC BY 2.0 FR"
},
"2": {
"summary": "sentences published under CC0 1.0",
"value": "CC0 1.0"
},
"3": {
"summary": "sentences having a licensing issue",
"value": "PROBLEM"
},
"4": {
"summary": "sentences not having a licensing issue (the default)",
"value": "!PROBLEM"
}
}
},
{
"name": "trans:lang",
"in": "query",
"description": "Limit to sentences having translations in this language.",
"schema": {
"$ref": "#/components/schemas/NegatableLanguageCodeList"
},
"examples": {
"1": {
"summary": "sentences having translation(s) in Esperanto",
"value": "epo"
},
"2": {
"summary": "sentences having translation(s) in Esperanto or Sundanese",
"value": "epo,sun"
},
"3": {
"summary": "sentences having translation(s) in a language that is not Esperanto or Sundanese",
"value": "!epo,sun"
}
}
},
{
"name": "trans:is_direct",
"in": "query",
"description": "Limit to sentences having directly-linked translation(s) if value is yes, or indirectly-linked translations (i.e. translations of translations) if the value is no.",
"schema": {
"$ref": "#/components/schemas/Boolean"
}
},
{
"name": "trans:owner",
"in": "query",
"description": "Limit to sentences having translation(s) owned by the provided username. Make sure to combine with trans:is_orphan filter in a way that makes sense.",
"schema": {
"$ref": "#/components/schemas/NegatableMemberList"
},
"examples": {
"1": {
"summary": "sentences having translation(s) owned by gillux",
"value": "gillux"
},
"2": {
"summary": "sentences having translation(s) owned by gillux or ajip",
"value": "gillux,ajip"
},
"3": {
"summary": "sentences having translation(s) owned by a different member than gillux or orphan",
"value": "!gillux"
},
"4": {
"summary": "sentences having translation(s) that are orphan or owned by a member who is neither gillux nor ajip",
"value": "!gillux,ajip"
}
}
},
{
"name": "trans:is_unapproved",
"in": "query",
"description": "Limit to sentences having unapproved translation(s) (if value is yes) or having translation(s) not marked as unapproved (if value is no).",
"schema": {
"$ref": "#/components/schemas/Boolean"
}
},
{
"name": "trans:is_orphan",
"in": "query",
"description": "Limit to sentences having orphan translations (if value is yes) or translations owned by someone (if value is no). Make sure to combine with trans:owner filter in a way that makes sense.",
"schema": {
"$ref": "#/components/schemas/Boolean"
}
},
{
"name": "trans:is_native",
"in": "query",
"description": "Limit to sentences having translations owned by a self-identified native speaker (if value is yes) or not owned by a self-identified native speaker (if the value is no). Tip: combine trans:is_native=no with trans:is_orphan=no to limit to sentences having translations owned by a self-identified non-native speaker.",
"schema": {
"$ref": "#/components/schemas/Boolean"
}
},
{
"name": "trans:has_audio",
"in": "query",
"description": "Limit to sentences having translation(s) having one or more audio recordings (if value is yes) or no audio recording (if value is no).",
"schema": {
"$ref": "#/components/schemas/Boolean"
}
},
{
"name": "trans:count",
"in": "query",
"description": "Limit according to the presence of translations. Zero (0) or non-zero (!0) are the only allowed values.",
"schema": {
"type": "string",
"pattern": "!?0"
},
"examples": {
"1": {
"summary": "sentences not having any translation",
"value": "0"
},
"2": {
"summary": "sentences having translation(s)",
"value": "!0"
}
}
},
{
"name": "sort",
"in": "query",
"description": "Sort order of the sentences. Prefix the value with minus - to reverse that order.",
"required": true,
"schema": {
"type": "string",
"pattern": "-?(relevance|words|created|modified|random)"
},
"examples": {
"1": {
"summary": "prioritize sentences with exact matches, then sentences containing all the searched words, then shortest sentences",
"value": "relevance"
},
"2": {
"summary": "order by number of words (or, if the language does not use spaces as word separators, by number of characters), shortest first",
"value": "words"
},
"3": {
"summary": "order by number of words, longest first",
"value": "-words"
},
"4": {
"summary": "order by sentence creation date (newest first)",
"value": "created"
},
"5": {
"summary": "order by sentence creation date (oldest first)",
"value": "-created"
},
"6": {
"summary": "order by last sentence modification (last modified first)",
"value": "modified"
},
"7": {
"summary": "randomly sort results",
"value": "random"
}
}
},
{
"$ref": "#/components/parameters/after"
},
{
"name": "limit",
"in": "query",
"description": "Maximum number of sentences in the response.",
"schema": {
"type": "integer",
"example": "20"
}
},
{
"$ref": "#/components/parameters/include",
"description": "Specify which additional associated data to return along with matched sentences and translations."
},
{
"name": "showtrans",
"in": "query",
"description": "Specify which translations to return along with matched sentences. The default is matching.",
"schema": {
"type": "enum",
"enum": [
"matching",
"all",
"none"
]
},
"examples": {
"1": {
"summary": "if there are any non-excluding translation filters, return translations matched these filters, otherwise return no translation",
"value": "matching"
},
"2": {
"summary": "return all translations",
"value": "all"
},
"3": {
"summary": "return no translation",
"value": "none"
}
}
},
{
"$ref": "#/components/parameters/showtrans:lang"
},
{
"$ref": "#/components/parameters/showtrans:is_direct"
},
{
"$ref": "#/components/parameters/showtrans:is_unapproved"
},
{
"$ref": "#/components/parameters/showtrans:is_orphan"
},
{
"$ref": "#/components/parameters/showtrans:owner"
},
{
"$ref": "#/components/parameters/showtrans:is_native"
},
{
"$ref": "#/components/parameters/showtrans:has_audio"
}
]
},
"/unstable/users/{username}": {
"get": {
"tags": [
"Users"
],
"summary": "Get a user",
"description": "Get information about a member of Tatoeba.",
"operationId": "f7d9d4e39558b6de60724081b3a0253c",
"responses": {
"200": {
"description": "Success."
},
"400": {
"description": "Invalid parameter."
},
"404": {
"description": "There is no user with that username or the account was removed."
}
}
},
"parameters": [
{
"name": "username",
"in": "path",
"description": "The user name of the member.",
"required": true,
"schema": {
"$ref": "#/components/schemas/User/properties/username"
}
}
]
}
},
"components": {
"schemas": {
"Paging": {
"description": "Description of the pagination context of a response.",
"properties": {
"first": {
"description": "URL to fetch the first page of results.",
"type": "string",
"example": "https://example.com/sentences"
},
"total": {
"description": "The total number of results among all pages.",
"type": "integer",
"example": "42"
},
"has_next": {
"description": "Whether there are more results than what was returned.",
"type": "boolean",
"example": true
},
"next": {
"description": "URL to fetch the next page of results.",
"type": "string",
"example": "https://example.com/sentences?after=1234,4567"
}
},
"type": "object"
},
"LanguageCode": {
"description": "The ISO 639-3 code of the language, or some exceptional code.",
"type": "string",
"maxLength": 4,
"minLength": 3,
"pattern": "[a-z]+",
"example": "epo"
},
"LanguageCodeList": {
"description": "A list of ISO 639-3 codes or some exceptional code. The codes will be combined with a boolean OR.",
"type": "array",
"items": {
"type": "string",
"maxLength": 4,
"minLength": 3,
"pattern": "[a-z]+",
"example": "epo"
}
},
"NegatableRangeList": {
"description": "A comma-separated list of inclusive ranges of the form n-m, n and m being integers. A range may be open-ended by omitting n or m (but not both). The list of ranges can be negated by prefixing it with !.",
"type": "string",
"minLength": 1,
"pattern": "!?([0-9]+-[0-9]+|[0-9]+-|-[0-9]+)(,([0-9]+-[0-9]+|[0-9]+-|-[0-9]+))*",
"example": "10-20"
},
"NegatableMemberList": {
"description": "A comma-separated list of usernames. The list of usernames can be negated by prefixing it with !.",
"type": "string",
"pattern": "!?[0-9a-zA-Z_]*(,[0-9a-zA-Z_]*)*",
"example": "gillux"
},
"NegatableTagList": {
"description": "A comma-separated list of tags. The list of tags can be negated by prefixing it with !.",
"type": "string",
"pattern": "!?[^,]+(,[^,]+)*",
"example": "OK"
},
"NegatableListIdList": {
"description": "A comma-separated list of list ids. The list of ids can be negated by prefixing it with !.",
"type": "string",
"pattern": "!?[0-9]+(,[0-9]+)*",
"example": "123"
},
"NegatableLanguageCodeList": {
"description": "A comma-separated list of ISO 639-3 codes or some exceptional code. The list of languages can be negated by prefixing it with !.",
"type": "string",
"pattern": "!?[a-z]{3,4}(,[a-z]{3,4})*",
"example": "epo"
},
"Boolean": {
"type": "enum",
"enum": [
"yes",
"no"
]
},
"ScriptCode": {
"description": "ISO 15924 script code",
"type": "string",
"maxLength": 4,
"minLength": 4,
"pattern": "[A-Z][a-z]{3}",
"example": "Latn"
},
"SentenceLicense": {
"type": "enum",
"enum": [
"CC BY 2.0 FR",
"CC0 1.0",
"PROBLEM"
]
},
"SentenceLicenseList": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SentenceLicense"
}
},
"AudioWithExtraInfo": {
"description": "An audio object along with related information.",
"allOf": [
{
"$ref": "#/components/schemas/Audio"
},
{
"properties": {
"sentence": {
"$ref": "#/components/schemas/Sentence"
}
},
"type": "object"
}
]
},
"SentenceWithTranslations": {
"description": "A sentence object that contains related objects, including translations.",
"allOf": [
{
"$ref": "#/components/schemas/SentenceWithExtraInfo"
},
{
"properties": {
"translations": {
"description": "Sentences that are direct or indirect translations of the parent sentence objet",
"type": "array",
"items": {
"$ref": "#/components/schemas/Translation"
}
}
},
"type": "object"
}
]
},
"SentenceWithExtraInfo": {
"description": "A sentence object that contains both sentence text and metadata about the sentence, and related objects.",
"allOf": [
{
"$ref": "#/components/schemas/Sentence"
},
{
"properties": {
"transcriptions": {
"description": "Transcriptions of the sentence",
"type": "array",
"items": {
"$ref": "#/components/schemas/Transcription"
}
},
"audios": {
"description": "Audio recordings of the sentence",
"type": "array",
"items": {
"$ref": "#/components/schemas/Audio"
}
}
},
"type": "object"
}
]
},
"User": {
"description": "A user object that contains metadata about a member of Tatoeba.",
"properties": {
"username": {
"description": "The name of the member.",
"type": "string",
"maxLength": 20,
"minLength": 2,
"pattern": "[a-zA-Z0-9_]+",
"example": "gillux"
},
"role": {
"description": "The role this member was given.",
"type": "enum",
"enum": [
"admin",
"corpus_maintainer",
"advanced_contributor",
"contributor",
"inactive",
"spammer"
],
"example": "contributor"
},
"since": {
"description": "The date this member joined Tatoeba.",
"type": "string",
"format": "date",
"example": "2019-12-31"
},
"languages": {
"type": "array",
"items": {
"properties": {
"code": {
"$ref": "#/components/schemas/LanguageCode"
},
"level": {
"description": "The self-proclaimed level of proficiency in this language, ranging from 0 (lowest) to 5 (highest).",
"type": [
"integer",
"null"
],
"example": "3"
},
"details": {
"description": "Optional details about the language ability, such as dialect or country. This is a free-form text entered by the member, which can be written in any language.",
"type": "string"
}
},
"type": "object"
}
}
},
"type": "object"
},
"Sentence": {
"description": "A sentence object that contains both sentence text and metadata about the sentence.",
"properties": {
"id": {
"description": "The sentence identifier",
"type": "integer",
"example": "1234"
},
"text": {
"description": "The sentence text",
"type": "string",
"example": "Everything will be okay."
},
"lang": {
"anyOf": [
{
"$ref": "#/components/schemas/LanguageCode"
},
{
"description": "Contains null when the language has been assigned an ISO 639-3 code, but it is not yet supported on Tatoeba. Such sentences are often part of a list that describes the language.",
"type": "null"
}
]
},
"script": {
"description": "The sentence script",
"anyOf": [
{
"$ref": "#/components/schemas/ScriptCode",
"description": "If more than one script is supported for the language of this sentence, this contains the script code in ISO 15924 standard."
},
{
"description": "If the sentence language is only written in a single obvious script (such as Latin script for English), this contains null. Also contains null when different scripts are in use on Tatoeba, but Tatoeba does not perform script autodetection (example: Algerian Arabic (arq) or Baluchi (bal).",
"type": "null"
}
]
},
"license": {
"$ref": "#/components/schemas/SentenceLicense",
"description": "The license of the sentence"
},
"owner": {
"description": "The owner of the sentence",
"anyOf": [
{
"description": "User name of the sentence owner.",
"type": "string",
"example": "kevin"
},
{
"description": "Contains null when the sentence is orphan.",
"type": "null"
}
]
},
"is_unapproved": {
"description": "Whether this sentence is marked as unapproved (if value is true) or not (if value is false)",
"type": "boolean"
}
},
"type": "object"
},
"Transcription": {
"description": "The sentence written in an alternative form or script.",
"properties": {
"text": {
"description": "The transcription text. May use some ad-hoc markup syntax aimed at easing manual edit and machine readability.",
"type": "string",
"example": "Wo3men5 hai2you3 hen3 duo1gong1 zuo4 yao4 zuo4."
},
"script": {
"$ref": "#/components/schemas/ScriptCode",
"description": "Script code of the transcription in ISO 15924 standard"
},
"needsReview": {
"description": "Whether we think this transcription should be reviewed by a human. It is false when the transcription was autogenerated by an algorithm of low confidence. It is true when a human reviewed it, or when the algorithm is considered very accurate already.",
"type": "boolean",
"example": false
},
"type": {
"description": "Transcription type. altscript means the transcription is made into a script representative of the language (for example simplified Chinese characters transcribed into traditional). transcription means the target script is not representative (for example simplified Chinese into Latin characters).",
"type": "enum",
"enum": [
"transcription",
"altscript"
],
"example": "transcription"
},
"html": {
"description": "An HTML-valid, human-readable and good-looking representation of the text field",
"type": "string",
"example": "Wǒmen háiyǒu hěn duōgōng zuò yào zuò."
},
"editor": {
"description": "Last editor of the transcription.",
"anyOf": [
{
"description": "User who last reviewed the sentence text.",
"type": "string",
"example": "kevin"
},
{
"description": "Contains null when the transcription text was autogenerated by a machine. This happens when the transcription text was never reviewed, or was reset to its autogenerated state by a user.",
"type": "null"
}
]
},
"modified": {
"description": "Last time (in ISO 8601 format) the transcription text was edited. If editor is null, it is the datetime of autogeneration, otherwise it is the datetime of user review.",
"type": "string",
"format": "date-time",
"example": "2020-02-20T02:20:00+00:00"
}
},
"type": "object"
},
"Audio": {
"description": "An audio object that contains metadata about a recording.",
"properties": {
"id": {
"description": "The audio identifier",
"type": "integer",
"example": "4321"
},
"author": {
"description": "Name of user who contributed the audio recording",
"type": "string",
"example": "kevin62"
},
"licence": {
"description": "License of the audio recording",
"type": "string",
"example": "CC0 1.0"
},
"attribution_url": {
"description": "URL to give attribution to the author. If you want to re-use the audio in your project, you need to mention the author name along with this URL.",
"type": "string",
"example": "https://example.com/audio/kevin"
},
"download_url": {
"description": "URL to download the audio file",
"type": "string",
"example": "https://example.com/audio/1234.mp3"
},
"created": {
"description": "Audio creation datetime in ISO 8601 format",
"type": "string",
"format": "date-time",
"example": "2020-02-20T02:20:00+00:00"
},
"modified": {
"description": "Audio last modification datetime in ISO 8601 format",
"type": "string",
"format": "date-time",
"example": "2020-02-20T02:20:00+00:00"
}
},
"type": "object"
},
"Translation": {
"description": "A sentence object that is a direct or indirect translation of another sentence.",
"allOf": [
{
"properties": {
"is_direct": {
"description": "Whether this translation is direct (if value is true) or indirect (if value is false)",
"type": "boolean"
}
},
"type": "object"
},
{
"$ref": "#/components/schemas/SentenceWithExtraInfo"
}
]
}
},
"responses": {
"ClientErrorResponse": {
"description": "There was an issue with the provided parameters.",
"content": {
"application/json": {
"schema": {
"description": "Description of the error response.",
"properties": {
"message": {
"description": "Details about what is wrong.",
"type": "string",
"example": "Invalid value for parameter \"sort\""
},
"url": {
"description": "URL of the request (HTML-safe).",
"type": "string",
"example": "/unstable/sentences?lang=eng&sort=invalid"
},
"code": {
"description": "HTTP status code of the response.",
"type": "integer",
"example": 400
}
},
"type": "object"
}
}
}
},
"ServerErrorResponse": {
"description": "There is a problem with the API server.",
"content": {
"application/json": {
"schema": {
"description": "Description of the error response.",
"properties": {
"message": {
"description": "Details about what is wrong.",
"type": "string",
"example": "An Internal Error Has Occurred."
},
"url": {
"description": "URL of the request (HTML-safe).",
"type": "string",
"example": "/unstable/sentences/1"
},
"code": {
"description": "HTTP status code of the response.",
"type": "integer",
"example": 500
}
},
"type": "object"
}
}
}
},
"NotFoundErrorResponse": {
"description": "The thing could not be found.",
"content": {
"application/json": {
"schema": {
"description": "Description of the error response.",
"properties": {
"message": {
"description": "Details about what is wrong.",
"type": "string",
"example": "Not Found"
},
"url": {
"description": "URL of the request (HTML-safe).",
"type": "string",
"example": "/unstable/sentences/1234"
},
"code": {
"description": "HTTP status code of the response.",
"type": "integer",
"example": 404
}
},
"type": "object"
}
}
}
}
},
"parameters": {
"after": {
"name": "after",
"in": "query",
"description": "Cursor start position. This parameter is used internally to paginate results.",
"schema": {
"type": [
"string",
"integer"
]
}
},
"include": {
"name": "include",
"in": "query",
"schema": {
"type": "array",
"items": {
"type": "enum",
"enum": [
"audios",
"transcriptions"
]
}
},
"examples": {
"1": {
"summary": "return associated transcriptions",
"value": "transcriptions"
},
"2": {
"summary": "return associated audio recordings",
"value": "audios"
},
"3": {
"summary": "return associated transcriptions and audio recordings",
"value": "transcriptions,audios"
}
}
},
"showtrans:lang": {
"name": "showtrans:lang",
"in": "query",
"description": "Limit returned translations to the ones in this language.",
"explode": false,
"schema": {
"$ref": "#/components/schemas/NegatableLanguageCodeList"
},
"examples": {
"1": {
"summary": "return translations in Esperanto, if any",
"value": "epo"
},
"2": {
"summary": "return translations in Esperanto and Sundanese, if any",
"value": "epo,sun"
},
"3": {
"summary": "return translations in any language that is not Esperanto or Sundanese, if any",
"value": "!epo,sun"
}
}
},
"showtrans:is_direct": {
"name": "showtrans:is_direct",
"in": "query",
"description": "Limit returned translations to the directly-linked ones if value is yes, or the indirectly-linked ones (i.e. translations of translations) if the value is no.",
"schema": {
"$ref": "#/components/schemas/Boolean"
}
},
"showtrans:is_unapproved": {
"name": "showtrans:is_unapproved",
"in": "query",
"description": "Limit returned translations to the ones that are unapproved (if value is yes) or not unapproved (if value is no).",
"schema": {
"$ref": "#/components/schemas/Boolean"
}
},
"showtrans:is_orphan": {
"name": "showtrans:is_orphan",
"in": "query",
"description": "Limit returned translations to the ones that are orphan (if value is yes) or owned by someone (if value is no). Make sure to combine with showtrans:owner filter in a way that makes sense.",
"schema": {
"$ref": "#/components/schemas/Boolean"
}
},
"showtrans:owner": {
"name": "showtrans:owner",
"in": "query",
"description": "Limit returned translations to the ones owned by the provided username. Make sure to combine with showtrans:is_orphan filter in a way that makes sense.",
"schema": {
"$ref": "#/components/schemas/NegatableMemberList"
},
"examples": {
"1": {
"summary": "return translations owned by gillux",
"value": "gillux"
},
"2": {
"summary": "return translations owned by gillux or ajip",
"value": "gillux,ajip"
},
"3": {
"summary": "return translations orphan or owned by a different member than gillux",
"value": "!gillux"
},
"4": {
"summary": "return translations orphan or owned by a member who is neither gillux nor ajip",
"value": "!gillux,ajip"
}
}
},
"showtrans:is_native": {
"name": "showtrans:is_native",
"in": "query",
"description": "Limit returned translations to the ones that are owned by a self-identified native speaker (if value is yes) or not owned by a self-identified native speaker (if the value is no). Tip: combine showtrans:is_native=no with showtrans:is_orphan=no to return translations owned by a self-identified non-native speaker.",
"schema": {
"$ref": "#/components/schemas/Boolean"
}
},
"showtrans:has_audio": {
"name": "showtrans:has_audio",
"in": "query",
"description": "Limit returned translations to the ones having one or more audio recordings (if value is yes) or no audio recording (if value is no).",
"schema": {
"$ref": "#/components/schemas/Boolean"
}
}
}
},
"tags": [
{
"name": "Audio",
"description": "Audio"
},
{
"name": "Sentences",
"description": "Sentences"
},
{
"name": "Users",
"description": "Users"
}
]
}