surfaces/docs/api-contract.md

API Contract — Lambda Platform

Статус: ЧЕРНОВИК — проектируем сами, уточняем с Азаматом когда SDK будет готов Последнее обновление: 2026-03-29

---

Архитектурный контекст

Каждому пользователю выделяется один LXC-контейнер с workspace 10 ГБ. Workspace содержит директории чатов: C1/, C2/, C3/ — файлы + history.db в каждом.

Master управляет lifecycle контейнера (запуск, заморозка, пробуждение). Бот не управляет lifecycle — он передаёт user_id + chat_id + сообщение. Master сам решает: нужно ли поднять контейнер, смонтировать нужный чат, запустить агента.

---

Base URL

https://api.lambda-platform.io/v1

Аутентификация

Authorization: Bearer {SERVICE_TOKEN}

Сервисный токен выдаётся команде поверхностей. Не путать с токеном пользователя.

---

Users

GET /users/{external_id}?platform={platform}

Получает или создаёт пользователя.

Query params:

• platform — telegram | matrix

Response 200:

{
  "user_id": "usr_abc123",
  "external_id": "12345678",
  "platform": "telegram",
  "display_name": "Иван Иванов",
  "created_at": "2025-01-15T10:30:00Z",
  "is_new": false
}

---

Messages

Бот не управляет сессиями явно. Отправка сообщения — единственная операция. Master решает: нужен ли новый контейнер, или разбудить существующий.

POST /users/{user_id}/chats/{chat_id}/messages

Отправляет сообщение пользователя агенту. Master поднимает/размораживает контейнер, монтирует нужный чат (C1/, C2/...), запускает агента.

Request:

{
  "text": "Привет, что ты умеешь?",
  "attachments": []
}

Response 200:

{
  "message_id": "msg_qwe012",
  "response": "Я AI-агент Lambda...",
  "tokens_used": 142,
  "finished": true
}

---

Settings

GET /users/{user_id}/settings

Настройки пользователя: скиллы, коннекторы, SOUL, безопасность, план.

Response 200:

{
  "skills": {"web-search": true, "browser": false},
  "connectors": {"gmail": {"connected": true, "email": "user@gmail.com"}},
  "soul": {"name": "Лямбда", "style": "friendly"},
  "safety": {"email-send": true, "file-delete": true},
  "plan": {"name": "Beta", "tokens_used": 800, "tokens_limit": 1000}
}

POST /users/{user_id}/settings

Применяет действие над настройками.

Request:

{
  "action": "toggle_skill",
  "payload": {"skill": "browser", "enabled": true}
}

Response 200:

{"ok": true}

---

Error format

{
  "error": "ERROR_CODE",
  "message": "Human readable description",
  "details": {}
}

Коды ошибок: USER_NOT_FOUND, RATE_LIMITED, PLATFORM_ERROR, CONTAINER_UNAVAILABLE

---

Открытые вопросы к Азамату (SDK)

• Точный формат эндпоинта отправки сообщения — URL, поля
• Как передавать вложения (файлы, изображения)? Через S3 pre-signed URL или напрямую?
• Стриминговый ответ (SSE / WebSocket) или только sync?
• Как обрабатывается chat_id на стороне платформы — это имя директории (C1/C2) или наш произвольный идентификатор?
• Есть ли endpoint для получения истории чата или она хранится только в history.db внутри контейнера?
• Формат SettingsAction — совпадает с нашим или другой?