This document covers the authentication mechanisms and architectural overview of the AnythingLLM Developer API. It explains how to generate and use API keys, the structure of API requests and responses, and provides an overview of the available endpoint categories.
For information about specific endpoint implementations, see:
AnythingLLM uses API Key authentication to secure programmatic access to the system. All API requests must include a valid API key in the Authorization header.
Sources: server/utils/middleware/validApiKey.js server/models/apiKeys.js
API keys can be generated in two modes depending on the system configuration:
In single-user mode (when multi-user is disabled), API keys can be generated without user association.
| Endpoint | Method | Authentication | Description |
|---|---|---|---|
/system/generate-api-key | POST | JWT Token | Generate new API key |
/system/api-keys | GET | JWT Token | List all API keys |
/system/api-key/:id | DELETE | JWT Token | Delete an API key |
Sources: server/endpoints/system.js1029-1082
In multi-user mode, API keys are associated with user accounts and require admin privileges to manage.
| Endpoint | Method | Authentication | Role Required | Description |
|---|---|---|---|---|
/admin/generate-api-key | POST | JWT Token | admin | Generate new API key |
/admin/api-keys | GET | JWT Token | admin | List all API keys with user info |
/admin/api-key/:id | DELETE | JWT Token | admin | Delete an API key |
Sources: server/endpoints/admin.js433-451 server/endpoints/api/admin/index.js453-470
Sources: server/models/apiKeys.js
All API requests must include the API key in the Authorization header using the Bearer token format:
Authorization: Bearer {your-api-key}
Example Request:
Sources: server/utils/middleware/validApiKey.js
Sources: server/utils/middleware/validApiKey.js server/endpoints/api/workspace/index.js1-19
All API responses follow consistent patterns:
Sources: server/swagger/openapi.json40-47
Sources: server/swagger/openapi.json13-52 server/endpoints/api/workspace/index.js server/endpoints/api/document/index.js
| Category | Base Path | Authentication | Multi-User Check | Admin Required |
|---|---|---|---|---|
| Authentication | /v1/auth | API Key | No | No |
| Workspace | /v1/workspace/* | API Key | No | No |
| Document | /v1/document/* | API Key | No | No |
| Admin | /v1/admin/* | API Key | Yes | Yes |
| System | /v1/system/* | API Key | Varies | Varies |
| OpenAI | /v1/openai/* | API Key | No | No |
Sources: server/endpoints/api/admin/index.js15-39 server/endpoints/api/workspace/index.js22-101
AnythingLLM provides interactive API documentation via Swagger UI.
The API documentation is available at:
https://your-instance.com/api/docs
No authentication is required to view the documentation, but executing requests through the Swagger UI requires a valid API key.
Sources: server/swagger/openapi.json1-12 frontend/src/utils/paths.js95-97
The API documentation organizes endpoints into the following tags:
Sources: server/swagger/openapi.json15-50
Sources: server/utils/middleware/validApiKey.js
| Method | Description | Returns |
|---|---|---|
ApiKey.create(userId) | Generate new API key with sk- prefix | { apiKey, error } |
ApiKey.get({ secret }) | Retrieve key by secret value | apiKey object or null |
ApiKey.where(clause) | Query multiple keys | Array<apiKey> |
ApiKey.whereWithUser(clause) | Query with user join | Array<apiKey with user> |
ApiKey.delete({ id }) | Remove an API key | boolean |
Sources: server/models/apiKeys.js
Sources: server/endpoints/api/admin/index.js71-83
In multi-user mode, certain endpoints require specific roles:
| Endpoint Pattern | Role Required | Example |
|---|---|---|
/v1/admin/users | admin | User management |
/v1/admin/invites | admin or manager | Invite management |
/v1/admin/workspaces | admin or manager | Workspace administration |
/v1/admin/preferences | admin | System preferences |
/v1/admin/api-keys | admin | API key management |
Sources: server/endpoints/api/admin/index.js41-450
| Status Code | Meaning | When Used |
|---|---|---|
200 | OK | Successful request |
400 | Bad Request | Invalid parameters or missing required fields |
401 | Unauthorized | No valid authentication provided |
403 | Forbidden | Invalid API key or insufficient permissions |
404 | Not Found | Resource does not exist |
500 | Internal Server Error | Server-side error occurred |
503 | Service Unavailable | External service (e.g., Collector) offline |
Sources: server/endpoints/api/workspace/index.js661-669 server/endpoints/api/document/index.js107-116
Sources: server/endpoints/api/workspace/index.js649-699
The frontend provides a System model that abstracts API calls:
Sources: frontend/src/models/system.js540-582
All API requests from the frontend use the baseHeaders() utility:
Sources: frontend/src/utils/request.js frontend/src/models/system.js1
The AnythingLLM API provides comprehensive programmatic access to all system features through a REST API secured by API key authentication. Key characteristics:
sk- prefix/api/docsSources: server/swagger/openapi.json server/utils/middleware/validApiKey.js server/models/apiKeys.js
Refresh this wiki