Admin Endpoints
All endpoints in this section require the caller to have the global ADMIN role. Any request from a non-admin user returns 403 FORBIDDEN.
LLM Providers
Orbit supports multiple LLM backends. Only one provider/model is active at a time. The active provider is used for all AI chat generation.
GET /api/v1/admin/llm-providers
List all configured LLM providers.
Authentication: Required — ADMIN.
Response: Array of provider objects. Supported provider types: openai, ollama, anthropic, openrouter.
[
{
"id": "prov_001",
"type": "openai",
"is_active": true,
"active_model": "gpt-4o",
"base_url": null
},
{
"id": "prov_002",
"type": "ollama",
"is_active": false,
"active_model": null,
"base_url": "http://localhost:11434"
}
]
GET /api/v1/admin/llm-providers/{id}/models
List available models for a provider. For cloud providers this calls the provider's API to fetch the current model list. For Ollama this lists locally downloaded models.
Authentication: Required — ADMIN.
Response: Array of model identifier strings.
{
"data": ["gpt-4o", "gpt-4o-mini", "gpt-3.5-turbo"]
}
POST /api/v1/admin/llm-providers/{id}/activate
Set a provider and model as the active LLM for chat generation.
Authentication: Required — ADMIN.
Request:
{
"model": "gpt-4o"
}
Response: Updated provider object with is_active: true.
PATCH /api/v1/admin/llm-providers/{id}
Update configuration for a provider (API key, base URL, generation parameters).
Authentication: Required — ADMIN.
Request:
{
"api_key": "sk-...",
"base_url": "https://api.openai.com/v1",
"temperature": 0.2,
"max_tokens": 2048
}
All fields optional. api_key is write-only — it is never returned in responses.
POST /api/v1/admin/ollama/models/pull
Pull (download) a model to the local Ollama instance. This is a long-running background operation.
Authentication: Required — ADMIN.
Request:
{
"model_name": "smollm2"
}
Response: 202 Accepted with a job status object. Poll GET /api/v1/admin/llm-providers/ollama/models to check when the model appears.
Knowledge Settings
These settings control the RAG pipeline used to index materials and retrieve context for chat.
GET /api/v1/admin/knowledge-settings
Retrieve current RAG pipeline configuration.
Authentication: Required — ADMIN.
Response:
{
"data": {
"chunk_size": 512,
"chunk_overlap": 64,
"retrieval_max_chunks": 10,
"citation_enabled": true,
"citation_max_items": 5
}
}
PATCH /api/v1/admin/knowledge-settings
Update one or more RAG settings. Changes apply to new material uploads; existing materials are not automatically re-indexed.
Authentication: Required — ADMIN.
Request: Any subset of the settings object fields.
{
"chunk_size": 1024,
"chunk_overlap": 128,
"retrieval_max_chunks": 8,
"citation_enabled": true,
"citation_max_items": 3
}
Changing chunk_size or chunk_overlap will produce inconsistent retrieval results until all existing materials are re-processed under the new settings.
Users
GET /api/v1/admin/users
List all application users.
Authentication: Required — ADMIN.
Query parameters:
| Parameter | Description |
|---|---|
role | Filter by global_role. |
is_deleted | true to show only soft-deleted users. |
page, page_size | Standard pagination. |
Response: Paginated list of user objects.
PATCH /api/v1/admin/users/{id}/role
Change a user's global role.
Authentication: Required — ADMIN.
Request:
{
"global_role": "TEACHER"
}
Valid values: NO_ROLE, STUDENT, TEACHER, ADMIN.
Constraints:
- Cannot demote the last global ADMIN.
Response: Updated user object.
POST /api/v1/admin/users/{id}/delete
Soft-delete a user account. The user loses access immediately. Data is retained.
Authentication: Required — ADMIN.
Request body: Empty.
Constraints:
- Cannot delete the last global ADMIN.
- Cannot delete a user who is the last teacher in any class.
Response: 204 No Content.
POST /api/v1/admin/users/{id}/restore
Restore a soft-deleted user account, re-enabling their access.
Authentication: Required — ADMIN.
Request body: Empty.
Response: Restored user object.
Audit Log
GET /api/v1/admin/audit
Retrieve a paginated list of audit events capturing administrative and user actions.
Authentication: Required — ADMIN.
Query parameters:
| Parameter | Description |
|---|---|
type | Filter by event type (e.g. USER_ROLE_CHANGED, CLASS_ARCHIVED). |
actor_id | Filter by the user who performed the action. |
resource_id | Filter by the affected resource ID. |
from, to | ISO 8601 timestamps to bound the time range. |
page, page_size | Standard pagination. |
Response: Paginated list of audit event objects.
{
"data": [
{
"id": "evt_001",
"type": "USER_ROLE_CHANGED",
"actor_id": "usr_001",
"resource_id": "usr_456",
"metadata": {
"old_role": "STUDENT",
"new_role": "TEACHER"
},
"created_at": "2026-03-14T09:30:00Z"
}
],
"meta": {
"page": 1,
"page_size": 20,
"total": 1,
"has_next": false
}
}
General Settings
GET /api/v1/admin/general-settings
Retrieve application-wide display settings.
Authentication: Required — ADMIN.
Response:
{
"data": {
"app_name": "Orbit Classroom",
"theme": "system",
"show_thinking_overlay": true
}
}
PATCH /api/v1/admin/general-settings
Update one or more general settings.
Authentication: Required — ADMIN.
Request: Any subset of { "app_name", "theme", "show_thinking_overlay" }.
{
"app_name": "My Classroom",
"theme": "dark",
"show_thinking_overlay": true
}
theme— accepted values:"light","dark","system".show_thinking_overlay— boolean; whentrue, the UI displays a "thinking..." overlay while the AI generates a response.
System Status
GET /api/v1/admin/system-status
Retrieve real-time server resource utilization and provider health checks.
Authentication: Required — ADMIN.
Response:
{
"data": {
"cpu_percent": 14.2,
"ram_percent": 61.8,
"disk_percent": 43.0,
"gpu_percent": 0,
"provider_health": [
{
"provider_id": "prov_001",
"type": "openai",
"is_reachable": true,
"latency_ms": 210
},
{
"provider_id": "prov_002",
"type": "ollama",
"is_reachable": false,
"latency_ms": null
}
]
}
}
GPU fields are 0 when no GPU is detected. is_reachable: false indicates the provider endpoint could not be reached at the time of the health check.