Folders with the API

Reading needs a key with the folders:read scope. Every change needs folders:write.

Each folder belongs to one target language, and can only hold items in that language.

List and read folders

GET /v1/folders lists your folders, most recently updated first. Add ?language=es to see one language only.

GET /v1/folders/{folderDocId} returns the folder and the items in it, in display order:

{
  "folder": {
    "doc_id": "Fd4kL9mN2pQ7rS1tU6vW",
    "name": "Travel",
    "target_ISO_639-1": "es",
    "number_of_items": 2,
    "parent_folder_doc_id": null,
    "items": [
      { "doc_id": "8sKd92mfPqR1xLvBn4Tz", "content_type": "deck", "name": "Airport words" },
      { "doc_id": "Xq2mP9sLkR4tVbN1cZ8a", "content_type": "text", "name": "En el mercado" }
    ]
  }
}

Create a folder

curl -X POST https://yalango.com/api/v1/folders \
  -H "Authorization: Bearer yal_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Travel", "target_ISO_639-1": "es"}'

Add parent_folder_doc_id to create it inside another folder. The parent folder must be in the same language.

Rename or reorder

curl -X PATCH https://yalango.com/api/v1/folders/Fd4kL9mN2pQ7rS1tU6vW \
  -H "Authorization: Bearer yal_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Travel 2026", "item_order": ["Xq2mP9sLkR4tVbN1cZ8a", "8sKd92mfPqR1xLvBn4Tz"]}'

item_order must list every item in the folder exactly once.

Move an item

curl -X POST https://yalango.com/api/v1/folders/move \
  -H "Authorization: Bearer yal_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content_type": "deck",
    "doc_id": "8sKd92mfPqR1xLvBn4Tz",
    "destination_folder_doc_id": "Fd4kL9mN2pQ7rS1tU6vW"
  }'

• content_type is deck, table, text, notebook or folder.
• Set destination_folder_doc_id to null to move the item to the top level of your library.
• The item and the folder must be in the same language. Otherwise the request returns 400 language_mismatch.
• A folder cannot be moved into itself or one of its own subfolders. That returns 400 folder_cycle.

Delete a folder

DELETE /v1/folders/{folderDocId} deletes a folder only when it is empty. In the app, deleting a folder deletes everything in it, so the API refuses a folder that still has items with 409 folder_not_empty. Move or delete the items first.

Limits

The free plan allows 1,000 folders. Going over returns 402 quota_exceeded.