| --- |
| outline: deep |
| --- |
| |
| # AstrBot HTTP API |
|
|
| Starting from v4.18.0, AstrBot provides API Key based HTTP APIs for programmatic access. |
|
|
| ## Quick Start |
|
|
| 1. Create an API key in WebUI - Settings. |
| 2. Include the API key in request headers: |
|
|
| ```http |
| Authorization: Bearer abk_xxx |
| ``` |
|
|
| Also supported: |
|
|
| ```http |
| X-API-Key: abk_xxx |
| ``` |
|
|
| 3. For chat endpoints, `username` is required: |
|
|
| - `POST /api/v1/chat`: request body must include `username` |
| - `GET /api/v1/chat/sessions`: query params must include `username` |
|
|
| ## Common Endpoints |
|
|
| - `POST /api/v1/chat`: send chat message (SSE stream, server generates UUID when `session_id` is omitted) |
| - `GET /api/v1/chat/sessions`: list sessions for a specific `username` with pagination |
| - `GET /api/v1/configs`: list available config files |
| - `POST /api/v1/file`: upload attachment |
| - `POST /api/v1/im/message`: proactive message via UMO |
| - `GET /api/v1/im/bots`: list bot/platform IDs |
|
|
| ## Example |
|
|
| ```bash |
| curl -N 'http://localhost:7860/api/v1/chat' \ |
| -H 'Authorization: Bearer abk_xxx' \ |
| -H 'Content-Type: application/json' \ |
| -d '{"message":"Hello","username":"alice"}' |
| ``` |
|
|
| ## Full API Reference |
|
|
| Use the interactive docs: |
|
|
| - https://docs.astrbot.app/scalar.html |
|
|
