Rodrigo Rodriguez (Pragmatismo)
d1301c9cd8
Documentation organized with equilibrium: - Small (50-100 lines): Index files - Medium (250-400 lines): Guides - Large (450-600 lines): Complete references Structure: - docs/api/ - REST endpoints, WebSocket - docs/guides/ - Getting started, deployment, templates - docs/reference/ - BASIC language, configuration, architecture Updated README.md to point to new docs location.
599 lines
8 KiB
Markdown
599 lines
8 KiB
Markdown
# REST API Endpoints
|
|
|
|
Complete reference for all General Bots REST API endpoints.
|
|
|
|
## Sessions
|
|
|
|
### List Sessions
|
|
|
|
```http
|
|
GET /api/sessions
|
|
```
|
|
|
|
**Query Parameters:**
|
|
|
|
| Parameter | Type | Description |
|
|
|-----------|------|-------------|
|
|
| `limit` | integer | Max results (default: 50) |
|
|
| `offset` | integer | Pagination offset |
|
|
| `status` | string | Filter by status: `active`, `closed` |
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"sessions": [
|
|
{
|
|
"id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"user_id": "user@example.com",
|
|
"bot_id": "default",
|
|
"status": "active",
|
|
"created_at": "2024-01-01T10:00:00Z",
|
|
"last_activity": "2024-01-01T10:30:00Z"
|
|
}
|
|
],
|
|
"total": 1,
|
|
"limit": 50,
|
|
"offset": 0
|
|
}
|
|
```
|
|
|
|
### Create Session
|
|
|
|
```http
|
|
POST /api/sessions
|
|
```
|
|
|
|
**Request Body:**
|
|
|
|
```json
|
|
{
|
|
"bot_id": "default",
|
|
"user_id": "user@example.com",
|
|
"metadata": {
|
|
"channel": "web",
|
|
"language": "en"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Get Session
|
|
|
|
```http
|
|
GET /api/sessions/:id
|
|
```
|
|
|
|
### Send Message
|
|
|
|
```http
|
|
POST /api/sessions/:id/messages
|
|
```
|
|
|
|
**Request Body:**
|
|
|
|
```json
|
|
{
|
|
"content": "Hello, I need help",
|
|
"type": "text"
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"id": "msg-uuid",
|
|
"session_id": "session-uuid",
|
|
"role": "assistant",
|
|
"content": "Hello! How can I assist you today?",
|
|
"timestamp": "2024-01-01T10:31:00Z"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Drive (File Storage)
|
|
|
|
### List Files
|
|
|
|
```http
|
|
GET /api/drive
|
|
GET /api/drive/:path
|
|
```
|
|
|
|
**Query Parameters:**
|
|
|
|
| Parameter | Type | Description |
|
|
|-----------|------|-------------|
|
|
| `recursive` | boolean | Include subdirectories |
|
|
| `type` | string | Filter: `file`, `folder` |
|
|
|
|
### Upload File
|
|
|
|
```http
|
|
POST /api/drive/:path
|
|
Content-Type: multipart/form-data
|
|
```
|
|
|
|
### Download File
|
|
|
|
```http
|
|
GET /api/drive/:path/download
|
|
```
|
|
|
|
### Delete File
|
|
|
|
```http
|
|
DELETE /api/drive/:path
|
|
```
|
|
|
|
---
|
|
|
|
## Tasks
|
|
|
|
### List Tasks
|
|
|
|
```http
|
|
GET /api/tasks
|
|
```
|
|
|
|
**Query Parameters:**
|
|
|
|
| Parameter | Type | Description |
|
|
|-----------|------|-------------|
|
|
| `status` | string | `pending`, `completed`, `cancelled` |
|
|
| `priority` | string | `low`, `medium`, `high` |
|
|
| `due_before` | datetime | Filter by due date |
|
|
|
|
### Create Task
|
|
|
|
```http
|
|
POST /api/tasks
|
|
```
|
|
|
|
**Request Body:**
|
|
|
|
```json
|
|
{
|
|
"title": "Follow up with client",
|
|
"description": "Send proposal document",
|
|
"due_date": "2024-01-15T17:00:00Z",
|
|
"priority": "high",
|
|
"assignee": "user@example.com"
|
|
}
|
|
```
|
|
|
|
### Update Task
|
|
|
|
```http
|
|
PUT /api/tasks/:id
|
|
```
|
|
|
|
### Delete Task
|
|
|
|
```http
|
|
DELETE /api/tasks/:id
|
|
```
|
|
|
|
---
|
|
|
|
## Email
|
|
|
|
### List Emails
|
|
|
|
```http
|
|
GET /api/email
|
|
GET /api/email/:folder
|
|
```
|
|
|
|
**Folders:** `inbox`, `sent`, `drafts`, `trash`
|
|
|
|
### Send Email
|
|
|
|
```http
|
|
POST /api/email/send
|
|
```
|
|
|
|
**Request Body:**
|
|
|
|
```json
|
|
{
|
|
"to": ["recipient@example.com"],
|
|
"cc": [],
|
|
"bcc": [],
|
|
"subject": "Meeting Tomorrow",
|
|
"body": "Hi, let's meet at 3pm.",
|
|
"html": false,
|
|
"attachments": []
|
|
}
|
|
```
|
|
|
|
### Get Email
|
|
|
|
```http
|
|
GET /api/email/:id
|
|
```
|
|
|
|
### Delete Email
|
|
|
|
```http
|
|
DELETE /api/email/:id
|
|
```
|
|
|
|
---
|
|
|
|
## Calendar
|
|
|
|
### List Events
|
|
|
|
```http
|
|
GET /api/calendar/events
|
|
```
|
|
|
|
**Query Parameters:**
|
|
|
|
| Parameter | Type | Description |
|
|
|-----------|------|-------------|
|
|
| `start` | datetime | Range start |
|
|
| `end` | datetime | Range end |
|
|
| `calendar_id` | string | Specific calendar |
|
|
|
|
### Create Event
|
|
|
|
```http
|
|
POST /api/calendar/events
|
|
```
|
|
|
|
**Request Body:**
|
|
|
|
```json
|
|
{
|
|
"title": "Team Meeting",
|
|
"start_time": "2024-01-15T14:00:00Z",
|
|
"end_time": "2024-01-15T15:00:00Z",
|
|
"location": "Conference Room A",
|
|
"attendees": ["team@example.com"],
|
|
"recurrence": null
|
|
}
|
|
```
|
|
|
|
### Export Calendar (iCal)
|
|
|
|
```http
|
|
GET /api/calendar/export.ics
|
|
```
|
|
|
|
### Import Calendar
|
|
|
|
```http
|
|
POST /api/calendar/import
|
|
Content-Type: text/calendar
|
|
```
|
|
|
|
---
|
|
|
|
## Meet (Video Conferencing)
|
|
|
|
### Create Room
|
|
|
|
```http
|
|
POST /api/meet/rooms
|
|
```
|
|
|
|
**Request Body:**
|
|
|
|
```json
|
|
{
|
|
"name": "Team Standup",
|
|
"scheduled_start": "2024-01-15T09:00:00Z",
|
|
"max_participants": 10
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"room_id": "room-uuid",
|
|
"join_url": "https://meet.example.com/room-uuid",
|
|
"token": "participant-token"
|
|
}
|
|
```
|
|
|
|
### Join Room
|
|
|
|
```http
|
|
POST /api/meet/rooms/:id/join
|
|
```
|
|
|
|
### List Participants
|
|
|
|
```http
|
|
GET /api/meet/rooms/:id/participants
|
|
```
|
|
|
|
---
|
|
|
|
## Knowledge Base
|
|
|
|
### Search
|
|
|
|
```http
|
|
GET /api/kb/search
|
|
```
|
|
|
|
**Query Parameters:**
|
|
|
|
| Parameter | Type | Description |
|
|
|-----------|------|-------------|
|
|
| `q` | string | Search query (required) |
|
|
| `limit` | integer | Max results (default: 10) |
|
|
| `threshold` | float | Similarity threshold (0-1) |
|
|
| `collection` | string | Specific KB collection |
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"results": [
|
|
{
|
|
"id": "doc-uuid",
|
|
"content": "Relevant document content...",
|
|
"score": 0.95,
|
|
"metadata": {
|
|
"source": "company-docs",
|
|
"title": "Employee Handbook"
|
|
}
|
|
}
|
|
],
|
|
"query": "vacation policy",
|
|
"total": 5
|
|
}
|
|
```
|
|
|
|
### List Collections
|
|
|
|
```http
|
|
GET /api/kb/collections
|
|
```
|
|
|
|
### Reindex Collection
|
|
|
|
```http
|
|
POST /api/kb/reindex
|
|
```
|
|
|
|
---
|
|
|
|
## Analytics
|
|
|
|
### Dashboard Stats
|
|
|
|
```http
|
|
GET /api/analytics/stats
|
|
```
|
|
|
|
**Query Parameters:**
|
|
|
|
| Parameter | Type | Description |
|
|
|-----------|------|-------------|
|
|
| `time_range` | string | `day`, `week`, `month`, `year` |
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"total_messages": 15420,
|
|
"active_sessions": 45,
|
|
"avg_response_time_ms": 230,
|
|
"error_rate": 0.02,
|
|
"top_queries": [
|
|
{"query": "password reset", "count": 120}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Message Trends
|
|
|
|
```http
|
|
GET /api/analytics/messages/trend
|
|
```
|
|
|
|
---
|
|
|
|
## Paper (Documents)
|
|
|
|
### List Documents
|
|
|
|
```http
|
|
GET /api/paper
|
|
```
|
|
|
|
### Create Document
|
|
|
|
```http
|
|
POST /api/paper
|
|
```
|
|
|
|
**Request Body:**
|
|
|
|
```json
|
|
{
|
|
"title": "Meeting Notes",
|
|
"content": "# Meeting Notes\n\n...",
|
|
"type": "note"
|
|
}
|
|
```
|
|
|
|
### Get Document
|
|
|
|
```http
|
|
GET /api/paper/:id
|
|
```
|
|
|
|
### Update Document
|
|
|
|
```http
|
|
PUT /api/paper/:id
|
|
```
|
|
|
|
### Delete Document
|
|
|
|
```http
|
|
DELETE /api/paper/:id
|
|
```
|
|
|
|
---
|
|
|
|
## Designer (Bot Builder)
|
|
|
|
### List Dialogs
|
|
|
|
```http
|
|
GET /api/designer/dialogs
|
|
```
|
|
|
|
### Create Dialog
|
|
|
|
```http
|
|
POST /api/designer/dialogs
|
|
```
|
|
|
|
**Request Body:**
|
|
|
|
```json
|
|
{
|
|
"name": "greeting",
|
|
"content": "TALK \"Hello!\"\nanswer = HEAR"
|
|
}
|
|
```
|
|
|
|
### Validate Dialog
|
|
|
|
```http
|
|
POST /api/designer/dialogs/:id/validate
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"valid": true,
|
|
"errors": [],
|
|
"warnings": ["Line 15: Consider using END IF"]
|
|
}
|
|
```
|
|
|
|
### Deploy Dialog
|
|
|
|
```http
|
|
POST /api/designer/dialogs/:id/deploy
|
|
```
|
|
|
|
---
|
|
|
|
## Sources (Templates)
|
|
|
|
### List Templates
|
|
|
|
```http
|
|
GET /api/sources/templates
|
|
```
|
|
|
|
**Query Parameters:**
|
|
|
|
| Parameter | Type | Description |
|
|
|-----------|------|-------------|
|
|
| `category` | string | Filter by category |
|
|
|
|
### Get Template
|
|
|
|
```http
|
|
GET /api/sources/templates/:id
|
|
```
|
|
|
|
### Use Template
|
|
|
|
```http
|
|
POST /api/sources/templates/:id/use
|
|
```
|
|
|
|
---
|
|
|
|
## Admin
|
|
|
|
### System Stats
|
|
|
|
```http
|
|
GET /api/admin/stats
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"uptime_seconds": 86400,
|
|
"memory_used_mb": 512,
|
|
"active_connections": 23,
|
|
"database_size_mb": 1024,
|
|
"cache_hit_rate": 0.85
|
|
}
|
|
```
|
|
|
|
### Health Check
|
|
|
|
```http
|
|
GET /api/health
|
|
```
|
|
|
|
**Response:**
|
|
|
|
```json
|
|
{
|
|
"status": "healthy",
|
|
"components": {
|
|
"database": "ok",
|
|
"cache": "ok",
|
|
"storage": "ok",
|
|
"llm": "ok"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Error Codes
|
|
|
|
| Code | HTTP Status | Description |
|
|
|------|-------------|-------------|
|
|
| `BAD_REQUEST` | 400 | Invalid request parameters |
|
|
| `UNAUTHORIZED` | 401 | Missing or invalid auth token |
|
|
| `FORBIDDEN` | 403 | Insufficient permissions |
|
|
| `NOT_FOUND` | 404 | Resource not found |
|
|
| `CONFLICT` | 409 | Resource already exists |
|
|
| `RATE_LIMITED` | 429 | Too many requests |
|
|
| `INTERNAL_ERROR` | 500 | Server error |
|
|
|
|
---
|
|
|
|
## Pagination
|
|
|
|
List endpoints support pagination:
|
|
|
|
```http
|
|
GET /api/tasks?limit=20&offset=40
|
|
```
|
|
|
|
Response includes pagination info:
|
|
|
|
```json
|
|
{
|
|
"data": [...],
|
|
"pagination": {
|
|
"total": 150,
|
|
"limit": 20,
|
|
"offset": 40,
|
|
"has_more": true
|
|
}
|
|
}
|
|
```
|