# Справочник HTTP API

> Все HTTP-адреса Eggent — какие из них открыты по токену для интеграций, какие требуют входа в веб-версию, и что они принимают и возвращают.

Source: https://eggent.ai/r/docs/http-api/

У Eggent два вида HTTP-адресов:

- **Внешний API** (`/api/external/*`) — для интеграций. Авторизация токеном `Authorization: Bearer <токен>`. Подробно — в [«HTTP API для интеграций»](https://eggent.ai/r/docs/external-api.md).
- **API веб-версии** — всё остальное. Требует входа: cookie сессии, которую ставит `/api/auth/login`. Этими адресами пользуется сам интерфейс; для автоматизации лучше внешний API.

Базовый адрес: `https://имя.cloud.eggent.ai` в облаке или адрес твоего сервера.

## Внешний API {#external}

| Метод и адрес | Что делает |
| --- | --- |
| `POST /api/external/message` | Отправить сообщение, получить ответ (JSON или поток SSE) |
| `POST /api/external/media-message` | То же с файлом, `multipart/form-data` |
| `POST /api/external/telegram/sent` | Для Telegram-бота, который сам отправляет ответы: `{"telegramChatId","messageIds","chatId"}` — какими сообщениями ушёл ответ из какого чата, чтобы ответ на них продолжил этот чат |
| `GET /api/external/token`, `POST /api/external/token` | Посмотреть или выпустить токен (нужен вход) |

## Служебное {#service}

| Метод и адрес | Что делает |
| --- | --- |
| `GET /api/health` | Проверка: `{"status":"ok","timestamp":"…","version":"0.2.9"}`. Без авторизации |
| `POST /api/auth/login` | Вход: `{"username":"…","password":"…"}` → cookie сессии |

## Проекты {#projects}

| Метод и адрес | Что делает |
| --- | --- |
| `GET /api/projects` | Список проектов |
| `POST /api/projects` | Создать: `{"name","description","instructions"}` |
| `GET`, `PUT`, `DELETE /api/projects/:id` | Прочитать, изменить, удалить проект |
| `GET`, `PUT /api/projects/:id/context` | Контекст проекта (`context.md`) |
| `GET`, `PUT /api/projects/:id/memory` | Память проекта (`memory.md`) |
| `GET`, `PUT /api/projects/:id/model` | Модель проекта (`model.json`) |
| `GET`, `DELETE /api/projects/:id/skills` | Навыки проекта. `DELETE` принимает `{"name"}` и удаляет этот навык вместе с прежними версиями, оставшимися после замены |
| `POST /api/projects/:id/skills/upload` | Загрузить один навык файлом (multipart-форма: `file`, и `replace=1`, чтобы заменить установленный) |
| `GET`, `PUT /api/projects/:id/mcp` | MCP-серверы проекта (`.mcp.json`) |

Для контекста, памяти, навыков и MCP вместо `:id` можно подставить `none` — тогда запрос относится к оркестратору. Своей модели у оркестратора нет: он отвечает моделью воркспейса.

## Что агент выучил {#learning}

| Метод и адрес | Что делает |
| --- | --- |
| `GET /api/learning` | Заметки, навыки, которые написал агент, и включено ли обучение |
| `POST /api/learning` | `{"enabled":true\|false}`, либо добавить или убрать одну заметку: `{"action":"add","target":"user\|notes","content":"…"}`, `{"action":"remove","target":"user\|notes","text":"…"}` |

## Чаты {#chats}

| Метод и адрес | Что делает |
| --- | --- |
| `POST /api/chat` | Отправить сообщение из интерфейса (поток) |
| `GET /api/chat/history` | Список чатов или история одного чата |
| `GET /api/chat/:id/stream` | Подключиться к ответу, который ещё пишется |
| `POST /api/chat/:id/stop` | Остановить работу в чате |
| `GET`, `POST`, `DELETE /api/chat/files` | Вложения чата |

## Файлы проекта {#files}

| Метод и адрес | Что делает |
| --- | --- |
| `GET /api/files` | Содержимое папки |
| `GET /api/files/content` | Текст файла |
| `GET /api/files/download` | Скачать файл. С `inline=1` — открыть в браузере в изолированном режиме |
| `GET /api/files/zip` | Папка (`path=`) или несколько файлов (повтори `path=`) одним `.zip`; `check=1` отвечает, что в него войдёт. Выше пределов — отказ 413 |
| `GET /api/files/stat` | Какие из перечисленных путей ещё существуют |
| `GET`, `POST /api/files/telegram` | Достижим ли Telegram; отправить один файл в твой чат |
| `POST /api/files/upload` | Загрузить файлы и папки, `multipart/form-data` |
| `DELETE /api/files` | Удалить файл или папку |
| `GET`, `DELETE /api/files/versions` | [История файла](https://eggent.ai/r/docs/files.md#history) (`project`, `path`) или её удаление |
| `GET /api/files/versions/content` | Текст версии `n` |
| `GET /api/files/versions/download` | Версия `n` файлом |
| `POST /api/files/versions/restore` | `{ project, path, n, force? }` — восстановить версию `n` новой версией |
| `GET`, `POST /api/files/versions/usage` | Сколько занимает история; `{ "action": "clear", "olderThanDays" }` очищает её |
| `GET /api/files/page-link` | Где показывается [страница](https://eggent.ai/r/docs/files.md#pages) (`project`, `path`, `mode=edit\|print`), на время |
| `GET /api/files/page-element` | Выбранный на странице блок: название, строки, исходник (`sha`, `el`) |
| `POST /api/files/page-edit` | `{ project, path, sha, edits }` — слова, изменённые на странице, записываются туда, откуда пришли |
| `GET /api/files/page-print` | Файл, подготовленный к [сохранению в PDF](https://eggent.ai/r/docs/files.md#pdf) |

Параметры загрузки: `project`, `path`, `files` (можно несколько), `relativePaths` (куда положить каждый файл, по порядку), `directories` (пустые папки), `conflict` — `skip` (по умолчанию), `overwrite` или `rename`. Один запрос — не больше 100 МБ, иначе ответ `413`.

```bash
curl -X POST https://имя.cloud.eggent.ai/api/files/upload \
  -b cookies.txt \
  -F "project=my-project" \
  -F "path=." \
  -F "conflict=rename" \
  -F "files=@./notes.md"
```

## Доска задач {#board}

Изменения требуют сессии с того же сайта и тела в JSON, как у маршрутов терминала.

| Метод и адрес | Что делает |
| --- | --- |
| `GET /api/board` | Все карточки, стоит ли доска, какие карточки сейчас в работе; `?archived=1` — вместе с убранными |
| `GET /api/board/summary` | Сколько карточек ждут тебя, работают и стоят в очереди |
| `POST /api/board/cards` | Новая карточка: `title`, `body`, `projectId`, `after`, `review`, `start` |
| `GET`, `PATCH`, `DELETE /api/board/cards/:id` | Одна карточка; `PATCH` правит её или перемещает: `{ "move": { "to": "inbox" \| "queued" \| "done" \| "archived" \| "unarchived", "position" } }` |
| `POST /api/board/cards/:id/answer` | `{ "text" }` — ответ на вопрос карточки |
| `POST /api/board/cards/:id/stop` | Остановить; карточка из очереди возвращается во «Входящие» |
| `POST /api/board/start-all` | Все карточки «Входящих» (проекта `projectId`, если указан) — в очередь |
| `POST /api/board/resume` | Дать доске продолжить после отказа сервиса моделей |

## Компания {#company}

Только в воркспейсе, который входит в [компанию](https://eggent.ai/r/docs/company.md). Записи требуют сессии с того же сайта и JSON в теле.

| Метод и адрес | Что делает |
| --- | --- |
| `GET /api/mail/contacts` | Люди компании и непрочитанное |
| `GET /api/mail/thread` | Переписка с человеком (`with`, `before`, `limit`) |
| `POST /api/mail/send` | `{ to, text, files?, replyTo? }` |
| `POST /api/mail/read` | `{ with, upTo }` — отметить прочитанным |
| `POST /api/mail/assign` | `{ messageId }` — открыть чат с агентом о сообщении |
| `GET /api/mail/attachments/:id` | Файл из переписки |
| `GET /api/shares` | Файлы, открытые тебе, и файлы, которые открыл ты |
| `GET /api/shares/people` | Кому можно открыть файл |
| `GET /api/shares/file` | Твой файл и кому он открыт (`project`, `path`) |
| `POST /api/shares/share` | `{ project, path, people: [{ id, role }] }` — переданный список и есть все, кому открыт файл |
| `GET /api/shares/:id`, `GET /api/shares/:id/text` | Общий файл: кому открыт и что в нём |
| `GET`, `POST /api/shares/:id/content` | Файл; `{ baseSha, text }` меняет его текст поверх этой версии |
| `POST /api/shares/:id/page-edit` | `{ sha, edits }` — слова, изменённые на общей странице |
| `GET`, `POST /api/shares/:id/comments` | Комментарии; `{ body, quote?, anchor?, replyTo? }` |
| `POST /api/shares/:id/comments/:comment/resolve`, `/delete` | Отметить решённым (`{ resolved }`) или удалить комментарий |
| `POST /api/shares/:id/stop` | Закрыть доступ |
| `GET /api/approvals` | Согласования: `box=waiting\|sent\|involved` |
| `GET /api/approvals/file` | Твой файл и его согласование (`project`, `path`) |
| `POST /api/approvals/send` | `{ project, path, approvers, note? }` — версия, которая в файле сейчас |
| `GET /api/approvals/:id` | Одно согласование с кругами |
| `POST /api/approvals/:id/decide` | `{ round, decision: "approve" \| "reject", comment? }` |
| `POST /api/approvals/:id/cancel` | Снять с согласования |
| `GET /api/approvals/:id/rounds/:round/file`, `/text` | Версия круга — файлом или текстом |

## Расписания {#schedules}

| Метод и адрес | Что делает |
| --- | --- |
| `GET /api/pi-schedules` | Все задачи по расписанию во всех проектах и у оркестратора, с отметкой, на паузе ли задача и почему |
| `POST /api/pi-schedules` | Изменить одну задачу: `{"action": "pause" \| "resume" \| "retime" \| "delete", "jobId": "…"}` (для `retime` ещё `schedule`) |