# POST /api/v1/tutor/messages

Отправить вопрос тьютору и получить конечный JSON, не SSE.

| Поле | Значение |
| --- | --- |
| URL | `POST https://aos.edgelab.space/api/v1/tutor/messages` |
| Доступ | Cookie кабинета · Mini App (TMA) |
| Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) |
| operationId | `tutorSend` |

## Описание

Отправить вопрос тьютору и получить конечный **JSON, не SSE**. `requestId` – клиентский UUID идемпотентности: повтор не создаёт второй расход. Текст до 4000 символов; текст после trim или хотя бы одно вложение обязательны. До 4 собственных ready uploads, уникальных без учёта регистра, ещё не прикреплённых, моложе 55 минут. В grace-режиме участия отправка запрещена (503); при отключённом тьюторе – `TUTOR_UNAVAILABLE`.

**Auth:** сессия кабинета (cookie) / TMA bearer. **Scope:** не требуется.

**Path:** параметров нет.

**Query:** нет объявленных полей.

**Body:** `application/json`, [TutorSendRequest](/docs/schemas#tutorsendrequest). Все вложенные поля и варианты – по ссылке.

| Поле          | Тип          | Обязательно | Ограничения                             |
| ------------- | ------------ | ----------- | --------------------------------------- |
| `requestId`   | `string`     | да          | формат "uuid"; pattern см. полную схему |
| `text`        | `string`     | да          | длина ≤ 4000                            |
| `attachments` | `(string)[]` | нет         | элементов ≤ 4                           |

**Ответ · статус и структура**

**Ответ:** 200 `application/json`, [TutorSendResponse](/docs/schemas#tutorsendresponse).

Краткая форма: `{ userMessage: TutorMessage, reply: TutorMessage, messagesLeftToday: integer }`.

Пример JSON; значения демонстрационные.

```json
{
  "userMessage": {
    "id": "5f0e1c2a-8b3d-4e6f-9a7b-1c2d3e4f5a61",
    "role": "user",
    "text": "Как подключить MCP к Claude Code?",
    "sources": [],
    "citations": [],
    "error": false,
    "feedback": null,
    "attachments": [
      {
        "id": "7a1c2e3f-4b5d-4e6f-8a9b-0c1d2e3f4a51",
        "name": "скрин ошибки.png",
        "mime": "image/png",
        "kind": "image",
        "size": 184320
      }
    ],
    "createdAt": "2026-11-06T09:00:00.000Z"
  },
  "reply": {
    "id": "5f0e1c2a-8b3d-4e6f-9a7b-1c2d3e4f5a62",
    "role": "assistant",
    "text": "Подключите сервер командой `claude mcp add` и проверьте его через `/mcp` [1]. Перед запуском пройдите чек-лист [2]. Зачем агенту MCP, коротко описано в каталоге скиллов [3][1].",
    "sources": [
      {
        "kind": "lesson",
        "label": "Урок 1.1 · 05:10",
        "lesson": "1.1",
        "seconds": 310
      },
      {
        "kind": "material",
        "label": "Материал · Чек-лист подключения MCP",
        "id": "mcp"
      },
      {
        "kind": "skill",
        "label": "Скилл · MCP",
        "id": "mcp"
      }
    ],
    "citations": [
      {
        "source": 0,
        "start": 73,
        "end": 76
      },
      {
        "source": 1,
        "start": 111,
        "end": 114
      },
      {
        "source": 2,
        "start": 169,
        "end": 172
      },
      {
        "source": 0,
        "start": 172,
        "end": 175
      }
    ],
    "error": false,
    "feedback": null,
    "attachments": [],
    "createdAt": "2026-11-06T09:00:04.000Z"
  },
  "messagesLeftToday": 49
}
```

**Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `409 BUSY`, `429 DAILY_LIMIT`, `429 GLOBAL_BUDGET`, `503 TUTOR_UNAVAILABLE`, `404 NOT_FOUND`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors).

**Лимиты:** 1 запуск одновременно на студента; сообщения и USD/день МСК из тарифа (`Me.limits`). Общая оценка изображений сообщения ≤10 000 tokens.

**Запрос · JSON**

```json
{
  "requestId": "00000000-0000-4000-8000-000000000001",
  "text": "Объясни материал урока 1.1"
}
```

**Пример · curl**

```bash
curl -sS -i -X POST https://aos.edgelab.space/api/v1/tutor/messages \
  --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' \
  -H 'Origin: https://aos.edgelab.space' \
  -H 'Content-Type: application/json' \
  -d '{"requestId":"00000000-0000-4000-8000-000000000001","text":"Объясни материал урока 1.1"}'
```

## Ответы по контракту

Тело запроса: [TutorSendRequest](/docs/schemas#tutorsendrequest).

| Статус | Тип | Схема | Описание |
| --- | --- | --- | --- |
| 200 | application/json | [TutorSendResponse](/docs/schemas#tutorsendresponse) | Успех |
| ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, VALIDATION_FAILED, BUSY, DAILY_LIMIT, GLOBAL_BUDGET, TUTOR_UNAVAILABLE, NOT_FOUND |

Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `tutorSend`.
