API Reference
The Qelos platform exposes a RESTful HTTP API that powers all platform functionality. Every operation available through the TypeScript SDK maps directly to an API endpoint documented here.
New: Gateway endpoint reference — all major gateway paths in one place, with curl and SDK snippets (entities, auth, workspaces, AI, roles, events) and a routing overview aligned with apps/gateway/server/services/proxy-middleware/config.ts.
Base URL
All endpoints are relative to your Qelos application URL:
https://your-qelos-app.com/api/...Authentication
Most endpoints require authentication. Qelos supports three authentication mechanisms:
| Method | Header / Mechanism | Description |
|---|---|---|
| Session cookie | Cookie (set by POST /api/signin) | Browser-based session authentication |
| OAuth tokens | Authorization: Bearer <accessToken> | Token-based authentication with automatic refresh |
| API token | x-api-key: <apiToken> | Long-lived tokens for scripts, CI/CD, and plugins |
See the Authentication API for details on obtaining credentials.
SDK equivalent: SDK Authentication
Common Patterns
Request Format
Content-Type: application/jsonfor all request bodies- Query parameters use standard URL encoding
- Path parameters are indicated with
{paramName}in endpoint paths
Response Format
All responses return JSON. Successful responses return the resource directly or wrapped in a standard envelope. Error responses follow this structure:
{
"error": "Error message describing what went wrong"
}Common HTTP Status Codes
| Code | Meaning |
|---|---|
200 | Success |
201 | Resource created |
400 | Bad request (invalid parameters) |
401 | Unauthorized (missing or invalid credentials) |
403 | Forbidden (insufficient permissions) |
404 | Resource not found |
500 | Internal server error |
Query Parameters
Many list endpoints support common query parameters:
| Parameter | Type | Description |
|---|---|---|
$limit | number | Maximum number of results to return |
$skip | number | Number of results to skip (for pagination) |
$sort | string | Sort field (prefix with - for descending) |
$flat | boolean | Return flat entity structure. Default true for blueprint entity endpoints; pass $flat=false (or 0) to receive the wrapped shape with metadata nested under metadata. |
$populate | boolean | Populate related references |
API Sections
Gateway (all services, one entry point)
- Gateway endpoint reference — Route map, common headers, and per-domain
curl+ SDK for entities, auth, workspaces, AI, roles, and events
Core
- Authentication — Sign in, sign up, token management, and user profile
- Workspaces — Multi-tenant workspace operations
- Invites — Workspace invitation handling
Data
- Blueprints — Data model definitions and analytics
- Blueprint Entities — CRUD operations on blueprint data
- Blocks — Content block management
- Configurations — Application configuration settings
Execution
- Webhooks / Lambdas — Execute serverless functions and webhooks
Payments
- Payments — Plans, subscriptions, invoices, and checkout
AI
- AI Threads — Conversation thread management
- AI Chat — Chat completions and streaming
- AI RAG — Vector storage for Retrieval-Augmented Generation
SDK ↔ API Mapping
Every SDK method corresponds to an API endpoint. Each API page links back to the relevant SDK documentation, and vice versa.