DocsDevelopersREST API Reference
REST API Reference
All endpoints accept and return JSON (UTF-8). Base URL: https://<your-ref>.rootcx.com (or http://localhost:9100 if self-hosting). Auth via Authorization: Bearer <token> on all /api/v1/* routes unless marked public.
Each section below links to the page with full request/response documentation.
System
| Method | Path | Description |
|---|---|---|
| GET | /health |
Health check (?full=true for subsystem details) |
| GET | /api/v1/status |
Runtime status |
Authentication and OIDC
Full reference: Authentication
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/auth/register |
Register |
| POST | /api/v1/auth/login |
Login |
| POST | /api/v1/auth/refresh |
Refresh token |
| POST | /api/v1/auth/logout |
Logout |
| GET | /api/v1/auth/me |
Current user |
| GET | /api/v1/auth/mode |
Auth configuration |
| GET | /api/v1/users |
List users |
| DELETE | /api/v1/users/{id} |
Delete user |
| GET | /api/v1/auth/oidc/providers |
List OIDC providers |
| POST | /api/v1/auth/oidc/providers |
Create/update OIDC provider |
| DELETE | /api/v1/auth/oidc/providers/{id} |
Delete provider |
| GET | /api/v1/auth/oidc/{providerId}/authorize |
Start OIDC flow |
| GET | /api/v1/auth/oidc/callback |
OIDC callback |
| POST | /api/v1/auth/oidc/token-exchange |
Token exchange |
| POST | /api/v1/auth/magic-link/generate |
Generate magic link |
| POST | /api/v1/auth/magic-link/consume |
Consume magic link |
RBAC
Full reference: RBAC
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/roles |
List roles |
| POST | /api/v1/roles |
Create role |
| PATCH | /api/v1/roles/{roleName} |
Update role |
| DELETE | /api/v1/roles/{roleName} |
Delete role |
| GET | /api/v1/roles/assignments |
List assignments |
| POST | /api/v1/roles/assign |
Assign role |
| POST | /api/v1/roles/revoke |
Revoke role |
| GET | /api/v1/permissions |
Current user permissions |
| GET | /api/v1/permissions/available |
All permission keys |
| GET | /api/v1/permissions/{userId} |
User permissions |
Data API
Full reference: Data API
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/apps/{appId}/collections/{entity} |
List records |
| POST | /api/v1/apps/{appId}/collections/{entity} |
Create record |
| POST | /api/v1/apps/{appId}/collections/{entity}/query |
Query with operators |
| POST | /api/v1/apps/{appId}/collections/{entity}/bulk |
Bulk create |
| GET | /api/v1/apps/{appId}/collections/{entity}/{id} |
Get by ID |
| PATCH | /api/v1/apps/{appId}/collections/{entity}/{id} |
Update |
| DELETE | /api/v1/apps/{appId}/collections/{entity}/{id} |
Delete |
| POST | /api/v1/federated/{identityKind}/query |
Federated query |
Jobs and Crons
Full reference: Job Queue, Scheduled Jobs
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/apps/{appId}/jobs |
Enqueue job |
| GET | /api/v1/apps/{appId}/jobs |
List jobs |
| GET | /api/v1/crons |
List all crons |
| GET | /api/v1/apps/{appId}/crons |
List app crons |
| POST | /api/v1/apps/{appId}/crons |
Create cron |
| PATCH | /api/v1/apps/{appId}/crons/{id} |
Update cron |
| DELETE | /api/v1/apps/{appId}/crons/{id} |
Delete cron |
| GET | /api/v1/apps/{appId}/crons/{id}/runs |
Cron runs |
| POST | /api/v1/apps/{appId}/crons/{id}/trigger |
Fire cron |
Webhooks
Full reference: Webhooks
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/apps/{appId}/webhooks |
List webhooks |
| POST | /api/v1/hooks/{token} |
Inbound webhook |
Secrets
Full reference: Secret Vault
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/apps/{appId}/secrets |
Set app secret |
| GET | /api/v1/apps/{appId}/secrets |
List app secrets |
| DELETE | /api/v1/apps/{appId}/secrets/{key} |
Delete app secret |
| POST | /api/v1/platform/secrets |
Set platform secret |
| GET | /api/v1/platform/secrets |
List platform secrets |
| GET | /api/v1/platform/secrets/env |
Get decrypted env |
| DELETE | /api/v1/platform/secrets/{key} |
Delete platform secret |
Storage
Full reference: Storage
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/storage/buckets |
List buckets |
| POST | /api/v1/storage/buckets |
Create bucket |
| DELETE | /api/v1/storage/buckets/{name} |
Delete bucket |
| GET | /api/v1/storage/objects/{bucket} |
List objects |
| POST | /api/v1/storage/objects/{bucket} |
Create folder |
| POST | /api/v1/storage/objects/{bucket}/upload |
Upload file |
| GET | /api/v1/storage/objects/{bucket}/{id} |
Download file |
| PATCH | /api/v1/storage/objects/{bucket}/{id} |
Rename/move |
| DELETE | /api/v1/storage/objects/{bucket}/{id} |
Delete object |
Agents
Full reference: Build an AI Agent
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/agents |
List agents |
| POST | /api/v1/apps/{appId}/agent/invoke |
Invoke (SSE) |
| GET | /api/v1/apps/{appId}/agent/sessions |
List sessions |
| GET | /api/v1/apps/{appId}/agent/sessions/{id} |
Get session |
| GET | /api/v1/apps/{appId}/agent/approvals |
Pending approvals |
| POST | /api/v1/apps/{appId}/agent/approvals/{id} |
Approve/reject |
| GET | /api/v1/agents/stream |
Fleet stream (SSE) |
Integrations
Full reference: Build an Integration
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/integrations |
List integrations |
| GET | /api/v1/integrations/catalog |
List catalog |
| POST | /api/v1/integrations/catalog/{id}/deploy |
Deploy |
| DELETE | /api/v1/integrations/catalog/{id} |
Undeploy |
| PUT | /api/v1/integrations/{id}/config |
Save config |
| POST | /api/v1/integrations/{id}/actions/{actionId} |
Execute action |
| POST | /api/v1/integrations/{id}/auth/start |
Start OAuth |
| GET | /api/v1/integrations/auth/callback |
OAuth callback |
Channels
Full reference: Channels
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/channels |
List channels |
| POST | /api/v1/channels |
Create channel |
| DELETE | /api/v1/channels/{id} |
Delete channel |
| POST | /api/v1/channels/{id}/activate |
Activate |
| POST | /api/v1/channels/{id}/link |
Create link token |
Workers and Deploy
Full reference: Backend Development, Deploying
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/apps/{appId}/deploy |
Deploy backend (tar.gz) |
| POST | /api/v1/apps/{appId}/frontend |
Deploy frontend (tar.gz) |
| POST | /api/v1/apps/{appId}/upload |
Upload file (50 MB max) |
| POST | /api/v1/apps/{appId}/worker/start |
Start worker |
| POST | /api/v1/apps/{appId}/worker/stop |
Stop worker |
| GET | /api/v1/apps/{appId}/worker/status |
Worker status |
| POST | /api/v1/apps/{appId}/rpc |
Invoke RPC method |
| GET | /api/v1/apps/{appId}/logs |
Live logs (SSE) |
Audit
Full reference: Audit Log
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/audit |
Query audit log |
Error format
All errors return { "error": "message" } with the appropriate HTTP status: 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), 409 (conflict), 500 (internal).