API Reference
The Agentbase REST API is served from the core NestJS backend at http://localhost:3001/api.
Interactive Swagger documentation is available at /api/docs when running in development mode.
Authentication
Most endpoints require a JWT bearer token:
# Register
POST /api/auth/register
{ "email": "user@example.com", "password": "secret", "displayName": "User" }
# Login
POST /api/auth/login
{ "email": "user@example.com", "password": "secret" }
# Returns: { "access_token": "eyJ...", "refresh_token": "eyJ..." }
# Use the token
GET /api/applications
Authorization: Bearer eyJ...Core Endpoints
| Resource | Endpoints |
|---|---|
| Auth | POST /auth/register, POST /auth/login, POST /auth/refresh, OAuth (GitHub/Google) |
| Users | GET /users/me, PUT /users/me, DELETE /users/me |
| Applications | GET /applications, POST /applications, GET/PUT/DELETE /applications/:id |
| Conversations | GET /conversations, POST /conversations, POST /conversations/:id/messages, stream |
| Plugins | GET /plugins, GET /plugins/:id, install/activate/deactivate/configure per app |
| Themes | GET /themes, GET /themes/:id, set/customize per app |
| Prompts | GET /prompts, POST /prompts, PUT/DELETE /prompts/:id |
| Model Configs | GET /model-configs, POST /model-configs, versioning, A/B testing |
| Analytics | GET /analytics/overview, usage metrics, conversation stats, cost tracking |
| API Keys | GET /api-keys, POST /api-keys, DELETE /api-keys/:id |
| Provider Keys | GET/PUT/DELETE /provider-keys/:provider, POST /provider-keys/:provider/validate |
| Teams | GET /teams, POST /teams, invite/remove members, role management |
| Webhooks | GET /webhooks, POST /webhooks, PUT/DELETE /webhooks/:id, delivery logs |
| Marketplace | browse, featured, reviews, submit, install (plugins + themes) |
| Templates | GET /templates, POST /templates/:id/deploy |
| Knowledge | POST /knowledge (upload), GET /knowledge/search, per-app RAG documents |
| Uploads | POST /uploads, multipart file upload, S3-backed |
| Billing | plans, POST /billing/subscribe, GET /billing/invoices, usage limits |
| Branding | GET/PUT /branding/:appId — logo, colors, custom CSS per application |
| Custom Domains | GET /custom-domains, POST /custom-domains, verify, activate |
| Notifications | GET /notifications, PUT /notifications/:id/read, mark all read |
| SSO | SAML/LDAP configuration, POST /sso/saml/callback |
| Workflows | GET /workflows, POST /workflows, trigger/pause/resume automated flows |
| Audit | GET /audit — immutable audit log of admin and user actions |
| Data Export | POST /data-export — export conversations, analytics, or user data as CSV/JSON |
| Admin | GET /admin/users, GET /admin/marketplace, platform-level management (admin only) |
| System Health | GET /system-health — detailed system metrics (CPU, memory, DB, Redis) |
| Plugin Endpoints | ALL /plugins/:pluginId/endpoints/* — dynamic routes registered by plugins |
Public API (Widget)
The embeddable widget uses API key authentication via the X-API-Key header:
POST /api/public/chat
X-API-Key: agb_...
{ "message": "Hello!", "applicationId": "..." }BYOK — Bring Your Own Key
Users can securely store their own AI provider API keys and bypass the platform quota entirely. Keys are AES-256-GCM encrypted at rest and never returned in full.
# List saved provider keys (returns hints only, not the real keys)
GET /api/provider-keys
Authorization: Bearer <token>
# Returns: [{ "provider": "openai", "keyHint": "ab12", "isActive": true }, ...]
# Save or replace a key for a provider
PUT /api/provider-keys/:provider
Authorization: Bearer <token>
{ "apiKey": "sk-..." }
# provider: openai | anthropic | gemini | huggingface
# Remove a saved key
DELETE /api/provider-keys/:provider
Authorization: Bearer <token>
# Validate a key with a live test call
POST /api/provider-keys/:provider/validate
Authorization: Bearer <token>
# Returns: { "valid": true, "models": ["gpt-4", "gpt-3.5-turbo"] }See Provider Keys API for full details.
AI Service Endpoints
The Python AI microservice (http://localhost:8000) exposes its own API under /api/ai:
| Endpoint | Description |
|---|---|
GET /api/health | AI service health check |
GET /api/ai/providers | List all configured AI providers and their models |
GET /api/ai/providers/:provider/models | List models for a specific provider |
POST /api/ai/conversations | Create a new AI conversation (stored in MongoDB) |
GET /api/ai/conversations/:id | Retrieve conversation with full message history |
POST /api/ai/conversations/:id/messages | Send a message and get an AI response |
POST /api/ai/conversations/:id/stream | Send a message and stream the response via SSE |
The core NestJS API communicates with the AI service internally. Clients should generally use the core API at :3001 — the AI service endpoints are available for direct integration when needed.
Streaming (SSE)
POST http://localhost:8000/api/ai/conversations/{id}/stream
Content-Type: application/json
{
"content": "Explain quantum entanglement simply.",
"provider": "openai",
"model": "gpt-4",
"temperature": 0.7,
"system_prompt": "You are a helpful assistant."
}Response is a stream of Server-Sent Events:
data: {"type": "chunk", "content": "Quantum "}
data: {"type": "chunk", "content": "entanglement "}
data: {"type": "done", "fullResponse": "Quantum entanglement is..."}Rate Limiting
API responses include rate limit headers:
X-RateLimit-Limit— max requests per windowX-RateLimit-Remaining— remaining requestsX-RateLimit-Reset— window reset timestamp