The Yalango API

The Yalango API lets you work with your own decks, cards, texts, tables, notebooks and folders from a script instead of the web app. It is built for automating your own account - collecting words from something you read, syncing from a tool you already use, or bulk-adding vocabulary you gathered elsewhere.

It is available to every signed-in account with a verified email address. You do not need Premium, though the free plan limits on decks and cards still apply.

The base URL

https://yalango.com/api/v1

Every endpoint sits under that prefix. The version is part of the URL - see Compatibility below.

Authentication

Requests carry an API key in the Authorization header:

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

The key must be sent in the header. Query parameters are not supported.

Create and manage your API keys in settings.

What you can do

Endpoint	What it does
`GET /v1/decks`	List your decks
`POST /v1/decks`	Create a deck
`GET /v1/decks/{deckDocId}`	Get one deck
`PATCH /v1/decks/{deckDocId}`	Update a deck
`GET /v1/decks/{deckDocId}/cards`	List a deck's cards
`POST /v1/decks/{deckDocId}/cards`	Add up to 100 cards
`PATCH /v1/decks/{deckDocId}/cards`	Edit up to 100 cards
`PATCH /v1/decks/{deckDocId}/cards/{cardDocId}`	Edit one card
`DELETE /v1/decks/{deckDocId}/cards/{cardDocId}`	Delete one card
`POST /v1/decks/{deckDocId}/cards/delete`	Delete up to 100 cards
`GET /v1/decks/{deckDocId}/custom-fields`	List a deck's custom fields
`POST /v1/decks/{deckDocId}/custom-fields`	Add a custom field
`DELETE /v1/decks/{deckDocId}/custom-fields/{fieldDocId}`	Delete a custom field
`GET /v1/vocabulary`	Look a word up in your vocabulary
`GET /v1/review`	See what is due for review
`GET`, `POST /v1/texts`	List and create texts
`GET`, `PATCH`, `DELETE /v1/texts/{textDocId}`	Read, edit and delete a text
`GET`, `POST /v1/tables`	List and create tables
`GET`, `PATCH`, `DELETE /v1/tables/{tableDocId}`	Read, edit and delete a table
`PATCH /v1/tables/{tableDocId}/columns`	Add, rename, delete and reorder columns
`GET`, `POST /v1/tables/{tableDocId}/rows`	Read rows, and add, edit and delete up to 100 at once
`GET`, `POST /v1/notebooks`	List and create notebooks
`GET`, `PATCH`, `DELETE /v1/notebooks/{notebookDocId}`	Read the outline, edit and delete a notebook
`PATCH /v1/notebooks/{notebookDocId}/sections`	Add, rename, delete and reorder sections
`POST /v1/notebooks/{notebookDocId}/pages`	Add a page
`GET`, `PATCH`, `DELETE /v1/notebooks/{notebookDocId}/pages/{pageDocId}`	Read, write and delete a page
`GET`, `POST /v1/folders`	List and create folders
`GET`, `PATCH`, `DELETE /v1/folders/{folderDocId}`	Read, rename, reorder and delete a folder
`POST /v1/folders/move`	Move an item into a folder
`GET /v1/languages`	List the languages you study
`POST /v1/languages`	Add a language

Deleting decks is not available yet.

A first request

This lists your decks, newest first:

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

{
  "decks": [
    {
      "doc_id": "8sKd92mfPqR1xLvBn4Tz",
      "id": 48210937465,
      "name": "Spanish verbs",
      "description": "",
      "source_ISO_639-1": "en",
      "target_ISO_639-1": "es",
      "privacy": "private",
      "number_of_items": 214,
      "tags": "",
      "created_timestamp": "2026-01-14T09:22:31.000Z",
      "last_updated_timestamp": "2026-03-02T18:05:12.000Z"
    }
  ],
  "next_cursor": null
}

The doc_id is what every other endpoint uses to identify a deck. The numeric id is the one that appears in a public deck URL.

Browsers are not supported

The API sends no CORS headers, so it cannot be called from front-end JavaScript in a browser. Call it from a server, a terminal, or a local script. A key used on a web page is visible to everyone who loads it.

Compatibility

Within v1, fields may be added to a response but never removed or renamed, so it is safe to parse a response and ignore the parts you do not need. Requests are strict in the other direction: an unrecognised field is rejected rather than ignored.

Every response includes an X-API-Version header. If v1 is ever retired, responses will start carrying Deprecation and Sunset headers well before it stops working.

Machine-readable schema

An OpenAPI 3.1 description of every endpoint is served at:

https://yalango.com/api/v1/openapi.json

It needs no API key and can be fed to a client generator or an HTTP client that imports OpenAPI.

Using an assistant instead of a script

If you would rather ask an assistant to do the work than write the requests yourself, Yalango also runs an MCP server at https://yalango.com/mcp that takes the same API key. See Connect an AI assistant.