# 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?
- [ ] Формат `SettingsAction` — совпадает с нашим или другой?