Довідник
Довідник формується з реєстру інструментів сервера, тож збігається з тим, що бачить агент у tools/list. Описи інструментів — англійською, бо їх читає агент; біля кожного є короткий опис українською.
Інструменти
tutor_list_lessons
Список уроків викладача, спершу ті, що змінювалися нещодавно; можна шукати за назвою.
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 | string | ні | до 100 символів | |
limit | integer | ні | від 1 до 50 | |
cursor | string | ні | до 500 символів |
Приклади виклику
{}{
"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 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 | string | так | UUID |
Приклади виклику
{
"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
Читає один блок: тип, інструкцію, вміст і ключ, разом з ідентифікаторами аркуша й уроку.
Read one block: its worksheet and lesson ids, position, type, instruction, content and answerKey. Use it to rewrite one exercise without reading the whole lesson.
Параметри
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
blockId | string | так | UUID |
Приклади виклику
{
"blockId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e"
}Приклад результату
{
"blockId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
"lessonId": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
"worksheetId": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"worksheetTitle": "Самостійна робота",
"position": 3,
"type": "callout",
"title": "",
"description": "",
"instruction": "",
"content": {
"tone": "info",
"label": "Note",
"text": "Bring dictionaries."
},
"answerKey": null,
"generationStatus": "completed",
"authoring": "teacher"
}tutor_get_block_schema
Описує один тип блоку: призначення, схему вмісту й ключа, обмеження та готовий приклад.
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 | string | так | одне з: callout, passage, vocabulary, table, open_prompt, writing, mcq, gap_fill, matching, video_watch, video_listening, video_comprehension, theory, translation, miro_board |
Приклади виклику
{
"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
}
},
"images": {
"type": "array",
"items": {
"type": "object",
"properties": {
"assetId": {
"type": "string"
},
"path": {
"type": "string"
},
"width": {
"type": "number"
},
"height": {
"type": "number"
},
"alt": {
"type": [
"string",
"null"
]
}
},
"required": [
"assetId",
"path",
"width",
"height"
],
"additionalProperties": false
},
"maxItems": 5
},
"imageSlot": {
"type": [
"object",
"null"
],
"properties": {
"want": {
"type": "string",
"maxLength": 200
}
},
"required": [
"want"
],
"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": 20,
"itemsField": "items",
"suggestedItemsMax": 20
},
"authoring": {
"note": "Sentences with one gap each. Write a real full sentence with ______; one correct answer per gap, with variants in the key.",
"guide": "tutor_get_authoring_guide"
},
"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
Список курсів викладача з кількістю уроків і лімітом активних курсів.
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 | boolean | ні | ||
limit | integer | ні | від 1 до 50 | |
cursor | string | ні | до 500 символів |
Приклади виклику
{}{
"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 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. briefFor returns a brief to write the lesson at that number from: what the earlier lessons taught.
Параметри
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
courseId | string | так | UUID | |
briefFor | object | ні | ||
briefFor.position | integer | ні | від 1 |
Приклади виклику
{
"courseId": "5a7e1f02-3b4c-4d5e-8f60-718293a4b5c6"
}{
"courseId": "5a7e1f02-3b4c-4d5e-8f60-718293a4b5c6",
"briefFor": {}
}Приклад результату
{
"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
}
],
"brief": {
"text": "About the course:\nThis lesson is lesson 2 of 2 in the course «English B1». …",
"summary": {
"lessonNumber": 2,
"lessonsInCourse": 2,
"previousLessonTitle": "Ordering food",
"nextLessonTitle": null,
"coveredItems": 12
}
}
}tutor_get_upload
Перевіряє, чи викладач уже додав файли за посиланням з tutor_upload_images.
Check a link from tutor_upload_images (mode link or drop). Returns status waiting, done or expired, and the assetIds uploaded so far.
Параметри
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
linkId | string | так | UUID |
Приклади виклику
{
"linkId": "9b2d4c1e-6a3f-4e7b-8d05-1c2e3f4a5b6c"
}Приклад результату
{
"status": "done",
"assetIds": [
"3f1c0a52-7d4e-4b8a-9c11-5e2f6a7b8c90"
]
}tutor_read_source
Читає субтитри відео YouTube (із часом) або текст статті, щоб написати урок. Нічого не зберігає.
Read the captions of a YouTube video (timed segments) or the text of an article, to write a lesson from. Nothing is stored. language is the content language code (e.g. en), which picks the caption track. Limited to 30 reads per day.
Параметри
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
url | string | так | від 1 до 2000 символів | |
language | string | так | від 2 до 20 символів |
Приклади виклику
{
"url": "https://www.youtube.com/watch?v=abcdefghijk",
"language": "en"
}Приклад результату
{
"kind": "video",
"url": "https://www.youtube.com/watch?v=abcdefghijk",
"title": "How to learn a language",
"channel": "Example channel",
"durationSec": 300,
"language": "en",
"autoCaptions": false,
"segments": [
{
"start": 0,
"end": 4.5,
"text": "Hello and welcome."
}
],
"truncated": false
}tutor_list_images
Список зображень викладача, найновіші першими.
List the teacher's uploaded images, newest first, with assetId, size, alt and how many blocks use each. Pass nextCursor back as cursor for the next page.
Параметри
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
limit | integer | ні | від 1 до 50 | |
cursor | string | ні | до 500 символів |
Приклади виклику
{
"limit": 20
}Приклад результату
{
"items": [
{
"assetId": "3f1c0a52-7d4e-4b8a-9c11-5e2f6a7b8c90",
"width": 1600,
"height": 1200,
"bytes": 184233,
"alt": null,
"usageCount": 1,
"createdAt": "2026-10-05T09:30:00Z",
"previewUrl": "https://mentor.chitay.org.ua/assets/images/tutor/u1/3f1c0a52.webp"
}
],
"nextCursor": null,
"quota": {
"usedMb": 42,
"limitMb": 500
}
}tutor_create_lesson
Створює цілий урок — аркуші й блоки — одним викликом: або все, або нічого.
Create a complete lesson with worksheets and blocks in one all-or-nothing call. A worksheet holds at most 20 blocks: split a larger lesson across worksheets. Mentor does not write content: read tutor_get_authoring_guide first. Every problem is reported at once with its path; nothing is created if any exist. Warnings never block the save. Returns lessonId and a reviewUrl for the teacher. Send idempotencyKey to make retries safe.
Параметри
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
idempotencyKey | string | ні | A unique string per intended lesson, 8–100 letters, digits, - or _. A retry with the same key returns the first result. | |
course | object | ні | Add the lesson to this course in the same all-or-nothing call. position is 1-based; the default is the end. | |
course.courseId | string | так | UUID | |
course.position | integer | ні | від 1 | |
lesson | object | так | ||
lesson.title | string | ні | до 300 символів | |
lesson.description | string | ні | до 1000 символів | Markdown subset: **bold** *italic* ~~strike~~, blank-line paragraphs. ≤500 visible chars. |
lesson.subject | string | так | одне з: angliyska-mova, nimetska-mova, polska-mova, ukrainska-mova, bolharska-mova, hahauska-mova, danska-mova, estonska-mova, ivryt, ispanska-mova, italiiska-mova, krymskotatar-mova, latviiska-mova, lytovska-mova, niderlandska-mova, novohretska-mova, norvezka-mova, portuhalska-mova, rumunska-mova, serbska-mova, slovatska-mova, slovenska-mova, turetska-mova, uhorska-mova, finska-mova, frantsuzka-mova, horvatska-mova, cheska-mova, shvedska-mova | |
lesson.level | string | ні | одне з: a1, a2, b1, b2, c1, c2, pochatkovyi, serednii, prosunutyi | |
lesson.outputLanguage | string | так | до 20 символів | Language of the instructions, e.g. uk or en. |
lesson.worksheets | array<object> | так | від 1 до 10 елементів | |
lesson.worksheets[].title | string | ні | до 300 символів | |
lesson.worksheets[].purpose | string | ні | одне з: classwork, homework, self_study | |
lesson.worksheets[].template | string | ні | одне з: grammar, vocabulary, source | The guide template this sheet follows; Mentor then returns warnings where it departs from it. |
lesson.worksheets[].blocks | array<object> | так | від 1 до 20 елементів | |
lesson.worksheets[].blocks[].type | string | так | одне з: callout, passage, vocabulary, table, open_prompt, writing, mcq, gap_fill, matching, video_watch, video_listening, video_comprehension, theory, translation, miro_board | |
lesson.worksheets[].blocks[].title | string | ні | ||
lesson.worksheets[].blocks[].description | string | ні | Shown above the block. **bold** *italic* ~~strike~~, paragraphs. ≤1000 visible. | |
lesson.worksheets[].blocks[].instruction | string | ні | ||
lesson.worksheets[].blocks[].content | object | так | Shape depends on the block type; see tutor_get_block_schema. | |
lesson.worksheets[].blocks[].answerKey | object | null | ні | Shape depends on the block type; see tutor_get_block_schema. |
Приклади виклику
{
"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."
}
}
]
}
]
}
}{
"idempotencyKey": "reference-lesson-0002",
"course": {
"courseId": "5a7e1f02-3b4c-4d5e-8f60-718293a4b5c6",
"position": 2
},
"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_copy_lesson
Копіює урок повністю — аркуші й блоки з вмістом і ключами; оригінал і робота студентів не змінюються.
Copy a whole lesson: all worksheets and blocks, with content and keys. The original, its assignments and student work are untouched. Title defaults to “Копія — ” plus the original title. Returns the new lessonId and its worksheets (id, title, purpose) so they can be edited next.
Параметри
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
lessonId | string | так | UUID | |
title | string | ні | від 1 до 200 символів |
Приклади виклику
{
"lessonId": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
"title": "Get by: living on little (self-study)"
}Приклад результату
{
"lessonId": "8b2e4d6f-1a3c-4e5b-9d7f-0c1a2b3d4e5f",
"title": "Копія — Get by: living on little",
"reviewUrl": "https://mentor.chitay.org.ua/app/worksheets/8b2e4d6f-1a3c-4e5b-9d7f-0c1a2b3d4e5f",
"worksheets": [
{
"id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"title": "Урок",
"purpose": "classwork",
"blockCount": 8
}
]
}tutor_add_block
Додає один готовий блок в аркуш — в кінець або на вказану позицію.
Add one finished block to a worksheet. Appended at the end unless position (0-based) is given. A worksheet holds at most 20 blocks; when it is full this returns limit_reached, so put the block on another worksheet. Returns blockId and the worksheet's new block order, and warnings when a check finds something in the block (the block is saved either way).
Параметри
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
worksheetId | string | так | UUID | |
block | object | так | ||
block.type | string | так | одне з: callout, passage, vocabulary, table, open_prompt, writing, mcq, gap_fill, matching, video_watch, video_listening, video_comprehension, theory, translation, miro_board | |
block.title | string | ні | ||
block.description | string | ні | Shown above the block. **bold** *italic* ~~strike~~, paragraphs. ≤1000 visible. | |
block.instruction | string | ні | ||
block.content | object | так | Shape depends on the block type; see tutor_get_block_schema. | |
block.answerKey | object | null | ні | Shape depends on the block type; see tutor_get_block_schema. | |
position | integer | ні | від 0 |
Приклади виклику
{
"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
Змінює поля одного блоку; тип блоку не змінюється, вміст перевіряється разом із ключем.
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). Changing instruction on a block not written by the teacher needs new content in the same call. Returns warnings when a check finds something in the block (the change is saved either way).
Параметри
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
blockId | string | так | UUID | |
title | string | ні | ||
instruction | string | ні | ||
description | string | ні | Shown above the block. **bold** *italic* ~~strike~~, paragraphs. ≤1000 visible. | |
content | object | ні | Shape depends on the block type; see tutor_get_block_schema. | |
answerKey | object | null | ні | Shape depends on the block type; see tutor_get_block_schema. |
Приклади виклику
{
"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",
"warnings": [
{
"worksheet": 0,
"blockIndex": 4,
"rule": "matching-duplicate",
"message": "Matching has the same right-hand text twice: \"für + Akk\".",
"expected": "Every text in a column differs.",
"text": "für + Akk"
}
]
}tutor_delete_block
Прибирає блок з аркуша (м’яке видалення, як у вебредакторі).
Remove one block from its worksheet. It is archived, not destroyed, so a student answer already written against it keeps its prompt.
Параметри
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
blockId | string | так | UUID |
Приклади виклику
{
"blockId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e"
}Приклад результату
{
"blockId": "b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e",
"deleted": true
}tutor_reorder_blocks
Задає новий порядок блоків аркуша; треба передати всі блоки аркуша, кожен один раз.
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 | string | так | UUID | |
blockIds | array<string> | так | від 1 елементів |
Приклади виклику
{
"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_upload_images
Додає 1–5 зображень до бібліотеки викладача: за адресою, файлом з ChatGPT, одноразовим посиланням для curl або сторінкою, яку відкриває викладач.
Add 1–5 images to the teacher's library and get assetIds to use in blocks. mode "url": public https image addresses. mode "file": files attached in ChatGPT. mode "link": a one-time upload URL for curl. mode "drop": a page the teacher opens to add files, then poll tutor_get_upload. PNG, JPEG or WebP, up to 20 MB each.
Параметри
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
mode | string | так | одне з: url, file, link, drop | |
urls | array<string> | ні | від 1 до 5 елементів | |
files | array<object> | ні | від 1 до 5 елементів | |
files[].download_url | string | так | до 4000 символів | |
files[].file_id | string | так | до 200 символів | |
files[].mime_type | string | ні | до 100 символів | |
files[].file_name | string | ні | до 300 символів | |
alt | array<string> | ні | до 5 елементів | |
count | integer | ні | від 1 до 5 |
Приклади виклику
{
"mode": "url",
"urls": [
"https://chitay.org.ua/assets/tests/images/example/1.png"
],
"alt": [
"Оголошення про оренду кімнати"
]
}{
"mode": "drop",
"count": 3
}{
"mode": "link",
"count": 1
}Приклад результату
{
"results": [
{
"ok": true,
"assetId": "3f1c0a52-7d4e-4b8a-9c11-5e2f6a7b8c90",
"width": 1600,
"height": 1200,
"bytes": 184233,
"previewUrl": "https://mentor.chitay.org.ua/assets/images/tutor/u1/3f1c0a52.webp"
}
],
"quota": {
"usedMb": 42,
"limitMb": 500
}
}tutor_update_image
Змінює опис зображення (alt) у бібліотеці й у всіх блоках, де воно є.
Set the alt text of an image (null clears it). It also changes every block that shows the image.
Параметри
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
assetId | string | так | UUID | |
alt | string | null | так | до 300 символів |
Приклади виклику
{
"assetId": "3f1c0a52-7d4e-4b8a-9c11-5e2f6a7b8c90",
"alt": "Оголошення про оренду кімнати"
}Приклад результату
{
"assetId": "3f1c0a52-7d4e-4b8a-9c11-5e2f6a7b8c90",
"alt": "Оголошення про оренду кімнати",
"previewUrl": "https://mentor.chitay.org.ua/assets/images/tutor/u1/3f1c0a52.webp"
}tutor_delete_image
Видаляє зображення з бібліотеки та з усіх блоків; без confirm лише показує, де воно використовується.
Delete an image and remove it from every block that uses it. Without confirm: true it deletes nothing and lists where the image is used; ask the teacher before confirming.
Параметри
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
assetId | string | так | UUID | |
confirm | boolean | ні |
Приклади виклику
{
"assetId": "3f1c0a52-7d4e-4b8a-9c11-5e2f6a7b8c90"
}{
"assetId": "3f1c0a52-7d4e-4b8a-9c11-5e2f6a7b8c90",
"confirm": true
}Приклад результату
{
"deleted": true,
"strippedBlocks": 2
}tutor_update_lesson
Змінює назву, опис, предмет, рівень, мову формулювань або назву першого аркуша уроку; оновлюються лише передані поля.
Change a lesson’s title, description, subject, level, instruction language or the first sheet’s title (worksheetTitle); only sent fields change, null clears description or level.
Параметри
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
lessonId | string | так | UUID | |
title | string | ні | від 1 до 300 символів | |
description | string | null | ні | до 1000 символів | Markdown subset: **bold** *italic* ~~strike~~, blank-line paragraphs. ≤500 visible chars. |
subject | string | ні | одне з: angliyska-mova, nimetska-mova, polska-mova, ukrainska-mova, bolharska-mova, hahauska-mova, danska-mova, estonska-mova, ivryt, ispanska-mova, italiiska-mova, krymskotatar-mova, latviiska-mova, lytovska-mova, niderlandska-mova, novohretska-mova, norvezka-mova, portuhalska-mova, rumunska-mova, serbska-mova, slovatska-mova, slovenska-mova, turetska-mova, uhorska-mova, finska-mova, frantsuzka-mova, horvatska-mova, cheska-mova, shvedska-mova | |
level | string | null | ні | одне з: a1, a2, b1, b2, c1, c2, pochatkovyi, serednii, prosunutyi, | |
outputLanguage | string | ні | одне з: uk, en, bg, gag, da, et, he, es, it, crh, lv, lt, nl, de, el, no, pl, pt, ro, sr, sk, sl, tr, hu, fi, fr, hr, cs, sv | |
worksheetTitle | string | ні | від 1 до 300 символів |
Приклади виклику
{
"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_update_worksheet
Перейменовує аркуш або змінює його вид (урок, домашнє, самонавчання); оновлюються лише передані поля.
Rename a worksheet or change its purpose (classwork, homework, self_study). Only sent fields change. A lesson has one live worksheet per purpose: conflict if another already has it.
Параметри
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
worksheetId | string | так | UUID | |
title | string | ні | від 1 до 200 символів | |
purpose | string | ні | одне з: classwork, homework, self_study |
Приклади виклику
{
"worksheetId": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"purpose": "self_study",
"title": "Самонавчання"
}Приклад результату
{
"worksheetId": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"lessonId": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
"title": "Самонавчання",
"purpose": "self_study",
"reviewUrl": "https://mentor.chitay.org.ua/app/worksheets/4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23"
}tutor_add_worksheet
Додає в наявний урок цілий аркуш із блоками одним викликом: або все, або нічого.
Add a complete worksheet with its blocks to an existing lesson, all or nothing. purpose is required; a lesson holds one live worksheet per purpose. Mentor does not write content: read tutor_get_authoring_guide first. Every problem is reported at once with its path; warnings never block the save. Send idempotencyKey to make retries safe.
Параметри
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
idempotencyKey | string | ні | A unique string per intended worksheet, 8–100 letters, digits, - or _. A retry with the same key returns the first result. | |
lessonId | string | так | UUID | |
worksheet | object | так | ||
worksheet.title | string | ні | до 300 символів | |
worksheet.purpose | string | так | одне з: classwork, homework, self_study | |
worksheet.template | string | ні | одне з: grammar, vocabulary, source | The guide template this sheet follows; Mentor then returns warnings where it departs from it. |
worksheet.blocks | array<object> | так | від 1 до 20 елементів | |
worksheet.blocks[].type | string | так | одне з: callout, passage, vocabulary, table, open_prompt, writing, mcq, gap_fill, matching, video_watch, video_listening, video_comprehension, theory, translation, miro_board | |
worksheet.blocks[].title | string | ні | ||
worksheet.blocks[].description | string | ні | Shown above the block. **bold** *italic* ~~strike~~, paragraphs. ≤1000 visible. | |
worksheet.blocks[].instruction | string | ні | ||
worksheet.blocks[].content | object | так | Shape depends on the block type; see tutor_get_block_schema. | |
worksheet.blocks[].answerKey | object | null | ні | Shape depends on the block type; see tutor_get_block_schema. | |
position | integer | ні | від 0 | Index among the lesson’s worksheets; default is the end. |
Приклади виклику
{
"idempotencyKey": "homework-sheet-0001",
"lessonId": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
"worksheet": {
"purpose": "homework",
"blocks": [
{
"type": "callout",
"content": {
"tone": "info",
"label": "Note",
"text": "Do it in writing."
}
}
]
}
}Приклад результату
{
"worksheetId": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"blockIds": [
"b1c2d3e4-f5a6-4b7c-8d9e-0f1a2b3c4d5e"
],
"reviewUrl": "https://mentor.chitay.org.ua/app/worksheets/4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23"
}tutor_delete_worksheet
Прибирає аркуш з уроку (архівує, не знищує); останній аркуш уроку прибрати не можна.
Remove one worksheet, with its blocks, from a lesson. It is archived, not destroyed, so student work stays readable and the teacher can restore it in the web app. A lesson’s last worksheet cannot be removed (conflict).
Параметри
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
worksheetId | string | так | UUID |
Приклади виклику
{
"worksheetId": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}Приклад результату
{
"worksheetId": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"deleted": true
}tutor_archive_lesson
Прибирає урок із бібліотеки (архівує, не знищує): викладач може його повернути у вебзастосунку.
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 | string | так | UUID |
Приклади виклику
{
"lessonId": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23"
}Приклад результату
{
"lessonId": "4f0c6b3e-8d1a-4c59-9f1e-2a7b9c0d1e23",
"archived": true
}tutor_create_course
Створює порожній приватний курс; уроки додаються окремим інструментом.
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 | string | так | від 1 до 200 символів | |
description | string | ні | до 4000 символів | Markdown subset: **bold** *italic* ~~strike~~, blank-line paragraphs, - / 1. lists, > quote. ≤2000 visible chars. |
subject | string | ні | одне з: ukrainska-mova, angliyska-mova, nimetska-mova, polska-mova, frantsuzka-mova, ispanska-mova, italiiska-mova, portuhalska-mova, novohretska-mova, rumunska-mova, uhorska-mova, shvedska-mova, norvezka-mova, finska-mova, danska-mova, cheska-mova, slovatska-mova, slovenska-mova, estonska-mova, latviiska-mova, lytovska-mova, horvatska-mova, serbska-mova, bolharska-mova, niderlandska-mova, turetska-mova, ivryt, krymskotatar-mova, hahauska-mova | |
level | string | ні | одне з: a1, a2, b1, b2, c1, c2, pochatkovyi, serednii, prosunutyi | |
contentLanguage | string | ні | одне з: uk, en, de, pl, fr, es, it, pt, el, ro, hu, sv, no, fi, da, cs, sk, sl, et, lv, lt, hr, sr, bg, nl, tr, he, crh, gag | Language the course is written in. |
pacing | string | ні | одне з: teacher_paced, self_paced | teacher_paced (default) or self_paced (student opens each next lesson). Fixed once anyone enrols. |
forWhom | array<string> | ні | до 8 елементів | Who the course is for, one point per item (≤200 visible chars). Only **bold**, *italic* and ~~strike~~ kept. null or [] clears. |
outcomes | array<string> | ні | до 8 елементів | What a learner gets after the course. Rules as forWhom. |
Приклади виклику
{
"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 очищає необов’язкове.
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 | string | так | UUID | |
title | string | ні | від 1 до 200 символів | |
description | string | null | ні | до 4000 символів | Markdown subset: **bold** *italic* ~~strike~~, blank-line paragraphs, - / 1. lists, > quote. ≤2000 visible chars. |
subject | string | null | ні | одне з: ukrainska-mova, angliyska-mova, nimetska-mova, polska-mova, frantsuzka-mova, ispanska-mova, italiiska-mova, portuhalska-mova, novohretska-mova, rumunska-mova, uhorska-mova, shvedska-mova, norvezka-mova, finska-mova, danska-mova, cheska-mova, slovatska-mova, slovenska-mova, estonska-mova, latviiska-mova, lytovska-mova, horvatska-mova, serbska-mova, bolharska-mova, niderlandska-mova, turetska-mova, ivryt, krymskotatar-mova, hahauska-mova, | |
level | string | null | ні | одне з: a1, a2, b1, b2, c1, c2, pochatkovyi, serednii, prosunutyi, | |
contentLanguage | string | null | ні | одне з: uk, en, de, pl, fr, es, it, pt, el, ro, hu, sv, no, fi, da, cs, sk, sl, et, lv, lt, hr, sr, bg, nl, tr, he, crh, gag, | Language the course is written in. |
pacing | string | ні | одне з: teacher_paced, self_paced | teacher_paced (default) or self_paced (student opens each next lesson). Fixed once anyone enrols. |
forWhom | array<string> | null | ні | до 8 елементів | Who the course is for, one point per item (≤200 visible chars). Only **bold**, *italic* and ~~strike~~ kept. null or [] clears. |
outcomes | array<string> | null | ні | до 8 елементів | What a learner gets after the course. Rules as forWhom. |
Приклади виклику
{
"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_archive_course
Архівує курс, щоб звільнити місце в ліміті курсів: курс не знищується, викладач може його повернути в Менторі.
Archive a course to free a slot at the course limit. Nothing is destroyed: the teacher can restore it in Mentor. Refused while students are taking it. Archived twice: no change.
Параметри
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
courseId | string | так | UUID |
Приклади виклику
{
"courseId": "5a7e1f02-3b4c-4d5e-8f60-718293a4b5c6"
}Приклад результату
{
"courseId": "5a7e1f02-3b4c-4d5e-8f60-718293a4b5c6",
"archived": true,
"alreadyArchived": false,
"note": "The course is hidden from the active list and no longer counts towards the course limit. The teacher can restore it in Mentor."
}tutor_add_lesson_to_course
Додає наявний урок до курсу — в кінець або на вказане місце (нумерація з 1).
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 | string | так | UUID | |
lessonId | string | так | UUID | |
position | integer | ні | від 1 |
Приклади виклику
{
"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 кроку; сам урок залишається в бібліотеці.
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 | string | так | UUID | |
stepId | string | так | UUID |
Приклади виклику
{
"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
Задає новий порядок уроків курсу; треба передати всі кроки курсу, кожен один раз.
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 | string | так | UUID | |
stepIds | array<string> | так | від 1 до 200 елементів |
Приклади виклику
{
"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» у токена.
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 | string | так | UUID | |
action | string | так | одне з: publish, unpublish |
Приклади виклику
{
"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"
}Допустимі значення
Поля subject і level приймають лише ці ідентифікатори (ті самі, що й форма в Менторі). Будь-яке інше значення інструмент відхилить.
Предмети (subject)
| Ідентифікатор | Назва |
|---|---|
angliyska-mova | Англійська мова |
nimetska-mova | Німецька мова |
polska-mova | Польська мова |
ukrainska-mova | Українська мова |
bolharska-mova | Болгарська мова |
hahauska-mova | Гагаузька мова |
danska-mova | Данська мова |
estonska-mova | Естонська мова |
ivryt | Іврит |
ispanska-mova | Іспанська мова |
italiiska-mova | Італійська мова |
krymskotatar-mova | Кримськотатарська мова |
latviiska-mova | Латвійська мова |
lytovska-mova | Литовська мова |
niderlandska-mova | Нідерландська мова |
novohretska-mova | Новогрецька мова |
norvezka-mova | Норвезька мова |
portuhalska-mova | Португальська мова |
rumunska-mova | Румунська мова |
serbska-mova | Сербська мова |
slovatska-mova | Словацька мова |
slovenska-mova | Словенська мова |
turetska-mova | Турецька мова |
uhorska-mova | Угорська мова |
finska-mova | Фінська мова |
frantsuzka-mova | Французька мова |
horvatska-mova | Хорватська мова |
cheska-mova | Чеська мова |
shvedska-mova | Шведська мова |
Рівні (level)
| Ідентифікатор | Назва |
|---|---|
a1 | A1 — початковий |
a2 | A2 — базовий |
b1 | B1 — середній |
b2 | B2 — вище середнього |
c1 | C1 — просунутий |
c2 | C2 — вільне володіння |
pochatkovyi | Початковий |
serednii | Середній |
prosunutyi | Просунутий |
Типи блоків
Типи блоків, з яких складається урок. Схему й приклад будь-якого типу агент отримує інструментом tutor_get_block_schema; кожен приклад нижче проходить ту саму перевірку, що й власні блоки викладача.
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.
Поля вмісту (content)
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
tone | string | так | одне з: warning, info, tip | |
label | string | null | ні | ||
text | string | так |
Приклади виклику
{
"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.
Поля вмісту (content)
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
paragraphs | array<object> | так | ||
paragraphs[].id | string | так | ||
paragraphs[].text | string | так | ||
numbered | boolean | ні | ||
truncated | boolean | ні | ||
images | array<object> | ні | до 5 елементів | |
images[].assetId | string | так | ||
images[].path | string | так | ||
images[].width | number | так | ||
images[].height | number | так | ||
images[].alt | string | null | ні | ||
imageSlot | object | null | ні | ||
imageSlot.want | string | так | до 200 символів |
Приклади виклику
{
"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.
Поля вмісту (content)
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
items | array<object> | так | ||
items[].id | string | так | ||
items[].expression | string | так | ||
items[].meaning | string | так | ||
items[].ipa | string | null | ні | ||
items[].sourceLine | string | null | ні | ||
items[].image | object | null | ні | ||
items[].image.assetId | string | так | ||
items[].image.path | string | так | ||
items[].image.width | number | так | ||
items[].image.height | number | так | ||
items[].image.alt | string | null | ні |
Приклади виклику
{
"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.
Поля вмісту (content)
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
columns | array<object> | так | ||
columns[].key | string | так | ||
columns[].label | string | так | ||
columns[].role | string | так | одне з: fixed, response | |
columns[].input | string | null | ні | одне з: text, textarea, checkbox, | |
rows | array<object> | так | ||
rows[].id | string | так | ||
rows[].cells | array<object> | так | ||
rows[].cells[].column | string | так | ||
rows[].cells[].value | string | так |
Приклади виклику
{
"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.
Поля вмісту (content)
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
response_mode | string | так | одне з: per_prompt, shared | |
lines | number | так | ||
prompts | array<object> | так | ||
prompts[].id | string | так | ||
prompts[].text | string | так | ||
shared_label | string | null | ні | ||
images | array<object> | ні | до 5 елементів | |
images[].assetId | string | так | ||
images[].path | string | так | ||
images[].width | number | так | ||
images[].height | number | так | ||
images[].alt | string | null | ні | ||
imageSlot | object | null | ні | ||
imageSlot.want | string | так | до 200 символів |
Приклади виклику
{
"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.
Поля вмісту (content)
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
prompts | array<object> | так | ||
prompts[].id | string | так | ||
prompts[].text | string | так | ||
choose | number | так | ||
word_target | object | null | ні | ||
word_target.min | number | так | ||
word_target.max | number | так | ||
constraints | array<object> | так | ||
constraints[].kind | string | так | одне з: use_expressions | |
constraints[].count | number | так | ||
planning_label | string | null | ні | ||
final_label | string | null | ні | ||
images | array<object> | ні | до 5 елементів | |
images[].assetId | string | так | ||
images[].path | string | так | ||
images[].width | number | так | ||
images[].height | number | так | ||
images[].alt | string | null | ні | ||
imageSlot | object | null | ні | ||
imageSlot.want | string | так | до 200 символів |
Приклади виклику
{
"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.
Поля вмісту (content)
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
questions | array<object> | так | ||
questions[].id | string | так | ||
questions[].text | string | так | ||
questions[].options | array<object> | так | ||
questions[].options[].key | string | так | ||
questions[].options[].text | string | так | ||
questions[].image | object | null | ні | ||
questions[].image.assetId | string | так | ||
questions[].image.path | string | так | ||
questions[].image.width | number | так | ||
questions[].image.height | number | так | ||
questions[].image.alt | string | null | ні |
Приклади виклику
{
"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).
Поля вмісту (content)
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
items | array<object> | так | ||
items[].id | string | так | ||
items[].before | string | так | ||
items[].after | string | так | ||
images | array<object> | ні | до 5 елементів | |
images[].assetId | string | так | ||
images[].path | string | так | ||
images[].width | number | так | ||
images[].height | number | так | ||
images[].alt | string | null | ні | ||
imageSlot | object | null | ні | ||
imageSlot.want | string | так | до 200 символів |
Приклади виклику
{
"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.
Поля вмісту (content)
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
left | array<object> | так | ||
left[].id | string | так | ||
left[].text | string | так | ||
left[].image | object | null | ні | ||
left[].image.assetId | string | так | ||
left[].image.path | string | так | ||
left[].image.width | number | так | ||
left[].image.height | number | так | ||
left[].image.alt | string | null | ні | ||
right | array<object> | так | ||
right[].key | string | так | ||
right[].text | string | так |
Приклади виклику
{
"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. Optional startSec and endSec (whole seconds) play only a fragment of the video; leave both out for the whole video, set one for an open start or end. endSec must be after startSec and not past durationSec.
Поля вмісту (content)
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
videoId | string | так | ||
title | string | так | ||
channel | string | так | ||
durationSec | number | так | ||
thumbnailUrl | string | так | ||
watchFor | array<string> | ні | ||
startSec | number | ні | ||
endSec | number | ні |
Приклади виклику
{
"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?"
],
"startSec": 4,
"endSec": 15
}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.
Поля вмісту (content)
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
items | array<object> | так | ||
items[].id | string | так | ||
items[].before | string | так | ||
items[].after | string | так | ||
items[].clip | object | null | ні | ||
items[].clip.videoId | string | так | ||
items[].clip.startSec | number | так | ||
items[].clip.endSec | number | так | ||
items[].clip.transcript | string | так |
Приклади виклику
{
"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.
Поля вмісту (content)
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
items | array<object> | так | ||
items[].id | string | так | ||
items[].text | string | так | ||
items[].options | array<object> | так | ||
items[].options[].key | string | так | ||
items[].options[].text | string | так | ||
items[].clip | object | null | ні | ||
items[].clip.videoId | string | так | ||
items[].clip.startSec | number | так | ||
items[].clip.endSec | number | так | ||
items[].clip.transcript | string | так |
Приклади виклику
{
"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.
Поля вмісту (content)
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
rule | array<string> | так | ||
table | object | null | ні | ||
table.columns | array<string> | так | ||
table.rows | array<array> | так | ||
examples | array<object> | так | ||
examples[].id | string | так | ||
examples[].text | string | так | ||
examples[].translation | string | так | ||
commonMistake | string | null | ні | ||
sourceNote | string | null | ні | ||
images | array<object> | ні | до 5 елементів | |
images[].assetId | string | так | ||
images[].path | string | так | ||
images[].width | number | так | ||
images[].height | number | так | ||
images[].alt | string | null | ні | ||
imageSlot | object | null | ні | ||
imageSlot.want | string | так | до 200 символів |
Приклади виклику
{
"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.
Поля вмісту (content)
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
direction | string | так | одне з: to_content, from_content | |
items | array<object> | так | ||
items[].id | string | так | ||
items[].source | string | так |
Приклади виклику
{
"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"
}
}
}miro_board — Дошка Miro
A Miro board shown in the lesson. boardId is the id from the board link (miro.com/app/board/<id>/) — or paste the full link and it is converted. Empty boardId makes an empty slot: hidden from students, flagged to the teacher. Asks for no answers; what students may do on the board is set by its sharing setting in Miro.
Поля вмісту (content)
| Поле | Тип | Обов’язкове | Обмеження | Опис |
|---|---|---|---|---|
boardId | string | так |
Приклади виклику
{
"boardId": "uXjVKabc123="
}Коди помилок
Кожен інструмент може повернути ці помилки; біля інструмента перелічені ті, що для нього типові.
| Код | Коли трапляється | Що робити агентові |
|---|---|---|
validation_failed | Вхідні дані порушують форму, правило або ліміт. | Виправити всі проблеми зі списку problems і повторити виклик один раз. |
scope_missing | У токена немає дозволу, потрібного цьому інструменту. | Сказати викладачу, який дозвіл додати, і створити новий токен. |
not_found | Ідентифікатор невідомий або належить іншому викладачу — ці випадки навмисно не розрізняються. | Перевірити ідентифікатор інструментом-списком. |
archived | Урок або курс в архіві. | Обрати інший або попросити викладача повернути з архіву. |
conflict | Зміна суперечить тому, що вже сталося: наприклад, спосіб проходження курсу, на який уже записано студентів. | Не повторювати. Сказати викладачу, чому зміна неможлива. |
limit_reached | Досягнуто ліміт продукту: кількість активних курсів або ліміт уроків чи студентів на плані викладача. У разі ліміту плану details має error: "teacher_plan_limit", kind (lessons або students), limit і plan. | Сказати викладачу про ліміт і не повторювати виклик: нічого не створено, наявне не змінено. Плани викладач бачить у Менторі на сторінці «Плани». |
not_entitled | Дія доступна не всім: публікація в каталозі поки для окремих акаунтів. | Сказати викладачу, що дія недоступна його акаунту. |
publish_incomplete | У курсу не вистачає даних, потрібних для публікації. | Заповнити поля зі списку problems і повторити. |
quota_exceeded | Спрацював ліміт ШІ: добовий або тижневий (details.limit). | Зачекати до моменту details.resetsAt (UTC). Кількості уроків немає. |
link_expired | Посилання для завантаження зображень застаріло або вже використане. | Створити нове через tutor_upload_images. |
fetch_refused | Адресу зображення не завантажено: не https, непублічна адреса, відповідь не є зображенням або забагато перенаправлень. | Дати публічну https-адресу зображення або обрати інший спосіб завантаження. |
rate_limited | Перевищено частоту викликів. | Зачекати retryAfterSeconds секунд. |
idempotency_conflict | Ключ idempotencyKey уже використано з іншим інструментом, або перший виклик із ним ще виконується. | Узяти новий ключ або повторити трохи згодом. |
generation_failed | Генерація уроку у веб-інтерфейсі завершилась помилкою. MCP-інструменти її не запускають. | Показати викладачу message. |
not_available | Інструмент існує, але вимкнений на цьому сервері: Ментор не генерує уроки: їх пише агент. | Скористатися інструментом, який названо в message. Не повторювати виклик. |
internal_error | Щось непередбачене. Подробиці записано в журнал, у message є номер для звернення. | Повторити один раз, потім повідомити. |
