# API Contract — Lambda Platform

> **Статус:** ЧЕРНОВИК — проектируем сами, не ждём SDK
> **Автор:** @architect
> **Последнее обновление:** заполнить дату

Это описание того, что нам нужно от платформы.
`MockPlatformClient` реализует этот контракт. При подключении реального SDK — только он меняется.

---

## 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
}
```

---

## Sessions

### POST /sessions
Создаёт новую сессию с AI-агентом.

**Request:**
```json
{
  "user_id": "usr_abc123",
  "platform": "telegram",
  "context": {}
}
```

**Response 201:**
```json
{
  "session_id": "ses_xyz789",
  "agent_id": "agt_def456",
  "created_at": "2025-01-15T10:30:00Z",
  "expires_at": "2025-01-16T10:30:00Z"
}
```

### GET /sessions/{session_id}
Получает информацию о сессии.

**Response 200:** — см. структуру выше + поле `status: "active" | "closed"`
**Response 404:** `{"error": "SESSION_NOT_FOUND", "message": "..."}`

### DELETE /sessions/{session_id}
Завершает сессию.

**Response 200:**
```json
{"closed": true}
```

---

## Messages

### POST /sessions/{session_id}/messages
Отправляет сообщение и получает ответ агента.

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

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

### GET /sessions/{session_id}/messages?limit=20&offset=0
История сообщений сессии.

**Response 200:**
```json
[
  {
    "message_id": "msg_qwe012",
    "user_text": "Привет",
    "response": "Привет!",
    "tokens_used": 42,
    "created_at": "2025-01-15T10:31:00Z"
  }
]
```

---

## Error format

Все ошибки возвращаются в едином формате:

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

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

---

## TODO (открытые вопросы к команде платформы)

- [ ] Нужна ли стриминговая передача ответа (SSE / WebSocket)?
- [ ] Как обрабатываются вложения (изображения, файлы)?