# Memdeck API для агента

Эта инструкция публичная. Авторизация нужна только для CRUD колод и карточек.

Публичные URL:
- https://memdecks.studentto.ru/agent.md
- https://memdecks.studentto.ru/llms.txt
- https://memdecks.studentto.ru/api/docs
- https://memdecks.studentto.ru/docs

База: https://memdecks.studentto.ru
Авторизация: заголовок `Authorization: Bearer <токен>`.
Токен выпускает пользователь в аккаунте: https://memdecks.studentto.ru/account
Формат токена: `mdk_...`
Все тела запросов: `Content-Type: application/json`
Ошибки: `{ "error": "текст" }` со статусом 400 / 401 / 404 / 500
Колоды и карточки всегда принадлежат владельцу токена. Чужие id не видны.

## Как добавить колоду

1. `POST /api/decks` с `name` (обязательно) и `description` (необязательно).
2. Из ответа взять `id`.
3. Для каждой карточки: `POST /api/decks/{id}/cards` с `front` и `back`.

Не пытайся создать карточки без колоды. Сначала колода, потом карточки.

## Поля

### Колода (вход)

| Поле | Тип | Обязательно | Лимит |
| --- | --- | --- | --- |
| name | string | да при создании | 1–80 символов после trim |
| description | string | нет | до 280 символов |

### Карточка (вход)

| Поле | Тип | Обязательно | Лимит |
| --- | --- | --- | --- |
| front | string | да при создании | 1–32000 символов, Markdown + LaTeX |
| back | string | да при создании | 1–32000 символов, Markdown + LaTeX |

LaTeX: `$...$` в строке, `$$...$$` блоком.

### Колода (ответ)

`id`, `userId`, `name`, `description`, `createdAt`, `updatedAt`, `cardCount`
В `GET /api/decks/:id` вместо `cardCount` приходит массив `cards`.

### Карточка (ответ)

`id`, `deckId`, `front`, `back`, `createdAt`, `updatedAt`

Даты — ISO-8601.

## Методы

### GET /api/decks
Список колод пользователя, новые сверху.
Тело: нет.
Ответ: массив колод с `cardCount`.

### POST /api/decks
Создать колоду.
Тело: `{ "name": "Немецкий A1", "description": "Глаголы" }`
`description` можно не слать.
Ответ 201: созданная колода, `cardCount: 0`.

### GET /api/decks/:id
Одна колода и все её карточки.
Ответ: колода + `cards` (по дате создания).

### PATCH /api/decks/:id
Частично изменить колоду.
Тело: `{ "name"?: string, "description"?: string }`
Непереданные поля не трогаются.

### DELETE /api/decks/:id
Удалить колоду и все её карточки.
Ответ: `{ "ok": true }`

### GET /api/decks/:id/cards
Только карточки колоды.
Ответ: массив карточек.

### POST /api/decks/:id/cards
Добавить карточку в колоду.
Тело: `{ "front": "Good morning", "back": "Доброе утро" }`
Оба поля обязательны.
Ответ 201: созданная карточка.

### PATCH /api/cards/:id
Частично изменить карточку.
Тело: `{ "front"?: string, "back"?: string }`

### DELETE /api/cards/:id
Удалить карточку.
Ответ: `{ "ok": true }`

## Примеры

Создать колоду:

```bash
curl -X POST https://memdecks.studentto.ru/api/decks \
  -H "Authorization: Bearer mdk_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Немецкий A1","description":"Глаголы"}'
```

Добавить карточку:

```bash
curl -X POST https://memdecks.studentto.ru/api/decks/<DECK_ID>/cards \
  -H "Authorization: Bearer mdk_..." \
  -H "Content-Type: application/json" \
  -d '{"front":"Good morning","back":"Доброе утро"}'
```

Карточка с Markdown и формулой:

```bash
curl -X POST https://memdecks.studentto.ru/api/decks/<DECK_ID>/cards \
  -H "Authorization: Bearer mdk_..." \
  -H "Content-Type: application/json" \
  -d '{"front":"## Площадь круга\n\nФормула для радиуса $r$","back":"$S = \\pi r^2$"}'
```

Список колод:

```bash
curl https://memdecks.studentto.ru/api/decks \
  -H "Authorization: Bearer mdk_..."
```