> For the complete documentation index, see [llms.txt](https://docs.skillzrun.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.skillzrun.com/administruvannya/robota-z-api/dovidnik-metodiv-zovnishnogo-api.md).

# Довідник методів зовнішнього API

Нижче — усі публічні методи зовнішнього API, згруповані за ресурсами. Це стислий довідник із ключовими параметрами; повні схеми запитів і відповідей завжди актуальні у [Swagger](https://api.skillzrun.com/external/api/swagger/static/index.html#/).

Якщо метод не позначено окремо, авторизація — заголовок `x-api-key` з ключем вашої школи (див. «Робота з API» — як його створити).

### Спільні параметри списків

Методи `GET`, що повертають список (users, homeworks, user\_reviews, subject\_structures), приймають однакові query-параметри:

| Параметр        | Опис                                                                                                                                |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `start`, `end`  | пагінація — індекс першого і останнього запису (стандартно 20 записів на сторінку)                                                  |
| `sort`, `order` | поле й напрямок сортування                                                                                                          |
| `filter`        | JSON-рядок з фільтром: `filter.q` — пошук, `filter.extraIds` — додати конкретні документи, `filter.exceptIds` — виключити документи |
| `ids`           | JSON-масив ID, щоб отримати декілька записів одразу                                                                                 |

### Користувачі (`users`)

| Метод    | Ендпоінт                                  | Опис                                                                 |
| -------- | ----------------------------------------- | -------------------------------------------------------------------- |
| `GET`    | `/external/api/users/`                    | Список користувачів                                                  |
| `GET`    | `/external/api/users/raw-items`           | "Сирі" записи користувачів (без обробки)                             |
| `GET`    | `/external/api/users/{id}`                | Один користувач за ID                                                |
| `GET`    | `/external/api/users/{id}/progress`       | Прогрес користувача                                                  |
| `POST`   | `/external/api/users/`                    | Створити користувача                                                 |
| `POST`   | `/external/api/users/upsert`              | Створити користувача або оновити наявного за email                   |
| `POST`   | `/external/api/users/create-with-orders`  | Створити користувача одразу із замовленнями (offerIds)               |
| `POST`   | `/external/api/users/bulk-provide-offers` | Масово надати оффери (`offerIds`) списку користувачів (`userIds`)    |
| `PUT`    | `/external/api/users/{id}`                | Оновити одного користувача                                           |
| `PUT`    | `/external/api/users/bulk-update`         | Масово оновити список користувачів (`userIds` + поля, що змінюються) |
| `DELETE` | `/external/api/users/{id}`                | Видалити користувача                                                 |

Ключові поля тіла запиту для створення/оновлення користувача:

* `name`, `email`, `phone` — основні дані (для `POST /users/` обов'язкові `name` і `email`);
* `isActive`, `isDemoMode` — активність акаунту й демо-режим;
* `seesAllSubjects`, `ignoreNotOpenLevels`, `ignoreStopItems` — розширені права перегляду;
* `subjects[]` — масив доступів до предметів, у кожному: `subjectId`, `groups[]`, `levelPacks[]`, `access.openMode` (`immediately`/`exactlyAt`), `access.closeMode` (`never`/`afterSeveralDays`/`exactlyAt`), `access.startDate`, `access.endDate`, `access.dayCount`, `userEventsLimit`;
* `newPassword` — новий пароль (мінімум 6 символів), доступно при оновленні;
* `noteAboutUser[]` — нотатки про користувача (`text`, `createdAt`, `employeeId`, `userVisible`).

### Баланс монет (`user_balance`)

| Метод   | Ендпоінт                      | Опис                                                                                                        |
| ------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `PATCH` | `/external/api/user_balance/` | Масове нарахування/списання монет — див. розділ «Масове оновлення балансу монет» на сторінці «Робота з API» |

### Домашні завдання (`homework`)

| Метод  | Ендпоінт                                       | Опис                                                                                  |
| ------ | ---------------------------------------------- | ------------------------------------------------------------------------------------- |
| `GET`  | `/external/api/homeworks/`                     | Список домашніх завдань, з додатковими фільтрами по статусу й даті перевірки вчителем |
| `POST` | `/external/api/ai-media-feedback/{homeworkId}` | Прикріпити аудіо-фідбек до домашнього завдання (`multipart/form-data`, поле `file`)   |
| `POST` | `/external/api/ai-text-feedback/{homeworkId}`  | Додати текстовий коментар і/або статус перевірки (`text`, `isApproved`)               |

`filter` для списку домашніх завдань додатково підтримує: `filter.updatedAtByTeacherStart/End` (дата перевірки вчителем, формат `yyyy-mm-dd`), `filter.statusHistory.status` і `filter.statusHistory.updatedAtStart/End`.

{% hint style="info" %}
Методи `ai-media-feedback` і `ai-text-feedback` авторизуються заголовком `authorization`, а не `x-api-key`.
{% endhint %}

### Події (`events`)

| Метод  | Ендпоінт                                 | Опис                                          |
| ------ | ---------------------------------------- | --------------------------------------------- |
| `POST` | `/external/api/events/for-many-subjects` | Створити подію одразу для декількох предметів |

Обов'язкові поля тіла запиту: `subjectIds[]`, `name`, `date`, `finishDate`, `description`, `persons`, `assignTo` (`groups`/`users`), `registerAllUsers`, `groups[]`, `users[]`, `online`, `meetingUrl`, `notifications[]`, `leader` (`employee`, `guest`), `tags[]`, `ignoreUserLimits`, `creationWithoutNotice`, `status`. Для платної події — об'єкт `paid` (`price`, `googleProductId`, `appleProductId`).

### Відгуки користувачів (`user_reviews`)

| Метод | Ендпоінт                      | Опис                                                     |
| ----- | ----------------------------- | -------------------------------------------------------- |
| `GET` | `/external/api/user_reviews/` | Список відгуків користувачів (спільні параметри списків) |

### Структура предметів (`subject_structures`)

| Метод | Ендпоінт                            | Опис                                                                         |
| ----- | ----------------------------------- | ---------------------------------------------------------------------------- |
| `GET` | `/external/api/subject_structures/` | Список структур предметів (рівні → теми → уроки) — спільні параметри списків |

### Уроки (`decks`)

| Метод | Ендпоінт                                | Опис                                                             |
| ----- | --------------------------------------- | ---------------------------------------------------------------- |
| `PUT` | `/external/api/decks/{id}/updateTheory` | Оновити теорію уроку — тіло запиту: `html` (HTML-контент теорії) |

### Генерація вправ (`exercises_generate`)

| Метод  | Ендпоінт                                             | Опис                                                               |
| ------ | ---------------------------------------------------- | ------------------------------------------------------------------ |
| `POST` | `/external/api/exercises_generate/`                  | Згенерувати вправи для уроків за допомогою ШІ                      |
| `POST` | `/external/api/exercises_generate/justRefreshTheory` | Примусово вивантажити теорію уроків в AI API (без генерації вправ) |

Поля запиту генерації: `lessons[]` (ID уроків), `count` (1–10 вправ на урок), `type` — тип вправи (`5` — вибрати слова, `7` — домашнє завдання, `8` — знайти пари, `9` — заповнити пропуски, `11` — тест із вибором відповіді), `language` (мова генерації), `additionalInstructions` (необов'язкові інструкції для ШІ), `forceRefreshTheory` (примусово оновити теорію перед генерацією). Для типу `9` обов'язковий об'єкт `type9Adjustments.answerType` (`keyboard`/`select`). Заголовок `locale` (необов'язково) визначає мову можливих повідомлень про помилки.

### Місії (`missions`)

| Метод  | Ендпоінт                       | Опис                                      |
| ------ | ------------------------------ | ----------------------------------------- |
| `POST` | `/external/api/copy_missions/` | Скопіювати місії з одного предмета в інші |

Поля запиту: `sourceSubjectId` — предмет-джерело, `targetSubjectsId[]` — предмети-цілі, `targetCompanyId` і `targetCompanyApiKey` — щоб скопіювати місії в іншу компанію (за замовчуванням копіювання відбувається в межах поточної школи).

### Слова та терміни (`words`)

| Метод  | Ендпоінт                          | Опис                                                                                           |
| ------ | --------------------------------- | ---------------------------------------------------------------------------------------------- |
| `POST` | `/external/api/images_for_words/` | Завантажити PPTX із зображеннями та ідентифікаторами слів (`multipart/form-data`, поле `file`) |