Mikhail Putilovskij
b6df29bd9b
- Surface Protocol: unified IncomingMessage/OutgoingUI/ChatContext - Telegram: Forum Topics (group + topics per chat) - Matrix: Space + rooms per chat - MockPlatformClient with PlatformClient Protocol - docs: surface-protocol, telegram/matrix specs, api-contract, claude-code-guide - project scaffold: src/, tests/, pyproject.toml Co-Authored-By: Claude Sonnet 4-6 <noreply@anthropic.com>
150 lines
No EOL
3.1 KiB
Markdown
150 lines
No EOL
3.1 KiB
Markdown
# 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)?
|
||
- [ ] Как обрабатываются вложения (изображения, файлы)? |