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:

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":"привет"}]}'

Пауза на вопросе/одобрении не подвешивает клиента: текст вопроса приходит в ответе с finish_reason: "stop". Решения по одобрениям — через нативный API.

11. Ошибки

{
  "error": {
    "code": "invalid_mode",
    "message": "Не поняла режим «творить». Доступны: ask, agent, plan, coder …",
    "doc": "https://api.assol.space/doc#modes"
  }
}

message — что именно не так и как исправить, doc — раздел этой документации.

HTTPcodeКогда
401unauthorizedнет токена API или он отозван
401wrong_token_scopeприслан токен Ollama вместо токена API
400bad_jsonтело — не JSON-объект
404session_not_foundчата нет или нет доступа
404approval_not_foundзапроса на подтверждение нет или он закрыт
409stand_busyна папке уже открыт чат человека; API-сессии стенд не занимают
422invalid_mode, invalid_model, invalid_decision, message_required, message_too_longкривое поле запроса
503no_local_modelдля auto нет ни одной локальной модели/спутника в сети
504run_timeoutпрогон дольше лимита ожидания — продолжи через /result
500internal_error, run_errorвнутренняя ошибка; текст — в message

12. Ограничения

Здоровье сервиса: GET /health → {"ok": true, …}.