145 lines
4.2 KiB
Markdown
145 lines
4.2 KiB
Markdown
# 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:**
|
||
```json
|
||
{
|
||
"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:**
|
||
```json
|
||
{
|
||
"text": "Привет, что ты умеешь?",
|
||
"attachments": []
|
||
}
|
||
```
|
||
|
||
**Response 200:**
|
||
```json
|
||
{
|
||
"message_id": "msg_qwe012",
|
||
"response": "Я AI-агент Lambda...",
|
||
"tokens_used": 142,
|
||
"finished": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Settings
|
||
|
||
### GET /users/{user_id}/settings
|
||
|
||
Настройки пользователя: скиллы, коннекторы, SOUL, безопасность, план.
|
||
|
||
**Response 200:**
|
||
```json
|
||
{
|
||
"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:**
|
||
```json
|
||
{
|
||
"action": "toggle_skill",
|
||
"payload": {"skill": "browser", "enabled": true}
|
||
}
|
||
```
|
||
|
||
**Response 200:**
|
||
```json
|
||
{"ok": true}
|
||
```
|
||
|
||
---
|
||
|
||
## Error format
|
||
|
||
```json
|
||
{
|
||
"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` — совпадает с нашим или другой?
|