Texts with the API

Reading needs a key with the texts:read scope. Creating, editing and deleting needs texts:write.

List your texts

curl "https://yalango.com/api/v1/texts?language=es" \
  -H "Authorization: Bearer yal_your_key_here"

Texts come back most recently updated first, without their bodies. language is optional. Page through with limit (up to 200) and the next_cursor from the previous response.

Read one text

curl https://yalango.com/api/v1/texts/Xq2mP9sLkR4tVbN1cZ8a \
  -H "Authorization: Bearer yal_your_key_here"

{
  "text": {
    "doc_id": "Xq2mP9sLkR4tVbN1cZ8a",
    "text_id": 73019284561,
    "title": "En el mercado",
    "body": "Hoy fui al mercado. Compré manzanas y pan.",
    "source_ISO_639-1": "en",
    "target_ISO_639-1": "es",
    "privacy": "private",
    "has_audio": false,
    "created_timestamp": "2026-10-02T09:12:00.000Z",
    "last_updated_timestamp": "2026-10-02T09:12:00.000Z"
  }
}

Create a text

curl -X POST https://yalango.com/api/v1/texts \
  -H "Authorization: Bearer yal_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "En el mercado",
    "body": "Hoy fui al mercado. Compré manzanas y pan.",
    "target_ISO_639-1": "es",
    "source_ISO_639-1": "en"
  }'

Field	Required	Notes
title	Yes	Up to 200 characters
body	Yes	Up to 50,000 characters, in the language being learned
target_ISO_639-1	Yes	The language the text is written in
source_ISO_639-1	No	The language you already know, used for translations

Texts created through the API are private. Pinyin is generated automatically for Chinese texts. Sentence audio is generated in the app, the same way as for any other text.

POST /v1/texts accepts an Idempotency-Key header, so a retry after a timeout does not create a second text.

Edit a text

curl -X PATCH https://yalango.com/api/v1/texts/Xq2mP9sLkR4tVbN1cZ8a \
  -H "Authorization: Bearer yal_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"title": "En el mercado de Valencia"}'

Only title and body can be changed. Sentence audio is generated per sentence, so changing the body removes it - generate it again in the app.

A text's language is fixed when it is created. Sending either language field returns 400 language_immutable. To change it, create a new text.

Delete a text

curl -X DELETE https://yalango.com/api/v1/texts/Xq2mP9sLkR4tVbN1cZ8a \
  -H "Authorization: Bearer yal_your_key_here"

The text and its audio are deleted, and it is removed from any folder. This cannot be undone.

Limits

The free plan allows 100 texts. Going over returns 402 quota_exceeded. Yalango Premium removes the limit.