Notebooks with the API

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

A notebook holds sections, and each section holds pages. A page is a list of blocks.

Create a notebook

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

name (up to 200 characters) and target_ISO_639-1 are required. Notebooks created through the API are private and start empty. PATCH /v1/notebooks/{notebookDocId} changes name and description.

Read the outline

GET /v1/notebooks/{notebookDocId} returns the sections in order, and the page titles in each:

{
  "notebook": {
    "doc_id": "Nb7xK2pQ9mL4vR8tW1zY",
    "name": "Spanish grammar",
    "is_course": false,
    "sections": [
      {
        "section_doc_id": "Sc1aB2cD3eF4gH5iJ6kL",
        "name": "Verbs",
        "pages": [{ "page_doc_id": "Pg9zY8xW7vU6tS5rQ4pO", "title": "Ser and estar" }]
      }
    ]
  }
}

Manage sections

PATCH /v1/notebooks/{notebookDocId}/sections takes any combination of these, checks all of them, and then applies them together:

curl -X PATCH https://yalango.com/api/v1/notebooks/Nb7xK2pQ9mL4vR8tW1zY/sections \
  -H "Authorization: Bearer yal_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "add": ["Pronouns"],
    "rename": [{ "section_doc_id": "Sc1aB2cD3eF4gH5iJ6kL", "name": "Verbs and tenses" }]
  }'

• add - new section names. They are placed after the existing sections.
• rename - section ids and their new names.
• delete - section ids to remove. Every page in the section is deleted too, and this cannot be undone.
• order - every remaining section id, in the new order.
• page_order - for each section you want to reorder, its id and every page id in the new order.

Write a page

Create a page at the end of a section with POST /v1/notebooks/{notebookDocId}/pages:

curl -X POST https://yalango.com/api/v1/notebooks/Nb7xK2pQ9mL4vR8tW1zY/pages \
  -H "Authorization: Bearer yal_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "section_doc_id": "Sc1aB2cD3eF4gH5iJ6kL",
    "title": "Ser and estar",
    "blocks": [
      { "type": "heading_1", "content": "When to use ser" },
      { "type": "markdown", "content": "Use **ser** for identity and origin." },
      { "type": "deck", "ref_doc_id": "8sKd92mfPqR1xLvBn4Tz", "block_title": "Practice" }
    ]
  }'

These block types can be written through the API:

Type	Fields
markdown	content - Markdown text
heading_1, heading_2, heading_3	content - the heading text
deck, table, text	ref_doc_id - one of your own decks, tables or texts. Optional block_title and block_description

The name shown on a deck, table or text block is filled in from the item itself. Linking to an item that is not yours returns 403.

Images, PDFs, videos and sentences can only be added in the app.

Edit a page

Read the page first with GET /v1/notebooks/{notebookDocId}/pages/{pageDocId}. Every block has an id and an editable flag.

Then send PATCH with the complete list of blocks in the order you want:

{
  "blocks": [
    { "id": "c1d2e3f4-..." },
    { "id": "a9b8c7d6-...", "content": "Use **ser** for identity, origin and time." },
    { "type": "markdown", "content": "A new paragraph at the end." }
  ]
}

• { "id" } on its own keeps that block exactly as it is.
• An id with fields edits that block. Only editable blocks can be edited.
• A block without an id is added as a new block.
• An editable block you leave out is removed.

Blocks with editable: false (images, PDFs, videos and sentences) cannot be recreated through the API. Leaving one out is refused with 400 block_not_removable_via_api rather than deleting it - include it as { "id": "..." } to keep it, and remove it in the app if you really want it gone.

A page can have up to 300 blocks and a title of up to 300 characters. Pages cannot move between sections.

Delete

• DELETE /v1/notebooks/{notebookDocId}/pages/{pageDocId} deletes one page and its uploaded images.
• DELETE /v1/notebooks/{notebookDocId} deletes the whole notebook with all of its sections, pages and images.

Neither can be undone.

Published courses

A notebook published as a language course can be read but not changed through the API. Any change returns 409 notebook_is_course.

Limits

The free plan allows 10 notebooks. Going over returns 402 quota_exceeded. A notebook can have up to 200 sections and 1,000 pages. Yalango Premium removes the notebook limit.