# POST /api/v1/files

Загрузить вложение raw bytes, не multipart: тип сверяется с сигнатурой/UTF-8.

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

## Описание

Загрузить вложение raw bytes, не multipart: тип сверяется с сигнатурой/UTF-8. До 10 MiB на файл; публичный домен ограничивает тело 4 MB ещё до API. Изображения до 3.75 MiB, сторона ≤4096 px, ≤7 450 000 пикселей; PDF до 20 страниц; извлечённый текст до 20 000 символов (длинный обрезается с `textTruncated=true`). Параллельные загрузки разрешены; сохранённый id передаётся в `TutorSendRequest.attachments`.

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

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

**Query:**

| Поле   | Тип      | Обязательно | Ограничения            |
| ------ | -------- | ----------- | ---------------------- |
| `name` | `string` | нет         | длина ≥ 1; длина ≤ 200 |

**Body:** обязательные raw bytes; `Content-Type`: `image/png`, `image/jpeg`, `image/webp`, `application/pdf`, `text/plain`, `text/markdown`.

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

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

Краткая форма: `{ id: string, name: string, mime: "image/png" | "image/jpeg" | "image/webp" | "application/pdf" | "text/plain" | "text/markdown", kind: "image" | "pdf" | "text", size: integer, width: integer | null, height: integer | null, pages: integer | null, textTruncated: boolean, createdAt: string }`.

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

```json
{
  "id": "7a1c2e3f-4b5d-4e6f-8a9b-0c1d2e3f4a51",
  "name": "скрин ошибки.png",
  "mime": "image/png",
  "kind": "image",
  "size": 184320,
  "width": 1179,
  "height": 2556,
  "pages": null,
  "textTruncated": false,
  "createdAt": "2026-11-06T08:59:30.000Z"
}
```

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

**Лимиты:** параллельные загрузки разрешены. Для PDF – до 2 резерваций на студента суммарно в обработке и ожидании. 20 попыток/день МСК, сброс в 00:00 МСК; отказы после резервирования дневной попытки тоже считаются, кроме отказа из-за занятости сервера: такая попытка возвращается в квоту. Превышение собственных 2 PDF-резерваций попытку расходует. Оба вида занятости дают `429 RATE_LIMITED`, сообщение «Сервер занят, попробуйте через минуту», `retryAfterSec: 60`; исчерпанная дневная квота – `429 DAILY_LIMIT`. Лимит хранения – 200 MiB: все неприкреплённые и прикреплённые за последние 30 суток.

```bash
curl -sS -i -X POST 'https://aos.edgelab.space/api/v1/files?name=example.txt' \
  --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' \
  -H 'Origin: https://aos.edgelab.space' \
  -H 'Content-Type: text/plain' \
  --data-binary @example.txt
```

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

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

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