API Ассоль
Чаты с Ассоль по HTTP: сессии, режимы, стрим, OpenAI-совместимый слой.
Базовые адреса: https://api.assol.space и https://api.assol.online (одно и то же).
1. Токен
Каждый запрос (кроме /health, /doc и /) требует персональный токен в заголовке:
Authorization: Bearer aso_…
Токен привязан к тебе: сессии, модели и ключи — твои. Чужой токен видит только свои данные.
2. Где взять токен
В Ассоль: Настройки → Токены API. Создай токен с именем устройства — секрет показывается один раз, скопируй его сразу.
Токены Ollama (ollama.assol.space) живут отдельным списком и к этому API не подходят.
3. Режимы
Поле mode — поведение Ассоль в этом сообщении. Доступны все режимы сессии:
| mode | Что делает |
|---|---|
ask | Только ответ текстом: без правок файлов и команд. |
agent | Полный набор инструментов: чтение, правки, bash, git. Опасные действия спрашивают подтверждение. |
plan | Сначала план, потом его исполнение. |
coder | Задача сразу уходит Aider в рабочей папке; агент не читает код сам. |
Режим можно задать при создании сессии и переопределять каждым сообщением.
4. Модели
Поле model:
- конкретная модель из
GET /v1/models— любая подключённая: локальная (хаб, процессорные копии), модель спутника или облачная (если в Ассоль задан ключ провайдера); autoили поле не передано — отвечает свободная локальная модель или модель спутника. Облако в режимеautoне выбирается никогда.
curl -s https://api.assol.space/v1/models \
-H "Authorization: Bearer aso_…"
В списке у каждой модели есть available (жива ли она сейчас; для моделей хаба — состояние Ollama). Нет ни одной локальной модели в сети — ответ 503 no_local_model: включи Ollama на ПК Ассоль или спутник либо передай конкретную модель.
5. Сессии
Создать
curl -s -X POST https://api.assol.space/v1/sessions \
-H "Authorization: Bearer aso_…" -H "Content-Type: application/json" \
-d '{"mode":"agent","model":"auto","title":"мой скрипт"}'
Ответ: {"session": {"id": 42, "mode": "agent", "model": "…", …}}. Чат создаётся в рабочей папке по умолчанию; workspace_id — если нужна другая папка.
API-сессии — автоматические: они не занимают стенд (папку), поэтому работают рядом с открытым чатом в UI. Если папку держит открытый чат человека, а действие без этого невозможно, ответ 409 stand_busy — закрой или архивируй чат.
Список, состояние, стоп
GET /v1/sessions | все чаты; ?archived=1 — архив |
GET /v1/sessions/{id} | чат, переписка, статус прогона, ожидания человека |
POST /v1/sessions/{id}/stop | остановить прогон |
6. Сообщения
curl -s -X POST https://api.assol.space/v1/sessions/42/messages \
-H "Authorization: Bearer aso_…" -H "Content-Type: application/json" \
-d '{"text":"привет","mode":"ask","model":"auto"}'
Без stream сервер ждёт ответ и возвращает JSON:
{
"session_id": 42,
"status": "done",
"answer": "Привет! …",
"message_id": 1234,
"pending_ask": null,
"approvals": []
}
status — фаза прогона: done, error, stopped, waiting_input (Ассоль задала вопрос), waiting_approval (нужно подтверждение инструмента), running (только в run_timeout).
Если прогон идёт дольше лимита ожидания, ответ 504 run_timeout — продолжай ждать через GET /v1/sessions/{id}/result.
7. Стрим на том же адресе
Отдельный адрес/хост для стрима не нужен: тот же эндпоинт с "stream": true, но ответ приходит как text/event-stream (SSE) — сервер пишет кадры по мере генерации и закрывает поток после event: done.
curl -N -X POST https://api.assol.space/v1/sessions/42/messages \
-H "Authorization: Bearer aso_…" -H "Content-Type: application/json" \
-d '{"text":"привет","stream":true}'
event: session
data: {"session_id": 42}
event: status
data: {"status": "running"}
event: delta
data: {"text": "Привет"}
event: done
data: {"session_id": 42, "status": "done", "answer": "Привет! …"}
События: session, status, delta, ask (вопрос Ассоль), approval (карточка подтверждения), done, error. Каждые 15 секунд приходит комментарий-пульс : ping.
Как читать в браузере. EventSource не умеет POST и заголовки, поэтому стрим читают через fetch:
const res = await fetch('https://api.assol.space/v1/sessions/42/messages', {
method: 'POST',
headers: { 'Authorization': 'Bearer aso_…', 'Content-Type': 'application/json' },
body: JSON.stringify({ text: 'привет', stream: true }),
})
const reader = res.body.getReader()
const decoder = new TextDecoder()
while (true) {
const { value, done } = await reader.read()
if (done) break
console.log(decoder.decode(value)) // кадры event: … / data: …
}
На домене API прокси не буферизует поток (nginx: proxy_buffering off, таймауты 3600 с) — кадры приходят по мере генерации, а не в конце. Поток держится до 10 минут: дольше — event: error с run_timeout, дальше жди /result (лимит — ASSOL_API_WAIT_S).
8. Ожидание результата
GET /v1/sessions/{id}/result?timeout_s=600 — ждёт итог текущего прогона и возвращает те же поля, что ответ на сообщение. Удобно после run_timeout или после решения по одобрению.
9. Одобрения
В режимах agent/coder опасный инструмент останавливает прогон и ждёт решения.
curl -s https://api.assol.space/v1/sessions/42/approvals \
-H "Authorization: Bearer aso_…"
curl -s -X POST https://api.assol.space/v1/approvals/<id> \
-H "Authorization: Bearer aso_…" -H "Content-Type: application/json" \
-d '{"decision":"allow"}'
Решения: allow (один раз), deny, always (запомнить «разрешить всегда»), never.
10. OpenAI-совместимый слой
Base URL: https://api.assol.space/v1/openai. Работает с клиентами, которые умеют OpenAI Chat Completions:
curl -s -X POST https://api.assol.space/v1/openai/chat/completions \
-H "Authorization: Bearer aso_…" -H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"привет"}]}'
model— подключённая модель;auto/незнакомое имя — свободная локальная модели или спутник;- дополнительные поля:
mode(по умолчаниюask),session_id(работать в существующем чате),assol_keep(оставить временный чат в списке); - без
session_idкаждый запрос создаёт временный чат и прячет его после ответа; история изmessagesпереигрывается,systemприклеивается к запросу; stream: true— обычные OpenAI-кадрыdata: {…}иdata: [DONE].
Пауза на вопросе/одобрении не подвешивает клиента: текст вопроса приходит в ответе с finish_reason: "stop". Решения по одобрениям — через нативный API.
11. Ошибки
{
"error": {
"code": "invalid_mode",
"message": "Не поняла режим «творить». Доступны: ask, agent, plan, coder …",
"doc": "https://api.assol.space/doc#modes"
}
}
message — что именно не так и как исправить, doc — раздел этой документации.
| HTTP | code | Когда |
|---|---|---|
| 401 | unauthorized | нет токена API или он отозван |
| 401 | wrong_token_scope | прислан токен Ollama вместо токена API |
| 400 | bad_json | тело — не JSON-объект |
| 404 | session_not_found | чата нет или нет доступа |
| 404 | approval_not_found | запроса на подтверждение нет или он закрыт |
| 409 | stand_busy | на папке уже открыт чат человека; API-сессии стенд не занимают |
| 422 | invalid_mode, invalid_model, invalid_decision, message_required, message_too_long | кривое поле запроса |
| 503 | no_local_model | для auto нет ни одной локальной модели/спутника в сети |
| 504 | run_timeout | прогон дольше лимита ожидания — продолжи через /result |
| 500 | internal_error, run_error | внутренняя ошибка; текст — в message |
12. Ограничения
- Текст сообщения — до 32 000 символов; тело запроса — до 8 МБ.
- Вложений в API v1 нет: только текст.
- Один прогон на сессию: сообщение во время прогона встаёт в очередь, ответ придёт по завершении текущего.
- Режимы
agent/coderмогут остановиться на подтверждении — это не ошибка, аwaiting_approval. - API-сессии не занимают стенд: «одна сессия на папку» ограничивает только чаты людей в UI.
- Отдельного лимита запросов нет; злоупотребление блокируется отзывом токена в настройках.
Здоровье сервиса: GET /health → {"ok": true, …}.