# API

Источник: https://svedum.ru/docs/developers/api

> Запускайте облачных агентов сотрудника из своего кода — ключ из кабинета, задача, ход работы и файлы результата.

API даёт вашим скриптам и сервисам то же, что облачный агент сотрудника в приложении:
поручить задачу, дописать уточнение, следить за ходом, остановить и забрать файлы. Агент
работает в облаке сотрудника, с его навыками и подключениями, и расходует лимит тарифа как
обычная работа. В приложении он виден у сотрудника — во вкладке «Обзор», в разделе
«Агенты».

## Ключ

### 1. Создайте ключ

В [личном кабинете](https://svedum.ru/docs/account/cabinet) откройте «API-ключи», впишите имя ключа — например,
«CI» — и нажмите «Создать ключ».

### 2. Сохраните его

Ключ показывается один раз: скопируйте его и нажмите «Я сохранил ключ». Ключ начинается с
`rzm_`. Храните его как пароль — в менеджере секретов, а не в git.

### 3. Проверьте

Ключ передают в заголовке `Authorization`:

```bash
curl https://svedum.ru/api/v1/me -H "Authorization: Bearer $RAZUM_API_KEY"
```

Ключ даёт доступ к сотрудникам вашего аккаунта; войти в кабинет по нему нельзя. Ключ,
который больше не нужен или мог утечь, отзовите — «Отозвать» в списке ключей: запросы с
ним сразу перестают проходить.

## Поручить задачу

Агента запускают у конкретного сотрудника. ID сотрудника — в ссылке на него: «В браузере» в
его [профиле](https://svedum.ru/docs/employees/create#профиль-сотрудника) копирует адрес вида
`https://svedum.ru/workbench/employees/<id>`.

```bash
curl https://svedum.ru/api/v1/agents \
  -H "Authorization: Bearer $RAZUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "<id сотрудника>",
    "prompt": { "text": "Сравни цены пяти конкурентов и сведи в таблицу" },
    "client_request_id": "price-check-2026-10-15"
  }'
```

В ответе — `id` агента, `run_id` его первого хода и `status`. Поля запроса:

* **`employee_id`** и **`prompt.text`** — обязательны.
* **`repo`** и **`base_ref`** — репозиторий GitHub и ветка, если задача про код. →
  [Облачные агенты](https://svedum.ru/docs/agents/cloud)
* **`client_request_id`** — ключ повтора: запрос с тем же значением второго агента не
  запустит. Ставьте его, если ваш код повторяет запросы при сбоях сети.
* **`model`** — модель агента: `ref` из `GET /models`. Без поля агент работает на модели
  сотрудника, с моделью не из списка запрос вернёт ошибку `400`.

## Следить и управлять

| Запрос                                                     | Что делает                                                  |
| ---------------------------------------------------------- | ----------------------------------------------------------- |
| `GET /agents/{id}`                                         | Агент и его `status`                                        |
| `GET /agents/{id}/runs/{run_id}/stream`                    | События хода потоком (`text/event-stream`)                  |
| `POST /agents/{id}/runs`                                   | Новый ход: `{"text": "…"}` — уточнение или следующая задача |
| `GET /agents/{id}/runs` и `GET /agents/{id}/runs/{run_id}` | Ходы агента                                                 |
| `POST /agents/{id}/runs/{run_id}/cancel`                   | Остановить ход                                              |
| `GET /agents/{id}/artifacts`                               | Файлы, которые сделал агент                                 |
| `GET /agents/{id}/artifacts/download?path=…`               | Скачать файл                                                |
| `GET /agents/{id}/usage`                                   | Расход агента                                               |
| `GET /agents?employee_id=…`                                | Агенты сотрудника, до 100 за запрос; дальше — по `cursor`   |
| `POST /agents/{id}/archive`, `/unarchive`                  | Убрать агента в архив и вернуть                             |
| `DELETE /agents/{id}`                                      | Удалить агента                                              |
| `GET /models`                                              | Модели, доступные аккаунту                                  |

Все пути — от `https://svedum.ru/api/v1`. `status` агента:

* **`queued`** — ждёт места в лимите одновременных задач в облаке;
* **`working`** — работает;
* **`waiting_user`** — ждёт ответа на вопрос или разрешение: откройте агента в приложении;
* **`finished`** — ход закончен.

Если поток оборвался, подключитесь заново с заголовком `Last-Event-ID` — события придут с
того места, где остановились.

Новые поля в ответах могут появляться: читайте те, что нужны, и не отклоняйте ответ с
незнакомыми.