Справочник API

Эндпоинты агентов

Все эндпоинты /v1/agents для облачных агентов: создание агентов для ваших пользователей, настройки, запуск и остановка, выполнение задач через API, файлы и ссылки для доступа, открытие веб-страницы, токены агентов и брендинги для агентов под вашим брендом.

API облачных агентов находится по адресу https://lovelyrouter.com/v1/agents. Аутентифицируйтесь API-ключом из консоли в виде Authorization: Bearer $LOVELY_API_KEY (Аутентификация) или, для одного агента, токеном агента. Ключи, которые сессия агента получает для себя, не могут вызывать эти эндпоинты. Тела запросов и ответов — JSON; суммы указываются в микродолларах (1 000 000 = $1). Агенты оплачиваются с вашего предоплаченного баланса; см. Цены на облачных агентов.

Пошаговое введение — в обзоре облачных агентов.

Объект агента#

Атрибуты

idstring

Уникальный id: agt_ и 24 символа.

objectstring

Всегда agent.

namestring | null

Ваша метка.

userstring | null

Ваш собственный id пользователя, которого обслуживает агент (1–128 символов: буквы, цифры, _ . @ : + -). По нему можно фильтровать список.

metadataobject | null

Ваш JSON-объект, до 4 КБ.

statusstring

stopped, starting или running.

sessionobject | null

Открытая сессия: id, status, size, vcpu, mem_gib, started_at, ready_at и её стоимость на текущий момент: charge_micros (время песочницы), llm_micros (модели и инструменты) и total_micros.

urlstring

Веб-страница агента, https://agent.lovelyrouter.com/a/<id>/. Вход — через Open или токен ui.

sizeidle_minutes

См. настройки.

settingsobject

model, tools, mcp_servers (значения заголовков показываются как ••••••••), instructions.

budget_microsinteger | null

Когда spend.total_micros достигает этого значения, агент останавливается и больше не стартует и не выполняет запуски.

brandingstring | null

Брендинг его страницы (brd_…) или null для стандартного вида.

white_labelboolean

true, если у агента есть брендинг: его песочница оплачивается по тарифам white label. Открытая session сообщает то же о себе.

spendobject

compute_micros (время песочницы), llm_micros (модели и инструменты, использованные его сессиями), total_micros.

workspaceobject

Объём хранимых данных bytes, measured_at.

created_atinteger

Миллисекунды с начала эпохи.

Создание агента#

POST/v1/agents

Создаёт агента с собственным пустым рабочим пространством и возвращает 201 с объектом агента. Принимает все настройки, а также "start": true, чтобы сразу его запустить. До 1 000 агентов на учётную запись.

Shell

curl https://lovelyrouter.com/v1/agents \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name": "Support bot", "user": "cust-42", "metadata": {"plan": "pro"}, "budget_micros": 5000000}'

Список агентов#

GET/v1/agents

Сначала новые. ?user=cust-42 возвращает агентов этого пользователя; limit (≤ 200, по умолчанию 50); before (значение created_at) листает назад, а next_before в ответе — значение для следующей страницы.

cURL

curl "https://lovelyrouter.com/v1/agents?user=cust-42" -H "Authorization: Bearer $LOVELY_API_KEY"

Получение, изменение и удаление агента#

PATCH/v1/agents/{id}

GET возвращает агента; PATCH (или POST) меняет переданные поля; DELETE останавливает агента, если он работает, и безвозвратно удаляет его вместе с рабочим пространством. Настройки применяются со следующего старта.

Параметры тела запроса

nameuser

Как в объекте агента; null очищает значение.

modelstring | null

LLM по умолчанию — любой id чат-модели из GET /v1/models. null = claude-haiku-5.5.

toolsbooleanПо умолчанию true

Инструменты данных и браузерный агент Lovely Router как MCP-инструменты (mcp__tools__*), оплата за использование.

mcp_serversarray

До 8 удалённых MCP-серверов (streamable HTTP): {"name", "url", "headers"}. name — 1–32 символа из a-z 0-9 _ -, начинается с буквы (tools занято), url — публичный URL https://, headers — до 10. Значения заголовков хранятся в зашифрованном виде и никогда не возвращаются; если отправить обратно ••••••••, сохранённое значение останется.

instructionsstring | null

Добавляется в каждую сессию, до 4 000 символов.

sizestring

small, medium или large (размеры).

idle_minutesinteger

5, 15, 30, 60, 120, 240, 480 или 1440.

max_hoursinteger

1, 2, 4, 8, 12 или 24.

auto_startbooleanПо умолчанию true

Просыпаться при вызове: остановленный агент стартует сам для запуска, открытия или посещения его страницы. Применяется сразу.

brandingstring | null

Один из ваших брендингов: со следующего старта агент становится агентом под вашим брендом и оплачивается по тарифам white label. null = стандартный вид и тарифы.

cURL

curl -X PATCH https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-5.5", "instructions": "Reply in the user'"'"'s language."}'

Запуск и остановка#

POST/v1/agents/{id}/start

Запускает агента; через несколько секунд он переходит в running (первый старт нового агента может занять больше времени). POST /v1/agents/{id}/stop останавливает его и возвращает сессию с итоговым charge_micros. Для старта нужен баланс, покрывающий 15 минут работы его размера (не меньше $0.25); одновременно на учётной записи работают до 20 агентов. Запуски задач стартуют остановленного агента сами.

cURL

curl -X POST https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/start -H "Authorization: Bearer $LOVELY_API_KEY"

Выполнение задачи#

POST/v1/agents/{id}/runs

API агента: отправляет агенту одну задачу и возвращает запуск. Агент работает в своей песочнице со своими инструментами и настройками точно так же, как на своей веб-странице; сессия каждого запуска сохраняется и тоже видна там. Остановленный агент сначала стартует, если у него включён auto_start (по умолчанию), и останавливается примерно через 5 секунд после окончания последнего запуска, независимо от того, разбудил ли его запуск или он уже работал, — если только в этой сессии не использовалась его страница (тогда он останавливается при простое). Чтобы агент продолжал работать между запусками, передайте stop_when_done: false. Работает с API-ключом или токеном агента со scope api.

Параметры тела запроса

inputstringОбязательно

Задача, до 100 000 символов.

session_idstring

Продолжить эту сессию (из session_id предыдущего запуска). Если не указан — новая сессия.

waitinteger

Удерживать запрос до этого числа секунд (≤ 300), пока запуск не завершится.

streamboolean

Вместо этого возвращать события запуска как server-sent events: run, session, status (ходы и шаги с расходом токенов), tool_call, tool_result, text, final, затем end с завершённым запуском.

stop_when_doneboolean

Остановить агента примерно через 5 секунд после завершения его запусков. По умолчанию true, если в этой сессии не использовалась страница агента. false оставляет агента работать (тогда он останавливается при простое); true останавливает его после этого запуска, даже если страница использовалась раньше, если только кто-то не воспользуется ею тем временем.

startboolean

Запустить агента, если он остановлен. С токеном агента решает только auto_start: true не может запустить агента, у которого он выключен.

Запуск перечисляет файлы, переданные в нём агентом, в поле files: path (относительно домашней папки агента), description, bytes и url, по которому файл скачивается через Files. Файл, сохранённый вне домашней папки, не сохраняется и имеет url: null. Чтобы показать файл тому, у кого нет API-ключа, создайте ссылку для доступа.

GET /v1/agents/{id}/runs перечисляет запуски с момента последнего старта агента, GET /v1/agents/{id}/runs/{run_id}?wait=30 возвращает один запуск, GET …/events передаёт его потоком, POST …/cancel останавливает его. Запуски хранятся, пока агент работает; их сессии остаются в рабочем пространстве. Одновременно на агенте работают до 4 запусков, по одному на сессию.

Shell

curl https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/runs \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"input": "Summarize README.md in three bullets.", "wait": 120}'

Response

{
  "id": "run_k3f9a1c7mf0x2",
  "object": "agent_run",
  "agent_id": "agt_3f9a1c7e0b2d4e6f8a9b0c1d",
  "status": "completed",
  "session_id": "session-631cba7f-3095-4f66-b2cb-6786ff1f951c",
  "input": "Summarize README.md in three bullets.",
  "output": "- …",
  "error": null,
  "usage": { "input_tokens": 1240, "output_tokens": 96, "cache_read_tokens": 15703, "cache_write_tokens": 0 },
  "steps": 2,
  "tool_calls": 1,
  "files": [
    {
      "path": "deepseek-harness/api-requests/summary.md",
      "description": "README summary",
      "bytes": 412,
      "in_home": true,
      "url": "https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/files/deepseek-harness/api-requests/summary.md"
    }
  ],
  "started_at": 1792363795275,
  "finished_at": 1792363805502
}

Файлы#

GET/v1/agents/{id}/files/{path}

Показывает содержимое папки или скачивает файл из домашней папки агента. path указывается относительно неё; не указывайте его, чтобы получить саму домашнюю папку. API-запуски работают в deepseek-harness/api-requests (их сессии сгруппированы как API Requests на веб-странице агента); сессии, начатые на веб-странице, работают в deepseek-harness/default-workspace, если вы не откроете другую папку. Пока агент работает, файлы читаются в реальном времени ("live": true); пока он остановлен, они в состоянии на момент последней остановки, и чтение не запускает агента. Работает с API-ключом или токеном агента со scope api.

Для папки возвращается {"object": "list", "path", "live", "data", "truncated"}: до 1 000 записей, сначала папки, у каждой name, path, type (file или dir), bytes, modified_at и url. Для файла возвращаются его байты как вложение с его типом содержимого.

cURL

curl https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/files/deepseek-harness/default-workspace \
  -H "Authorization: Bearer $LOVELY_API_KEY"

curl -O https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/files/deepseek-harness/api-requests/summary.md \
  -H "Authorization: Bearer $LOVELY_API_KEY"

Ссылки для доступа#

POST/v1/agents/{id}/shares

Создаёт ссылку, которая открывает файл или папку как сайт для любого, у кого она есть, без входа в систему. Ссылка продолжает работать, пока агент остановлен. Ссылка на папку открывает её index.html (или список файлов, если его нет), а страница загружает остальные файлы папки по относительным путям. Ссылка на файл заканчивается его именем. Возвращает 201 с {"object": "agent_share", "agent_id", "path", "type", "url", "expires_at"}.

Параметры тела запроса

pathstringОбязательно

Файл или папка в домашней папке агента, как в Files.

expires_inintegerПо умолчанию 604800

Сколько секунд работает ссылка: от 60 до 31 536 000 (год). По умолчанию неделя.

POST /v1/agents/{id}/shares/revoke сразу отключает все ссылки агента. Ссылка также перестаёт действовать, когда её агент удалён или когда отозван API-ключ либо токен агента, которым она создана: токен агента со scope api тоже может создавать ссылки, и они истекают вместе с токеном. Отключать ссылки может только учётная запись.

Общие страницы работают в песочнице: скрипты, формы и ресурсы с других сайтов работают, cookie и хранилище браузера — нет, и страница не может обращаться к Lovely Router или другим агентам.

cURL

curl https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/shares \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"path": "deepseek-harness/default-workspace/site", "expires_in": 86400}'

Response

{
  "object": "agent_share",
  "agent_id": "agt_3f9a1c7e0b2d4e6f8a9b0c1d",
  "path": "deepseek-harness/default-workspace/site",
  "type": "dir",
  "url": "https://agent.lovelyrouter.com/s/eyJrIjoic2hyIiwi…/",
  "expires_at": 1792450195275
}

Открытие веб-страницы#

POST/v1/agents/{id}/open

Возвращает url — ссылку, действующую 60 секунд, которая открывает веб-страницу работающего агента с выполненным входом. Вход действует 7 дней или до отзыва ключа. Остановленный агент с включённым auto_start сначала запускается (его страница показывает Starting…, пока он не будет готов); иначе — 409.

Токены агентов для ваших пользователей#

POST/v1/agents/{id}/tokens

Создаёт токен для одного агента, чтобы выдать его вашему пользователю, — так он никогда не увидит ваш API-ключ. scopes: api позволяет токену использовать запуски и файлы этого агента, создавать ссылки для доступа и читать его статус; ui создаёт url — ссылку, открывающую веб-страницу агента (её можно использовать повторно, пока токен не истёк). Давайте только api пользователям, которым не нужно видеть веб-страницу. expires_in: от 60 секунд до 30 дней (по умолчанию 3 600). Токен перестаёт работать, когда истекает, когда вы отзываете токены агента, когда удаляете агента или когда отзываете API-ключ, которым он создан.

POST /v1/agents/{id}/tokens/revoke отзывает все токены агента, выданные к этому моменту (уже открытые ссылки перестают работать в течение минуты).

cURL

curl https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/tokens \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"scopes": ["api"], "expires_in": 3600}'

Response

{
  "object": "agent_token",
  "agent_id": "agt_3f9a1c7e0b2d4e6f8a9b0c1d",
  "scopes": ["api"],
  "token": "agtok_eyJrIjoiYWd0Iiwi…",
  "expires_at": 1792367395275,
  "url": null
}

Сессии#

GET/v1/agents/{id}/sessions

Последние 50 сессий песочницы агента, включая открытую, со стоимостью каждой: charge_micros (время песочницы), llm_micros (модели и инструменты, использованные её ключом) и total_micros. stop_reason сессии — user, idle, done (разбудивший её запуск завершился), balance, budget, max_time, exited, error, deleted или admin.

Брендинги#

POST/v1/agents/brandings

Сохранённые оформления для агентов под вашим брендом. POST создаёт брендинг (201); GET /v1/agents/brandings перечисляет ваши (сначала новые, до 50); GET, PATCH (или POST) и DELETE /v1/agents/brandings/{id} читают, изменяют и удаляют один брендинг. PATCH меняет переданные поля; агенты, использующие брендинг, подхватывают изменение при следующем старте. Удаление брендинга, который используют агенты, возвращает 409. Токены агентов не могут вызывать эти эндпоинты.

Параметры тела запроса

agent_namestringОбязательно

Имя, которое пользователи видят на странице и которым агент называет себя: 1–40 букв, цифр, пробелов и . _ -, начинается с буквы или цифры.

namestring

Ваша метка, до 60 символов. По умолчанию — agent_name.

logostring | null

Изображение PNG, JPEG, WebP или SVG в виде base64 data: URI, до 64 КБ. null = монограмма: первая буква agent_name на акцентном цвете.

schemestringПо умолчанию dark

dark или light.

colorsobject

Значения #rrggbb: accent, bg (фон) и при желании accentSoft (ссылки), onAccent (текст на акцентном цвете), surface, surface2, surface3 (панели, приподнятые области, рамки), ink, ink2, ink3 (текст, второстепенный, приглушённый). Не указанные цвета выводятся из scheme, accent и bg. PATCH, меняющий только scheme, выводит новую палитру из акцентного цвета.

fontstring | null

Шрифт текста: Inter, Geist, Roboto, Open Sans, Lato, Poppins, Montserrat, Nunito, DM Sans, Manrope, Plus Jakarta Sans, Space Grotesk, Work Sans, IBM Plex Sans, Source Sans 3, Noto Sans, Outfit, Figtree, Rubik или Lora. null = собственный шрифт страницы.

mono_fontstring | null

Шрифт кода: JetBrains Mono, Geist Mono, IBM Plex Mono, Fira Code, Source Code Pro, Roboto Mono, DM Mono или Space Mono.

welcomestring | null

Заголовок над первым полем сообщения, до 80 символов. null = What can I do for you?

Объект брендинга содержит эти поля со всеми заполненными цветами, а также id (brd_ и 24 символа), object (agent_branding), agents (сколько агентов его используют; в списках и при чтении), created_at и updated_at.

cURL

curl https://lovelyrouter.com/v1/agents/brandings \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"agent_name": "Nova Assistant", "scheme": "light", "colors": {"accent": "#0d9488"}, "font": "Inter", "welcome": "How can Nova help today?"}'

Response

{
  "id": "brd_6c1f0a9e3b7d2c4e8f5a1b0d",
  "object": "agent_branding",
  "name": "Nova Assistant",
  "agent_name": "Nova Assistant",
  "logo": null,
  "scheme": "light",
  "colors": {
    "accent": "#0d9488", "accentSoft": "#0b7f75", "onAccent": "#ffffff",
    "bg": "#f7f8fa", "surface": "#ffffff", "surface2": "#f0f1f3", "surface3": "#e6e8ea",
    "ink": "#14161b", "ink2": "#5d5e62", "ink3": "#86878b"
  },
  "font": "Inter",
  "mono_font": null,
  "welcome": "How can Nova help today?",
  "agents": 0,
  "created_at": 1792367395275,
  "updated_at": 1792367395275
}

Собственный домен#

PUT/v1/agents/brandings/{id}/domain

Подключает ваш собственный домен к брендингу (как это работает); 201 с объектом домена. GET читает его (добавьте ?check=1, чтобы запросить актуальный статус прямо сейчас), DELETE отключает. Один домен на брендинг. Для подключения нужен баланс не меньше цены одного дня; домен стоит $0.50 в день, пока подключён, начиная с дня подключения, без возврата за уже начавшийся день. Объект брендинга содержит тот же объект в поле domain (или null).

Параметры тела запроса

hostnamestringОбязательно

Домен, которым вы владеете, например agents.yourcompany.com (можно вставить URL целиком).

Объект домена

hostnamestring

В нижнем регистре.

statusstring

pending (ожидается ваша DNS-запись или сертификат), active (обслуживает ваших агентов) или error (см. errors).

recordsarray

DNS-записи, которые нужно добавить: {"type", "name", "value", "purpose"}. purpose route — это CNAME, направляющий домен на нас (обязательно); ownership и certificate — TXT-записи, позволяющие выпустить сертификат до того, как домен будет указывать на нас (необязательно).

cname_targetstring

Куда указывает CNAME.

errorsarray

Чего ещё не хватает, пока статус pending.

price_day_microsinteger

Цена за день.

created_atactive_at

Миллисекунды с начала эпохи.

cURL

curl -X PUT https://lovelyrouter.com/v1/agents/brandings/brd_6c1f0a9e3b7d2c4e8f5a1b0d/domain \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"hostname": "agents.yourcompany.com"}'

Ошибки#

Ошибки имеют ту же форму, что и в остальном API: {"error": {"type", "message"}}.

Статус	Тип	Когда
400	`invalid_request_error`	Недопустимое значение поля (в сообщении указано, какого)
401	`authentication_error`	Ключ или токен отсутствует, недействителен, отозван или истёк
402	`insufficient_quota`	Баланс не покрывает 15 минут работы выбранного размера или бюджет агента исчерпан
403	`permission_error`	Токен без нужного scope, токен, использованный не для запусков и файлов своего агента, или собственный ключ агента
404	`not_found`	Нет такого агента, запуска, файла или папки
409	`conflict`	Агент уже работает (start), остановлен с выключенным `auto_start` (open, запуск) или запуск с `"start": false`, в этой сессии уже выполняется запуск, или удаление брендинга, который используют агенты
429	`rate_limit_exceeded`	Уже работают 20 агентов или на этом агенте уже выполняются 4 запуска
502	`api_error`	Песочница не смогла стартовать; плата не взимается. Повторите попытку
503	`service_unavailable`	Облачные агенты сейчас недоступны или агент ещё запускается