109 lines
No EOL
2.7 KiB
Markdown
109 lines
No EOL
2.7 KiB
Markdown
# Admin API
|
|
|
|
The Admin API provides endpoints for system administration, user management, and configuration management.
|
|
|
|
## Status: Roadmap
|
|
|
|
This API is on the development roadmap. The endpoints documented below represent the planned interface design.
|
|
|
|
## Base URL
|
|
|
|
```
|
|
http://localhost:8080/api/v1/admin
|
|
```
|
|
|
|
## Authentication
|
|
|
|
Uses the standard botserver authentication mechanism with administrator-level permissions required.
|
|
|
|
## Endpoints
|
|
|
|
### System Configuration
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/v1/admin/config` | Retrieve system configuration |
|
|
| PUT | `/api/v1/admin/config` | Update system configuration |
|
|
|
|
### User Management
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/v1/admin/users` | List all users |
|
|
| POST | `/api/v1/admin/users` | Create a new user |
|
|
| GET | `/api/v1/admin/users/{user_id}` | Get user details |
|
|
| PUT | `/api/v1/admin/users/{user_id}` | Update user |
|
|
| DELETE | `/api/v1/admin/users/{user_id}` | Delete user |
|
|
|
|
### Bot Management
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/v1/admin/bots` | List all bots |
|
|
| GET | `/api/v1/admin/bots/{bot_id}` | Get bot details |
|
|
| POST | `/api/v1/admin/bots/{bot_id}/restart` | Restart a bot |
|
|
| DELETE | `/api/v1/admin/bots/{bot_id}` | Delete a bot |
|
|
|
|
### System Health
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/v1/admin/health` | System health check |
|
|
| GET | `/api/v1/admin/metrics` | System metrics |
|
|
|
|
### Audit Logs
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/v1/admin/audit` | Retrieve audit logs |
|
|
| GET | `/api/v1/admin/audit/{event_id}` | Get specific audit event |
|
|
|
|
## Request Examples
|
|
|
|
### Get System Configuration
|
|
|
|
```bas
|
|
config = GET "/api/v1/admin/config"
|
|
TALK "Server port: " + config.server_port
|
|
```
|
|
|
|
### Create User
|
|
|
|
```bas
|
|
user_data = NEW OBJECT
|
|
user_data.email = "admin@example.com"
|
|
user_data.role = "administrator"
|
|
|
|
result = POST "/api/v1/admin/users", user_data
|
|
TALK "Created user: " + result.id
|
|
```
|
|
|
|
### Restart Bot
|
|
|
|
```bas
|
|
POST "/api/v1/admin/bots/my-bot/restart", {}
|
|
TALK "Bot restart initiated"
|
|
```
|
|
|
|
## Response Codes
|
|
|
|
| Code | Description |
|
|
|------|-------------|
|
|
| 200 | Success |
|
|
| 201 | Created |
|
|
| 204 | No Content (successful deletion) |
|
|
| 400 | Bad Request |
|
|
| 401 | Unauthorized |
|
|
| 403 | Forbidden (insufficient permissions) |
|
|
| 404 | Not Found |
|
|
| 500 | Internal Server Error |
|
|
|
|
## Required Permissions
|
|
|
|
| Endpoint Category | Required Role |
|
|
|-------------------|---------------|
|
|
| System Configuration | `admin` |
|
|
| User Management | `admin` |
|
|
| Bot Management | `admin` or `bot_manager` |
|
|
| System Health | `admin` or `monitor` |
|
|
| Audit Logs | `admin` or `auditor` | |