Ментор від Читай

Довідник

Довідник формується з реєстру інструментів сервера, тож збігається з тим, що бачить агент у tools/list. Описи інструментів — англійською, бо їх читає агент; біля кожного є короткий опис українською.

Інструменти

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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
querystringнідо 100 символів
limitintegerнівід 1 до 50
cursorstringнідо 500 символів

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

List the most recent lessons

{}

Find lessons by title

{
  "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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
lessonIdstringтакUUID

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

Read a lesson

{
  "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 · not_found

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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
blockIdstringтакUUID

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

Read one block

{
  "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

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

Потрібний дозвіл: 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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
typestringтакодне з: callout, passage, vocabulary, table, open_prompt, writing, mcq, gap_fill, matching, video_watch, video_listening, video_comprehension, theory, translation, miro_board

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

Learn the gap_fill block

{
  "type": "gap_fill"
}

Learn the callout block

{
  "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_get_authoring_guide

Віддає настанови зі створення уроків: правила, шаблони, розміри, планування курсу.

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

Read how to write a good lesson: core rules, lesson templates with block order and sizes, course planning, block notes. Read it before tutor_create_lesson. section defaults to all; use core, grammar, vocabulary, source, course or blocks for one part.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
sectionstringніодне з: all, core, grammar, vocabulary, source, course, blocks

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

Read the whole guide

{}

Read the grammar template

{
  "section": "grammar"
}

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

{
  "version": "2026-10-28",
  "section": "core",
  "markdown": "## Core rules\n\n1. **Open with a can-do goal…** Why: …"
}

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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
includeArchivedbooleanні
limitintegerнівід 1 до 50
cursorstringнідо 500 символів

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

List the first page of courses

{}

Include archived courses, 10 per page

{
  "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, archived

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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
courseIdstringтакUUID
briefForobjectні
briefFor.positionintegerнівід 1

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

Read a course

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

Read a course with the brief for its next lesson

{
  "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.

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

Check a link from tutor_upload_images (mode link or drop). Returns status waiting, done or expired, and the assetIds uploaded so far.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
linkIdstringтакUUID

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

Poll an upload

{
  "linkId": "9b2d4c1e-6a3f-4e7b-8d05-1c2e3f4a5b6c"
}

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

{
  "status": "done",
  "assetIds": [
    "3f1c0a52-7d4e-4b8a-9c11-5e2f6a7b8c90"
  ]
}

tutor_read_source

Читає субтитри відео YouTube (із часом) або текст статті, щоб написати урок. Нічого не зберігає.

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

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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
urlstringтаквід 1 до 2000 символів
languagestringтаквід 2 до 20 символів

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

Read a video in English

{
  "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

Список зображень викладача, найновіші першими.

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

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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
limitintegerнівід 1 до 50
cursorstringнідо 500 символів

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

List recent images

{
  "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

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

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

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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
idempotencyKeystringніA unique string per intended lesson, 8–100 letters, digits, - or _. A retry with the same key returns the first result.
courseobjectніAdd the lesson to this course in the same all-or-nothing call. position is 1-based; the default is the end.
course.courseIdstringтакUUID
course.positionintegerнівід 1
lessonobjectтак
lesson.titlestringнідо 300 символів
lesson.descriptionstringнідо 1000 символівMarkdown subset: **bold** *italic* ~~strike~~, blank-line paragraphs. ≤500 visible chars.
lesson.subjectstringтакодне з: 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.levelstringніодне з: a1, a2, b1, b2, c1, c2, pochatkovyi, serednii, prosunutyi
lesson.outputLanguagestringтакдо 20 символівLanguage of the instructions, e.g. uk or en.
lesson.worksheetsarray<object>таквід 1 до 10 елементів
lesson.worksheets[].titlestringнідо 300 символів
lesson.worksheets[].purposestringніодне з: classwork, homework, self_study
lesson.worksheets[].templatestringніодне з: grammar, vocabulary, sourceThe guide template this sheet follows; Mentor then returns warnings where it departs from it.
lesson.worksheets[].blocksarray<object>таквід 1 до 20 елементів
lesson.worksheets[].blocks[].typestringтакодне з: callout, passage, vocabulary, table, open_prompt, writing, mcq, gap_fill, matching, video_watch, video_listening, video_comprehension, theory, translation, miro_board
lesson.worksheets[].blocks[].titlestringні
lesson.worksheets[].blocks[].descriptionstringніShown above the block. **bold** *italic* ~~strike~~, paragraphs. ≤1000 visible.
lesson.worksheets[].blocks[].instructionstringні
lesson.worksheets[].blocks[].contentobjectтакShape depends on the block type; see tutor_get_block_schema.
lesson.worksheets[].blocks[].answerKeyobject | nullніShape depends on the block type; see tutor_get_block_schema.

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

Create a one-worksheet lesson with eight blocks

{
  "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."
            }
          }
        ]
      }
    ]
  }
}

Create the same lesson as lesson 2 of a course

{
  "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

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

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

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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
lessonIdstringтакUUID
titlestringнівід 1 до 200 символів

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

Copy a lesson under a new title

{
  "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

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

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

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).

Параметри

ПолеТипОбов’язковеОбмеженняОпис
worksheetIdstringтакUUID
blockobjectтак
block.typestringтакодне з: callout, passage, vocabulary, table, open_prompt, writing, mcq, gap_fill, matching, video_watch, video_listening, video_comprehension, theory, translation, miro_board
block.titlestringні
block.descriptionstringніShown above the block. **bold** *italic* ~~strike~~, paragraphs. ≤1000 visible.
block.instructionstringні
block.contentobjectтакShape depends on the block type; see tutor_get_block_schema.
block.answerKeyobject | nullніShape depends on the block type; see tutor_get_block_schema.
positionintegerнівід 0

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

Append a callout to a worksheet

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

Insert a callout as the first block

{
  "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). 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).

Параметри

ПолеТипОбов’язковеОбмеженняОпис
blockIdstringтакUUID
titlestringні
instructionstringні
descriptionstringніShown above the block. **bold** *italic* ~~strike~~, paragraphs. ≤1000 visible.
contentobjectніShape depends on the block type; see tutor_get_block_schema.
answerKeyobject | nullніShape depends on the block type; see tutor_get_block_schema.

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

Rename a block

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

Replace the text of a callout

{
  "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

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

Потрібний дозвіл: 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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
blockIdstringтакUUID

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

Delete a block

{
  "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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
worksheetIdstringтакUUID
blockIdsarray<string>таквід 1 елементів

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

Put the second block first

{
  "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 або сторінкою, яку відкриває викладач.

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

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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
modestringтакодне з: url, file, link, drop
urlsarray<string>нівід 1 до 5 елементів
filesarray<object>нівід 1 до 5 елементів
files[].download_urlstringтакдо 4000 символів
files[].file_idstringтакдо 200 символів
files[].mime_typestringнідо 100 символів
files[].file_namestringнідо 300 символів
altarray<string>нідо 5 елементів
countintegerнівід 1 до 5

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

Add a public image by address

{
  "mode": "url",
  "urls": [
    "https://chitay.org.ua/assets/tests/images/example/1.png"
  ],
  "alt": [
    "Оголошення про оренду кімнати"
  ]
}

Get a one-time page for the teacher to add files

{
  "mode": "drop",
  "count": 3
}

Get a one-time upload URL for curl

{
  "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) у бібліотеці й у всіх блоках, де воно є.

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

Set the alt text of an image (null clears it). It also changes every block that shows the image.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
assetIdstringтакUUID
altstring | nullтакдо 300 символів

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

Describe an image

{
  "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 лише показує, де воно використовується.

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

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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
assetIdstringтакUUID
confirmbooleanні

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

See where an image is used

{
  "assetId": "3f1c0a52-7d4e-4b8a-9c11-5e2f6a7b8c90"
}

Delete an image after the teacher agreed

{
  "assetId": "3f1c0a52-7d4e-4b8a-9c11-5e2f6a7b8c90",
  "confirm": true
}

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

{
  "deleted": true,
  "strippedBlocks": 2
}

tutor_update_lesson

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

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

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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
lessonIdstringтакUUID
titlestringнівід 1 до 300 символів
descriptionstring | nullнідо 1000 символівMarkdown subset: **bold** *italic* ~~strike~~, blank-line paragraphs. ≤500 visible chars.
subjectstringніодне з: 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
levelstring | nullніодне з: a1, a2, b1, b2, c1, c2, pochatkovyi, serednii, prosunutyi,
outputLanguagestringніодне з: 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
worksheetTitlestringнівід 1 до 300 символів

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

Rename a lesson

{
  "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

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

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

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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
worksheetIdstringтакUUID
titlestringнівід 1 до 200 символів
purposestringніодне з: classwork, homework, self_study

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

Make a worksheet 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

Додає в наявний урок цілий аркуш із блоками одним викликом: або все, або нічого.

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

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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
idempotencyKeystringніA unique string per intended worksheet, 8–100 letters, digits, - or _. A retry with the same key returns the first result.
lessonIdstringтакUUID
worksheetobjectтак
worksheet.titlestringнідо 300 символів
worksheet.purposestringтакодне з: classwork, homework, self_study
worksheet.templatestringніодне з: grammar, vocabulary, sourceThe guide template this sheet follows; Mentor then returns warnings where it departs from it.
worksheet.blocksarray<object>таквід 1 до 20 елементів
worksheet.blocks[].typestringтакодне з: callout, passage, vocabulary, table, open_prompt, writing, mcq, gap_fill, matching, video_watch, video_listening, video_comprehension, theory, translation, miro_board
worksheet.blocks[].titlestringні
worksheet.blocks[].descriptionstringніShown above the block. **bold** *italic* ~~strike~~, paragraphs. ≤1000 visible.
worksheet.blocks[].instructionstringні
worksheet.blocks[].contentobjectтакShape depends on the block type; see tutor_get_block_schema.
worksheet.blocks[].answerKeyobject | nullніShape depends on the block type; see tutor_get_block_schema.
positionintegerнівід 0Index among the lesson’s worksheets; default is the end.

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

Add a homework worksheet with one note

{
  "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

Прибирає аркуш з уроку (архівує, не знищує); останній аркуш уроку прибрати не можна.

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

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).

Параметри

ПолеТипОбов’язковеОбмеженняОпис
worksheetIdstringтакUUID

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

Delete a worksheet

{
  "worksheetId": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}

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

{
  "worksheetId": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
  "deleted": true
}

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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
lessonIdstringтакUUID

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

Archive a lesson

{
  "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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
titlestringтаквід 1 до 200 символів
descriptionstringнідо 4000 символівMarkdown subset: **bold** *italic* ~~strike~~, blank-line paragraphs, - / 1. lists, > quote. ≤2000 visible chars.
subjectstringніодне з: 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
levelstringніодне з: a1, a2, b1, b2, c1, c2, pochatkovyi, serednii, prosunutyi
contentLanguagestringніодне з: 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, gagLanguage the course is written in.
pacingstringніодне з: teacher_paced, self_pacedteacher_paced (default) or self_paced (student opens each next lesson). Fixed once anyone enrols.
forWhomarray<string>нідо 8 елементівWho the course is for, one point per item (≤200 visible chars). Only **bold**, *italic* and ~~strike~~ kept. null or [] clears.
outcomesarray<string>нідо 8 елементівWhat a learner gets after the course. Rules as forWhom.

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

Create a course

{
  "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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
courseIdstringтакUUID
titlestringнівід 1 до 200 символів
descriptionstring | nullнідо 4000 символівMarkdown subset: **bold** *italic* ~~strike~~, blank-line paragraphs, - / 1. lists, > quote. ≤2000 visible chars.
subjectstring | 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,
levelstring | nullніодне з: a1, a2, b1, b2, c1, c2, pochatkovyi, serednii, prosunutyi,
contentLanguagestring | 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.
pacingstringніодне з: teacher_paced, self_pacedteacher_paced (default) or self_paced (student opens each next lesson). Fixed once anyone enrols.
forWhomarray<string> | nullнідо 8 елементівWho the course is for, one point per item (≤200 visible chars). Only **bold**, *italic* and ~~strike~~ kept. null or [] clears.
outcomesarray<string> | nullнідо 8 елементівWhat a learner gets after the course. Rules as forWhom.

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

Set a description and clear the level

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

Describe who the course is for

{
  "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

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

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

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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
courseIdstringтакUUID

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

Archive a course

{
  "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).

Потрібний дозвіл: 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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
courseIdstringтакUUID
lessonIdstringтакUUID
positionintegerнівід 1

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

Append a lesson

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

Insert a lesson as the first one

{
  "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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
courseIdstringтакUUID
stepIdstringтакUUID

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

Remove a lesson from a 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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
courseIdstringтакUUID
stepIdsarray<string>таквід 1 до 200 елементів

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

Swap two lessons

{
  "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.

Параметри

ПолеТипОбов’язковеОбмеженняОпис
courseIdstringтакUUID
actionstringтакодне з: publish, unpublish

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

Publish a finished course

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

Take a course off the storefront

{
  "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)

ІдентифікаторНазва
a1A1 — початковий
a2A2 — базовий
b1B1 — середній
b2B2 — вище середнього
c1C1 — просунутий
c2C2 — вільне володіння
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.

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

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

ПолеТипОбов’язковеОбмеженняОпис
tonestringтакодне з: warning, info, tip
labelstring | nullні
textstringтак

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

{
  "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: 20, passageMaxChars: 12000

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

ПолеТипОбов’язковеОбмеженняОпис
paragraphsarray<object>так
paragraphs[].idstringтак
paragraphs[].textstringтак
numberedbooleanні
truncatedbooleanні
imagesarray<object>нідо 5 елементів
images[].assetIdstringтак
images[].pathstringтак
images[].widthnumberтак
images[].heightnumberтак
images[].altstring | nullні
imageSlotobject | nullні
imageSlot.wantstringтакдо 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.

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

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

ПолеТипОбов’язковеОбмеженняОпис
itemsarray<object>так
items[].idstringтак
items[].expressionstringтак
items[].meaningstringтак
items[].ipastring | nullні
items[].sourceLinestring | nullні
items[].imageobject | nullні
items[].image.assetIdstringтак
items[].image.pathstringтак
items[].image.widthnumberтак
items[].image.heightnumberтак
items[].image.altstring | 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.

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

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

ПолеТипОбов’язковеОбмеженняОпис
columnsarray<object>так
columns[].keystringтак
columns[].labelstringтак
columns[].rolestringтакодне з: fixed, response
columns[].inputstring | nullніодне з: text, textarea, checkbox,
rowsarray<object>так
rows[].idstringтак
rows[].cellsarray<object>так
rows[].cells[].columnstringтак
rows[].cells[].valuestringтак

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

{
  "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: 20, itemsField: prompts, suggestedItemsMax: 20

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

ПолеТипОбов’язковеОбмеженняОпис
response_modestringтакодне з: per_prompt, shared
linesnumberтак
promptsarray<object>так
prompts[].idstringтак
prompts[].textstringтак
shared_labelstring | nullні
imagesarray<object>нідо 5 елементів
images[].assetIdstringтак
images[].pathstringтак
images[].widthnumberтак
images[].heightnumberтак
images[].altstring | nullні
imageSlotobject | nullні
imageSlot.wantstringтакдо 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.

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

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

ПолеТипОбов’язковеОбмеженняОпис
promptsarray<object>так
prompts[].idstringтак
prompts[].textstringтак
choosenumberтак
word_targetobject | nullні
word_target.minnumberтак
word_target.maxnumberтак
constraintsarray<object>так
constraints[].kindstringтакодне з: use_expressions
constraints[].countnumberтак
planning_labelstring | nullні
final_labelstring | nullні
imagesarray<object>нідо 5 елементів
images[].assetIdstringтак
images[].pathstringтак
images[].widthnumberтак
images[].heightnumberтак
images[].altstring | nullні
imageSlotobject | nullні
imageSlot.wantstringтакдо 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.

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

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

ПолеТипОбов’язковеОбмеженняОпис
questionsarray<object>так
questions[].idstringтак
questions[].textstringтак
questions[].optionsarray<object>так
questions[].options[].keystringтак
questions[].options[].textstringтак
questions[].imageobject | nullні
questions[].image.assetIdstringтак
questions[].image.pathstringтак
questions[].image.widthnumberтак
questions[].image.heightnumberтак
questions[].image.altstring | 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).

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

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

ПолеТипОбов’язковеОбмеженняОпис
itemsarray<object>так
items[].idstringтак
items[].beforestringтак
items[].afterstringтак
imagesarray<object>нідо 5 елементів
images[].assetIdstringтак
images[].pathstringтак
images[].widthnumberтак
images[].heightnumberтак
images[].altstring | nullні
imageSlotobject | nullні
imageSlot.wantstringтакдо 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.

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

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

ПолеТипОбов’язковеОбмеженняОпис
leftarray<object>так
left[].idstringтак
left[].textstringтак
left[].imageobject | nullні
left[].image.assetIdstringтак
left[].image.pathstringтак
left[].image.widthnumberтак
left[].image.heightnumberтак
left[].image.altstring | nullні
rightarray<object>так
right[].keystringтак
right[].textstringтак

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

{
  "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.

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

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

ПолеТипОбов’язковеОбмеженняОпис
videoIdstringтак
titlestringтак
channelstringтак
durationSecnumberтак
thumbnailUrlstringтак
watchForarray<string>ні
startSecnumberні
endSecnumberні

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

{
  "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.

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

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

ПолеТипОбов’язковеОбмеженняОпис
itemsarray<object>так
items[].idstringтак
items[].beforestringтак
items[].afterstringтак
items[].clipobject | nullні
items[].clip.videoIdstringтак
items[].clip.startSecnumberтак
items[].clip.endSecnumberтак
items[].clip.transcriptstringтак

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

{
  "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: 20, itemsField: items, suggestedItemsMax: 20

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

ПолеТипОбов’язковеОбмеженняОпис
itemsarray<object>так
items[].idstringтак
items[].textstringтак
items[].optionsarray<object>так
items[].options[].keystringтак
items[].options[].textstringтак
items[].clipobject | nullні
items[].clip.videoIdstringтак
items[].clip.startSecnumberтак
items[].clip.endSecnumberтак
items[].clip.transcriptstringтак

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

{
  "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: 20

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

ПолеТипОбов’язковеОбмеженняОпис
rulearray<string>так
tableobject | nullні
table.columnsarray<string>так
table.rowsarray<array>так
examplesarray<object>так
examples[].idstringтак
examples[].textstringтак
examples[].translationstringтак
commonMistakestring | nullні
sourceNotestring | nullні
imagesarray<object>нідо 5 елементів
images[].assetIdstringтак
images[].pathstringтак
images[].widthnumberтак
images[].heightnumberтак
images[].altstring | nullні
imageSlotobject | nullні
imageSlot.wantstringтакдо 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.

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

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

ПолеТипОбов’язковеОбмеженняОпис
directionstringтакодне з: to_content, from_content
itemsarray<object>так
items[].idstringтак
items[].sourcestringтак

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

{
  "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.

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

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

ПолеТипОбов’язковеОбмеженняОпис
boardIdstringтак

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

{
  "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 є номер для звернення.Повторити один раз, потім повідомити.