Довідник

tutor_list_lessons

Список уроків викладача, спершу ті, що змінювалися нещодавно; можна шукати за назвою.

Потрібний дозвіл: read · validation_failed

List the teacher's lessons, most recently changed first. Filter by part of the title with query. Pass nextCursor back as cursor for the next page.

Параметри

Приклади виклику

{}

{
  "query": "present perfect",
  "limit": 10
}

Приклад результату

{
  "lessons": [
    {
      "id": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
      "title": "Get by: living on little",
      "subject": "angliyska-mova",
      "status": "completed",
      "worksheetCount": 1,
      "updatedAt": "2026-09-30T09:30:00Z"
    }
  ],
  "nextCursor": null
}

tutor_get_lesson

Читає один урок: аркуші й блоки з вмістом і ключами; показує, чи урок ще можна змінювати.

Потрібний дозвіл: read · not_found

Read one lesson: its worksheets and blocks in order, with each block's id, type, content and answerKey. editable is false when students already work on it and changes would be refused. updatedAt changes whenever a block is added, edited, removed or reordered.

Параметри

Приклади виклику

{
  "lessonId": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23"
}

Приклад результату

{
  "id": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
  "title": "Get by: living on little",
  "description": null,
  "subject": "angliyska-mova",
  "status": "completed",
  "updatedAt": "2026-09-30T09:30:00Z",
  "reviewUrl": "https://mentor.chitay.org.ua/app/worksheets/4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
  "editable": true,
  "worksheets": [
    {
      "id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "title": "Get by",
      "purpose": "classwork",
      "blocks": [
        {
          "id": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
          "type": "callout",
          "title": "",
          "instruction": "",
          "description": "",
          "authoring": "teacher",
          "status": "completed",
          "content": {
            "tone": "info",
            "label": "Note",
            "text": "Bring dictionaries."
          },
          "answerKey": null
        }
      ]
    }
  ]
}

tutor_get_block_schema

Описує один тип блоку: призначення, схему вмісту й ключа, обмеження та готовий приклад.

Потрібний дозвіл: read · validation_failed

Learn how to write one block type: its purpose, the content JSON Schema, the answerKey schema (null when the type is not graded), limits, and a complete valid example. Call it once per type you have not used yet.

Параметри

Приклади виклику

{
  "type": "gap_fill"
}

{
  "type": "callout"
}

Приклад результату

{
  "type": "gap_fill",
  "label": "Пропущені слова",
  "purpose": "Sentences with a gap between before and after; the student types the missing word or phrase. Auto-scored against value and the optional accept variants (case- and space-insensitive).",
  "gradable": true,
  "contentSchema": {
    "type": "object",
    "properties": {
      "items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "before": {
              "type": "string"
            },
            "after": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "before",
            "after"
          ],
          "additionalProperties": false
        }
      }
    },
    "required": [
      "items"
    ],
    "additionalProperties": false
  },
  "answerKeySchema": {
    "type": "object",
    "properties": {
      "items": {
        "type": "object",
        "description": "One entry per item, keyed by the item id from content. Every item needs an entry.",
        "additionalProperties": {
          "type": "object",
          "properties": {
            "field": {
              "type": "string",
              "enum": [
                "gap"
              ]
            },
            "value": {
              "type": "string",
              "description": "The expected word or phrase."
            },
            "accept": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Other accepted answers. Compared case- and space-insensitively."
            },
            "explanation": {
              "type": [
                "string",
                "null"
              ],
              "description": "Why the answer is right. Shown after review."
            }
          },
          "required": [
            "field",
            "value"
          ]
        }
      }
    },
    "required": [
      "items"
    ]
  },
  "limits": {
    "titleMaxChars": 200,
    "descriptionMaxChars": 1000,
    "instructionMaxChars": 2000,
    "blocksPerWorksheet": 40,
    "itemsField": "items",
    "suggestedItemsMax": 20
  },
  "example": {
    "content": {
      "items": [
        {
          "id": "g1",
          "before": "She could",
          "after": "on very little."
        },
        {
          "id": "g2",
          "before": "It is hard to",
          "after": "in a big city without a job."
        }
      ]
    },
    "answerKey": {
      "items": {
        "g1": {
          "field": "gap",
          "value": "get by"
        },
        "g2": {
          "field": "gap",
          "value": "get by",
          "accept": [
            "make ends meet"
          ]
        }
      }
    }
  }
}

tutor_list_courses

Список курсів викладача з кількістю уроків і лімітом активних курсів.

Потрібний дозвіл: read

List the teacher's courses, most recently changed first, with lesson counts and the active-course limit. Archived courses are hidden unless includeArchived is true.

Параметри

Приклади виклику

{}

{
  "includeArchived": true,
  "limit": 10
}

Приклад результату

{
  "courses": [
    {
      "id": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
      "title": "English B1",
      "subject": "english",
      "level": "b1",
      "visibility": "private",
      "published": false,
      "archived": false,
      "lessonCount": 12,
      "updatedAt": "2026-09-30T09:30:00Z"
    }
  ],
  "nextCursor": null,
  "limit": {
    "used": 1,
    "max": 10,
    "reached": false
  }
}

tutor_get_course

Курс із його уроками в порядку проходження та id кроків.

Потрібний дозвіл: read · not_found

Read one course and its lessons in order. Each lesson has a stepId (for the course-lesson tools) and a lessonId (for the lesson tools). pacingLocked: pacing can no longer change.

Параметри

Приклади виклику

{
  "courseId": "5a7e1f02-3b4c-4d5e-8f60-718293a4b5c6"
}

Приклад результату

{
  "id": "5a7e1f02-3b4c-4d5e-8f60-718293a4b5c6",
  "title": "English B1",
  "description": null,
  "subject": "english",
  "level": "b1",
  "pacing": "teacher_paced",
  "pacingLocked": false,
  "forWhom": [
    "**B1** learners who want to stop translating in their head"
  ],
  "outcomes": [],
  "published": false,
  "archived": false,
  "updatedAt": "2026-09-30T10:20:00Z",
  "lessons": [
    {
      "number": 1,
      "stepId": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
      "lessonId": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
      "title": "Ordering food",
      "note": null
    }
  ]
}

tutor_get_generation_status

Показує, як просувається створення уроку: очікує викладача, триває, готове чи невдале.

Потрібний дозвіл: read · not_found

Check a lesson started with tutor_generate_lesson. status is pending (waiting for the teacher to pick a plan in the web app — stop polling and share reviewUrl), generating, completed or failed. Poll no faster than every 5 seconds.

Параметри

Приклади виклику

{
  "lessonId": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23"
}

Приклад результату

{
  "lessonId": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
  "status": "pending",
  "message": "The material is ready. The teacher chooses the plan and starts exercise generation in the web app (open the reviewUrl); nothing more will happen until then.",
  "blocks": {
    "total": 0,
    "completed": 0,
    "failed": 0
  },
  "error": null,
  "reviewUrl": "https://mentor.chitay.org.ua/app/worksheets/4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23"
}

tutor_create_lesson

Створює цілий урок — аркуші й блоки — одним викликом: або все, або нічого.

Потрібний дозвіл: write · validation_failed, idempotency_conflict

Create a complete lesson with worksheets and blocks in one all-or-nothing call. Every problem is reported at once with its path; nothing is created if any exist. Returns lessonId and a reviewUrl for the teacher. Send idempotencyKey to make retries safe.

Параметри

Приклади виклику

{
  "idempotencyKey": "reference-lesson-0001",
  "lesson": {
    "title": "Get by: living on little",
    "description": "A short text and exercises on the phrasal verb «get by».",
    "subject": "angliyska-mova",
    "level": "b1",
    "outputLanguage": "uk",
    "worksheets": [
      {
        "title": "Get by",
        "purpose": "classwork",
        "blocks": [
          {
            "type": "passage",
            "title": "Text",
            "content": {
              "paragraphs": [
                {
                  "id": "p1",
                  "text": "Anna moved to a new city with very little money. She could get by on bread and soup."
                }
              ],
              "numbered": false,
              "truncated": false
            }
          },
          {
            "type": "vocabulary",
            "title": "Words",
            "content": {
              "items": [
                {
                  "id": "v1",
                  "expression": "get by",
                  "meaning": "давати собі раду",
                  "ipa": null,
                  "sourceLine": null
                }
              ]
            }
          },
          {
            "type": "mcq",
            "title": "Choose the meaning",
            "instruction": "Choose the correct answer.",
            "content": {
              "questions": [
                {
                  "id": "q1",
                  "text": "What does «get by» mean?",
                  "options": [
                    {
                      "key": "a",
                      "text": "to manage with little"
                    },
                    {
                      "key": "b",
                      "text": "to walk past"
                    }
                  ]
                }
              ]
            },
            "answerKey": {
              "items": {
                "q1": {
                  "field": "choice",
                  "value": "a"
                }
              }
            }
          },
          {
            "type": "gap_fill",
            "title": "Fill the gap",
            "content": {
              "items": [
                {
                  "id": "g1",
                  "before": "She could",
                  "after": "on very little."
                }
              ]
            },
            "answerKey": {
              "items": {
                "g1": {
                  "field": "gap",
                  "value": "get by"
                }
              }
            }
          },
          {
            "type": "matching",
            "title": "Match",
            "content": {
              "left": [
                {
                  "id": "l1",
                  "text": "get by"
                }
              ],
              "right": [
                {
                  "key": "r1",
                  "text": "давати собі раду"
                },
                {
                  "key": "r2",
                  "text": "зазирнути"
                }
              ]
            },
            "answerKey": {
              "items": {
                "l1": {
                  "field": "match",
                  "value": "r1"
                }
              }
            }
          },
          {
            "type": "open_prompt",
            "title": "Your answer",
            "content": {
              "response_mode": "per_prompt",
              "lines": 3,
              "prompts": [
                {
                  "id": "o1",
                  "text": "How do you get by when money is tight?"
                }
              ],
              "shared_label": null
            }
          },
          {
            "type": "translation",
            "title": "Translate",
            "content": {
              "direction": "to_content",
              "items": [
                {
                  "id": "t1",
                  "source": "Вона якось дає собі раду."
                }
              ]
            },
            "answerKey": {
              "items": {
                "t1": {
                  "field": "translation",
                  "value": "She somehow gets by.",
                  "compare": "sentence"
                }
              }
            }
          },
          {
            "type": "callout",
            "content": {
              "tone": "info",
              "label": null,
              "text": "Bring your dictionaries on Friday."
            }
          }
        ]
      }
    ]
  }
}

Приклад результату

{
  "lessonId": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
  "reviewUrl": "https://mentor.chitay.org.ua/app/worksheets/4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
  "worksheets": [
    {
      "id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
      "blockIds": [
        "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e"
      ]
    }
  ]
}

tutor_generate_lesson

Запускає створення уроку самою платформою — за темою, статтею, відео чи транскриптом, як у вебформі.

Потрібний дозвіл: write · validation_failed, quota_exceeded, idempotency_conflict, not_found, archived

Start AI generation of a lesson from a topic, article text or link, YouTube link, or transcript, like the web form; uses the teacher's daily generation quota. Returns lessonId at once; poll tutor_get_generation_status. With courseId the lesson is written for that course (its level, goals and earlier lessons, no repeats) and added at position (default last); subject and level default to the course's. generateExercises: true also writes the plan and exercises; otherwise generation stops at the plan step for the teacher. To write blocks yourself use tutor_create_lesson.

Параметри

Приклади виклику

{
  "idempotencyKey": "generate-present-perfect-01",
  "lessonType": "topic",
  "subject": "angliyska-mova",
  "outputLanguage": "uk",
  "topic": "Present Perfect",
  "level": "b1"
}

{
  "idempotencyKey": "course-b1-lesson-04",
  "lessonType": "topic",
  "outputLanguage": "uk",
  "topic": "Past Simple: irregular verbs",
  "courseId": "2d6a1c40-7b3e-4f58-a1c9-5e0b8d3f7a12",
  "generateExercises": true
}

{
  "lessonType": "youtube",
  "subject": "angliyska-mova",
  "outputLanguage": "uk",
  "sourceUrl": "https://www.youtube.com/watch?v=jNQXAC9IVRw"
}

Приклад результату

{
  "lessonId": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
  "status": "generating",
  "reviewUrl": "https://mentor.chitay.org.ua/app/worksheets/4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
  "course": {
    "courseId": "2d6a1c40-7b3e-4f58-a1c9-5e0b8d3f7a12",
    "lessonNumber": 4,
    "lessonsInCourse": 4,
    "previousLessonTitle": "Past Simple: regular verbs",
    "nextLessonTitle": null,
    "coveredItems": 36
  }
}

tutor_add_block

Додає один готовий блок в аркуш — в кінець або на вказану позицію.

Потрібний дозвіл: write · validation_failed, not_found

Add one finished block to a worksheet. Appended at the end unless position (0-based) is given. Returns blockId and the worksheet's new block order.

Параметри

Приклади виклику

{
  "worksheetId": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "block": {
    "type": "callout",
    "content": {
      "tone": "info",
      "label": "Note",
      "text": "Bring dictionaries."
    }
  }
}

{
  "worksheetId": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "block": {
    "type": "callout",
    "content": {
      "tone": "info",
      "label": "Note",
      "text": "Bring dictionaries."
    }
  },
  "position": 0
}

Приклад результату

{
  "blockId": "c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f",
  "blockIds": [
    "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
    "c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f"
  ]
}

tutor_update_block

Змінює поля одного блоку; тип блоку не змінюється, вміст перевіряється разом із ключем.

Потрібний дозвіл: write · validation_failed, not_found

Change fields of one block. A block keeps its type. When content is sent it is validated together with answerKey (the given one, or the stored one; null clears it).

Параметри

Приклади виклику

{
  "blockId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
  "title": "Warm-up note"
}

{
  "blockId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
  "content": {
    "tone": "info",
    "label": "Note",
    "text": "Bring a pen."
  }
}

Приклад результату

{
  "blockId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
  "updatedAt": "2026-09-30T10:05:00Z"
}

tutor_delete_block

Прибирає блок з аркуша (м’яке видалення, як у вебредакторі).

Потрібний дозвіл: write · not_found

Remove one block from its worksheet. It is archived, not destroyed, so a student answer already written against it keeps its prompt.

Параметри

Приклади виклику

{
  "blockId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e"
}

Приклад результату

{
  "blockId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
  "deleted": true
}

tutor_reorder_blocks

Задає новий порядок блоків аркуша; треба передати всі блоки аркуша, кожен один раз.

Потрібний дозвіл: write · validation_failed, not_found

Set the order of a worksheet's blocks. blockIds must be exactly the worksheet's current blocks, each once; missing and unknown ids are listed in the error.

Параметри

Приклади виклику

{
  "worksheetId": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "blockIds": [
    "c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f",
    "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e"
  ]
}

Приклад результату

{
  "blockIds": [
    "c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f",
    "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e"
  ]
}

tutor_update_lesson

Змінює назву, опис, предмет, рівень або мову формулювань уроку; оновлюються лише передані поля.

Потрібний дозвіл: write · validation_failed, not_found

Change a lesson’s title, description, subject, level or instruction language; only sent fields change, null clears description or level.

Параметри

Приклади виклику

{
  "lessonId": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
  "title": "Lesson 1: Ordering food"
}

Приклад результату

{
  "lessonId": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
  "title": "Lesson 1: Ordering food",
  "updatedAt": "2026-09-30T10:20:00Z",
  "reviewUrl": "https://mentor.chitay.org.ua/app/worksheets/4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23"
}

tutor_archive_lesson

Прибирає урок із бібліотеки (архівує, не знищує): вчитель може його повернути у вебзастосунку.

Потрібний дозвіл: write · not_found

Remove a lesson from the library. It is archived, not destroyed; the teacher can restore it in the web app. Its course steps stay: use tutor_remove_lesson_from_course.

Параметри

Приклади виклику

{
  "lessonId": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23"
}

Приклад результату

{
  "lessonId": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
  "archived": true
}

tutor_create_course

Створює порожній приватний курс; уроки додаються окремим інструментом.

Потрібний дозвіл: write · validation_failed, limit_reached

Create an empty private course, then add lessons with tutor_add_lesson_to_course. Returns courseId and a reviewUrl. Fails with limit_reached when the teacher has the maximum number of active courses.

Параметри

Приклади виклику

{
  "title": "English B1: everyday phrasal verbs",
  "subject": "angliyska-mova",
  "level": "b1",
  "contentLanguage": "en"
}

Приклад результату

{
  "courseId": "5a7e1f02-3b4c-4d5e-8f60-718293a4b5c6",
  "reviewUrl": "https://mentor.chitay.org.ua/app/courses/5a7e1f02-3b4c-4d5e-8f60-718293a4b5c6"
}

tutor_update_course

Змінює поля курсу: оновлюються лише передані поля, null очищає необов’язкове.

Потрібний дозвіл: write · validation_failed, not_found, archived, conflict

Change fields of a course. Only the fields you send change; null clears an optional field. Fails with archived for an archived course, conflict for a locked pacing.

Параметри

Приклади виклику

{
  "courseId": "5a7e1f02-3b4c-4d5e-8f60-718293a4b5c6",
  "description": "Twelve lessons on phrasal verbs.",
  "level": null
}

{
  "courseId": "5a7e1f02-3b4c-4d5e-8f60-718293a4b5c6",
  "forWhom": [
    "**B2–C1** learners who want to speak English more naturally",
    "those who confuse *be going to* and *be about to*"
  ],
  "outcomes": [
    "You can talk about plans and probability with confidence"
  ]
}

Приклад результату

{
  "courseId": "5a7e1f02-3b4c-4d5e-8f60-718293a4b5c6",
  "updatedAt": "2026-09-30T10:20:00Z"
}

tutor_add_lesson_to_course

Додає наявний урок до курсу — в кінець або на вказане місце (нумерація з 1).

Потрібний дозвіл: write · not_found, archived, validation_failed

Add an existing lesson to a course, at the end or at position (1 = first lesson; later lessons move down). Returns the lesson ids in course order. The same lesson may be added twice. Fails with archived for an archived course or lesson.

Параметри

Приклади виклику

{
  "courseId": "5a7e1f02-3b4c-4d5e-8f60-718293a4b5c6",
  "lessonId": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23"
}

{
  "courseId": "5a7e1f02-3b4c-4d5e-8f60-718293a4b5c6",
  "lessonId": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
  "position": 1
}

Приклад результату

{
  "stepId": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
  "position": 2,
  "lessonIds": [
    "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
    "0e9d8c7b-6a5f-4e4d-8c3b-2a1f0e9d8c7b"
  ],
  "warnings": []
}

tutor_remove_lesson_from_course

Прибирає урок із курсу за id кроку; сам урок залишається в бібліотеці.

Потрібний дозвіл: write · not_found, archived

Take one lesson out of a course by stepId (from tutor_get_course); the lesson stays in the library. A lesson added twice has two stepIds. Fails with archived for an archived course.

Параметри

Приклади виклику

{
  "courseId": "5a7e1f02-3b4c-4d5e-8f60-718293a4b5c6",
  "stepId": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d"
}

Приклад результату

{
  "courseId": "5a7e1f02-3b4c-4d5e-8f60-718293a4b5c6",
  "stepId": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
  "removed": true
}

tutor_reorder_course_lessons

Задає новий порядок уроків курсу; треба передати всі кроки курсу, кожен один раз.

Потрібний дозвіл: write · not_found, archived, validation_failed

Set the order of a course’s lessons. stepIds must be exactly the current steps (from tutor_get_course), each once; problems are listed in the error. Fails with archived for an archived course.

Параметри

Приклади виклику

{
  "courseId": "5a7e1f02-3b4c-4d5e-8f60-718293a4b5c6",
  "stepIds": [
    "0e9d8c7b-6a5f-4e4d-8c3b-2a1f0e9d8c7b",
    "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d"
  ]
}

Приклад результату

{
  "courseId": "5a7e1f02-3b4c-4d5e-8f60-718293a4b5c6",
  "stepIds": [
    "0e9d8c7b-6a5f-4e4d-8c3b-2a1f0e9d8c7b",
    "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d"
  ]
}

tutor_publish

Публікує курс у каталозі або знімає з публікації; потрібен окремий дозвіл «publish» у токена.

Потрібний дозвіл: publish · not_found, not_entitled, publish_incomplete, archived

Put a course on the public storefront, or take it off. Publishing needs the course details complete (fails with publish_incomplete and lists what is missing) and a teacher account allowed to publish (not_entitled otherwise). Unpublishing does not end anyone already taking the course. Returns publicUrl when published.

Параметри

Приклади виклику

{
  "courseId": "2d6a1c40-7b3e-4f58-a1c9-5e0b8d3f7a12",
  "action": "publish"
}

{
  "courseId": "2d6a1c40-7b3e-4f58-a1c9-5e0b8d3f7a12",
  "action": "unpublish"
}

Приклад результату

{
  "courseId": "2d6a1c40-7b3e-4f58-a1c9-5e0b8d3f7a12",
  "visibility": "public",
  "publicUrl": "https://chitay.org.ua/kursy/english-b1-everyday"
}

callout — Примітка

A short boxed note: a goal, a warning or a language tip. The student reads it and answers nothing. tone is one of info, tip, warning.

Автоперевірка: ні · Обмеження: titleMaxChars: 200, descriptionMaxChars: 1000, instructionMaxChars: 2000, blocksPerWorksheet: 40

Поля вмісту (content)

Приклади виклику

{
  "tone": "tip",
  "label": "Порада",
  "text": "Вираз «get by» майже завжди стоїть із прийменником: get by on, get by with."
}

passage — Текст матеріалу

A reading text placed inside the worksheet, split into paragraphs with stable ids, so the student reads and answers in one place. Asks nothing of the student.

Автоперевірка: ні · Обмеження: titleMaxChars: 200, descriptionMaxChars: 1000, instructionMaxChars: 2000, blocksPerWorksheet: 40, passageMaxChars: 12000

Поля вмісту (content)

Приклади виклику

{
  "paragraphs": [
    {
      "id": "p1",
      "text": "Anna moved to a new city with very little money. For the first month she could get by on bread and soup."
    },
    {
      "id": "p2",
      "text": "Then she found a job in a small bookshop, and life became a little easier."
    }
  ],
  "numbered": false,
  "truncated": false
}

vocabulary — Словник уроку

A glossary of the lesson: expressions with their meaning and, optionally, pronunciation. Reference material: the student fills nothing in. Pair it with a matching or gap_fill block to practise the words.

Автоперевірка: ні · Обмеження: titleMaxChars: 200, descriptionMaxChars: 1000, instructionMaxChars: 2000, blocksPerWorksheet: 40

Поля вмісту (content)

Приклади виклику

{
  "items": [
    {
      "id": "v1",
      "expression": "get by",
      "meaning": "давати собі раду, якось обходитися",
      "ipa": null,
      "sourceLine": null
    },
    {
      "id": "v2",
      "expression": "make ends meet",
      "meaning": "зводити кінці з кінцями",
      "ipa": null,
      "sourceLine": null
    }
  ]
}

table — Таблиця

A table: a reference chart, a checklist, or a grid the student fills in. A column with role "fixed" is printed; a column with role "response" is left for the student to write in.

Автоперевірка: ні · Обмеження: titleMaxChars: 200, descriptionMaxChars: 1000, instructionMaxChars: 2000, blocksPerWorksheet: 40, itemsField: rows, suggestedItemsMax: 20

Поля вмісту (content)

Приклади виклику

{
  "columns": [
    {
      "key": "verb",
      "label": "Дієслово",
      "role": "fixed"
    },
    {
      "key": "meaning",
      "label": "Значення",
      "role": "fixed"
    },
    {
      "key": "own",
      "label": "Ваше речення",
      "role": "response",
      "input": "text"
    }
  ],
  "rows": [
    {
      "id": "r1",
      "cells": [
        {
          "column": "verb",
          "value": "get by"
        },
        {
          "column": "meaning",
          "value": "давати собі раду"
        }
      ]
    },
    {
      "id": "r2",
      "cells": [
        {
          "column": "verb",
          "value": "get over"
        },
        {
          "column": "meaning",
          "value": "оговтатися"
        }
      ]
    }
  ]
}

open_prompt — Відкриті запитання

Open questions with no single right answer, for writing or discussion. response_mode is per_prompt (a box under each question) or shared (one box for all). Never scored; answerKey.modelAnswers may hold a sample answer per prompt id, shown to the student only after review.

Автоперевірка: ні · Обмеження: titleMaxChars: 200, descriptionMaxChars: 1000, instructionMaxChars: 2000, blocksPerWorksheet: 40, itemsField: prompts, suggestedItemsMax: 20

Поля вмісту (content)

Приклади виклику

{
  "response_mode": "per_prompt",
  "lines": 3,
  "prompts": [
    {
      "id": "o1",
      "text": "How do you get by when money is tight?"
    },
    {
      "id": "o2",
      "text": "What would you never give up, even on a small budget?"
    }
  ],
  "shared_label": null
}

writing — Письмове завдання

A longer writing task: a choice of topics, a target length as a word range (word_target, or null), and optional constraints: use_expressions asks the student to use count expressions from the lesson. choose says how many prompts the student picks. Never scored; answerKey.modelAnswers may hold a sample under the key _block.

Автоперевірка: ні · Обмеження: titleMaxChars: 200, descriptionMaxChars: 1000, instructionMaxChars: 2000, blocksPerWorksheet: 40

Поля вмісту (content)

Приклади виклику

{
  "prompts": [
    {
      "id": "w1",
      "text": "Describe a time when you had to get by with very little."
    },
    {
      "id": "w2",
      "text": "Write advice for a student who has just moved to a new city."
    }
  ],
  "choose": 1,
  "word_target": {
    "min": 60,
    "max": 100
  },
  "constraints": [
    {
      "kind": "use_expressions",
      "count": 2
    }
  ],
  "planning_label": null,
  "final_label": null
}

mcq — Варіанти відповіді

Multiple choice: each question has two or more options with unique keys, and exactly one correct key in the answer key. Auto-scored. optionNotes in the key may explain why a wrong option fails; it stays hidden until the reveal.

Автоперевірка: так, потрібен ключ відповідей · Обмеження: titleMaxChars: 200, descriptionMaxChars: 1000, instructionMaxChars: 2000, blocksPerWorksheet: 40, itemsField: questions, suggestedItemsMax: 20

Поля вмісту (content)

Приклади виклику

{
  "questions": [
    {
      "id": "q1",
      "text": "Що означає «get by» у реченні «She could get by on bread and soup»?",
      "options": [
        {
          "key": "a",
          "text": "давати собі раду"
        },
        {
          "key": "b",
          "text": "проходити повз"
        },
        {
          "key": "c",
          "text": "отримувати подарунки"
        }
      ]
    },
    {
      "id": "q2",
      "text": "Яке речення означає «ледве зводити кінці з кінцями»?",
      "options": [
        {
          "key": "a",
          "text": "They can barely make ends meet."
        },
        {
          "key": "b",
          "text": "They can barely make a meal."
        }
      ]
    }
  ]
}

Ключ відповідей (answerKey)

{
  "items": {
    "q1": {
      "field": "choice",
      "value": "a",
      "explanation": "«Get by» — справлятися з малими ресурсами."
    },
    "q2": {
      "field": "choice",
      "value": "a"
    }
  }
}

gap_fill — Пропущені слова

Sentences with a gap between before and after; the student types the missing word or phrase. Auto-scored against value and the optional accept variants (case- and space-insensitive).

Автоперевірка: так, потрібен ключ відповідей · Обмеження: titleMaxChars: 200, descriptionMaxChars: 1000, instructionMaxChars: 2000, blocksPerWorksheet: 40, itemsField: items, suggestedItemsMax: 20

Поля вмісту (content)

Приклади виклику

{
  "items": [
    {
      "id": "g1",
      "before": "She could",
      "after": "on very little."
    },
    {
      "id": "g2",
      "before": "It is hard to",
      "after": "in a big city without a job."
    }
  ]
}

Ключ відповідей (answerKey)

{
  "items": {
    "g1": {
      "field": "gap",
      "value": "get by"
    },
    "g2": {
      "field": "gap",
      "value": "get by",
      "accept": [
        "make ends meet"
      ]
    }
  }
}

matching — Відповідність

Two columns: the student pairs each left item with one right item. The right column needs at least as many entries as the left, so extra distractors are allowed. Auto-scored.

Автоперевірка: так, потрібен ключ відповідей · Обмеження: titleMaxChars: 200, descriptionMaxChars: 1000, instructionMaxChars: 2000, blocksPerWorksheet: 40, itemsField: left, suggestedItemsMax: 20

Поля вмісту (content)

Приклади виклику

{
  "left": [
    {
      "id": "l1",
      "text": "get by"
    },
    {
      "id": "l2",
      "text": "make ends meet"
    }
  ],
  "right": [
    {
      "key": "r1",
      "text": "давати собі раду"
    },
    {
      "key": "r2",
      "text": "зводити кінці з кінцями"
    },
    {
      "key": "r3",
      "text": "зазирнути"
    }
  ]
}

Ключ відповідей (answerKey)

{
  "items": {
    "l1": {
      "field": "match",
      "value": "r1"
    },
    "l2": {
      "field": "match",
      "value": "r2"
    }
  }
}

video_watch — Подивитися відео

A video for the student to watch, with optional things to watch for. Asks for no answers. videoId is a YouTube id; the title, channel, duration and thumbnail are shown as given.

Автоперевірка: ні · Обмеження: titleMaxChars: 200, descriptionMaxChars: 1000, instructionMaxChars: 2000, blocksPerWorksheet: 40

Поля вмісту (content)

Приклади виклику

{
  "videoId": "jNQXAC9IVRw",
  "title": "Me at the zoo",
  "channel": "jawed",
  "durationSec": 19,
  "thumbnailUrl": "https://i.ytimg.com/vi/jNQXAC9IVRw/hqdefault.jpg",
  "watchFor": [
    "Where is the speaker?",
    "What does he say about the animals?"
  ]
}

video_listening — На слух

Listening gaps: the student hears a moment of the video and types the missing words. clip may point at a time range of the video, or be null to leave it to the whole video. Auto-scored like gap_fill.

Автоперевірка: так, потрібен ключ відповідей · Обмеження: titleMaxChars: 200, descriptionMaxChars: 1000, instructionMaxChars: 2000, blocksPerWorksheet: 40, itemsField: items, suggestedItemsMax: 20

Поля вмісту (content)

Приклади виклику

{
  "items": [
    {
      "id": "i1",
      "before": "The cool thing about these guys is that they have",
      "after": "trunks.",
      "clip": null
    },
    {
      "id": "i2",
      "before": "And that is",
      "after": "to say about that.",
      "clip": null
    }
  ]
}

Ключ відповідей (answerKey)

{
  "items": {
    "i1": {
      "field": "gap",
      "value": "really, really, really long"
    },
    "i2": {
      "field": "gap",
      "value": "pretty much all there is"
    }
  }
}

video_comprehension — Розуміння відео

Multiple-choice questions about a video, in the same shape as mcq. clip may point at the relevant moment, or be null. Auto-scored.

Автоперевірка: так, потрібен ключ відповідей · Обмеження: titleMaxChars: 200, descriptionMaxChars: 1000, instructionMaxChars: 2000, blocksPerWorksheet: 40, itemsField: items, suggestedItemsMax: 20

Поля вмісту (content)

Приклади виклику

{
  "items": [
    {
      "id": "i1",
      "text": "Де знаходиться людина, що говорить у відео?",
      "options": [
        {
          "key": "a",
          "text": "У зоопарку"
        },
        {
          "key": "b",
          "text": "У школі"
        }
      ],
      "clip": null
    },
    {
      "id": "i2",
      "text": "Про яку особливість слонів він говорить?",
      "options": [
        {
          "key": "a",
          "text": "Про довгі хоботи"
        },
        {
          "key": "b",
          "text": "Про великі вуха"
        }
      ],
      "clip": null
    }
  ]
}

Ключ відповідей (answerKey)

{
  "items": {
    "i1": {
      "field": "choice",
      "value": "a"
    },
    "i2": {
      "field": "choice",
      "value": "a"
    }
  }
}

theory — Правило

A grammar rule for self-study: the rule in short sentences, an optional table, at least two examples with translations, and optionally a common mistake. Reference material, asks nothing; put a drill block after it.

Автоперевірка: ні · Обмеження: titleMaxChars: 200, descriptionMaxChars: 1000, instructionMaxChars: 2000, blocksPerWorksheet: 40

Поля вмісту (content)

Приклади виклику

{
  "rule": [
    "«Czy» відкриває загальне запитання, на яке відповідають «так» або «ні».",
    "Порядок слів у реченні не змінюється: «czy» просто ставиться на початок."
  ],
  "table": {
    "columns": [
      "Твердження",
      "Запитання"
    ],
    "rows": [
      [
        "Ona jest w domu.",
        "Czy ona jest w domu?"
      ],
      [
        "Masz czas.",
        "Czy masz czas?"
      ]
    ]
  },
  "examples": [
    {
      "id": "e1",
      "text": "Czy masz czas?",
      "translation": "У тебе є час?"
    },
    {
      "id": "e2",
      "text": "Nie wiem, czy przyjdzie.",
      "translation": "Не знаю, чи він прийде."
    }
  ],
  "commonMistake": "Не плутайте «czy» («чи») з «że» («що»).",
  "sourceNote": null
}

translation — Переклад речень

Sentence translation. direction says which way: to_content translates the given source into the lesson language, from_content the other way. The key holds the reference translation; compare "sentence" tolerates punctuation and case, "text" compares the words exactly.

Автоперевірка: так, потрібен ключ відповідей · Обмеження: titleMaxChars: 200, descriptionMaxChars: 1000, instructionMaxChars: 2000, blocksPerWorksheet: 40, itemsField: items, suggestedItemsMax: 20

Поля вмісту (content)

Приклади виклику

{
  "direction": "to_content",
  "items": [
    {
      "id": "t1",
      "source": "Не знаю, чи вона прийде."
    },
    {
      "id": "t2",
      "source": "У тебе є час?"
    }
  ]
}

Ключ відповідей (answerKey)

{
  "items": {
    "t1": {
      "field": "translation",
      "value": "Nie wiem, czy ona przyjdzie.",
      "compare": "sentence"
    },
    "t2": {
      "field": "translation",
      "value": "Czy masz czas?",
      "compare": "sentence"
    }
  }
}