Reference
API Reference
Complete reference for all CognitionDesk REST API endpoints. The base URL for all requests is https://api.cognitiondesk.com.
Jump to section
🟢 Health & Diagnostics👤 Users🔑 API Keys💬 Chat📄 Documents & Files🗄️ Storage🧠 Knowledge Base🤖 AI Model Provider📊 Usage & Billing🏢 Organizations🤖 Assistants & Workflows🚦 Plan Limits & 429 Behavior🛠️ Tools📱 Messaging Platforms💬 WhatsApp Business🔌 REST API Connections🟢 Health & Diagnostics
Public health endpoints — no authentication required.
| Method | Endpoint | Description |
|---|---|---|
| GET | /health | Basic server health check |
| GET | /health/ping | Fast ping/pong |
| GET | /health/status | Detailed status: memory, Node version |
| GET | /health/qdrant | Qdrant vector DB diagnostics |
| GET | /health/services | All critical services status |
| GET | /diagnostics/qdrant | Full Qdrant diagnostic with recommendations |
👤 Users
| Method | Endpoint | Description |
|---|---|---|
| POST | /users/setupUser | Initialize a new user account |
🔑 API Keys
| Method | Endpoint | Description |
|---|---|---|
| POST | /apikeys/generate-api-key | Generate a new API key for the user |
💬 Chat
Two base paths: /chat-apiKeyAuth (API Key) and /chat-tokenAuth (Firebase Token). Both expose the same endpoints.
| Method | Endpoint | Description |
|---|---|---|
| POST | /chat-apiKeyAuth/chat | Send a message and receive a complete response |
| POST | /chat-apiKeyAuth/stream | Send a message and stream the response (SSE) |
| POST | /chat-tokenAuth/chat | Chat with Firebase Token auth |
| POST | /chat-tokenAuth/stream | Stream with Firebase Token auth |
📄 Documents & Files
| Method | Endpoint | Description |
|---|---|---|
| POST | /upload | Upload a document and generate embeddings |
| GET | /documents | List all user documents |
| GET | /documents/:id/vector-metadata | Get Qdrant vector metadata for a document |
| GET | /files | List user files |
| DELETE | /files/:fileId | Delete a file |
| GET | /files/stats | Storage usage statistics |
🗄️ Storage
| Method | Endpoint | Description |
|---|---|---|
| POST | /storage-tokenAuth/getPresignedUrl | Get pre-signed S3 URL for direct upload |
| POST | /storage-tokenAuth/getDownloadUrl | Get pre-signed S3 URL for download |
| POST | /vectorStorage-tokenAuth/storeEmbeddings | Store embeddings in Qdrant |
| DELETE | /vectorStorage-tokenAuth/deleteEmbeddings | Delete embeddings from Qdrant |
| POST | /firebase-storage/generate-upload-url | Get signed Firebase Storage upload URL |
🧠 Knowledge Base
| Method | Endpoint | Description |
|---|---|---|
| GET | /knowledge-base/stats | Knowledge base statistics |
| GET | /knowledge-base/entries | List entries with filters |
| GET | /knowledge-base/entries/:id | Get entry by ID |
| PATCH | /knowledge-base/entries/:id | Update an entry |
| DELETE | /knowledge-base/entries/:id | Delete from Firestore + Qdrant |
| POST | /knowledge-base/ingest/url | Ingest content from URL(s) |
| POST | /knowledge-base/ingest/github | Ingest from GitHub repository |
| POST | /knowledge-base/ingest/text | Ingest plain text |
| POST | /knowledge-base/ingest/image | Ingest an image |
| POST | /knowledge-base/ingest/document | Ingest an uploaded document |
| GET | /knowledge-base/chunks | Explore vector chunks |
| POST | /knowledge-base/search | Semantic search in the KB |
🤖 AI Model Provider
| Method | Endpoint | Description |
|---|---|---|
| GET | /model-provider/config | Get current AI provider configuration |
| POST | /model-provider/config | Update provider configuration |
| POST | /model-provider/test | Test connection to AI provider |
| GET | /model-provider/local/models | List available local models |
| POST | /model-provider/test-embedding | Test embedding generation |
| GET | /model-provider/defaults | Get provider defaults and dimensions |
📊 Usage & Billing
| Method | Endpoint | Description |
|---|---|---|
| GET | /usage/current | Current usage for the user |
| GET | /usage/analytics | Usage analytics |
| GET | /usage/summary | Dashboard usage summary |
| GET | /usage/plans | Available subscription plans |
| POST | /usage/upgrade/initiate | Start a plan upgrade |
| GET | /billing/status | Billing status and token usage |
| GET | /billing/invoices | User invoices |
| GET | /billing/payment-methods | Payment methods on file |
| POST | /billing/checkout | Create checkout for upgrade (LemonSqueezy) |
| POST | /billing/recharge-tokens | Create checkout to recharge tokens |
| POST | /billing/voucher/validate | Validate a voucher code |
| POST | /billing/webhook/lemonsqueezy | LemonSqueezy webhook (direct) |
🏢 Organizations
Base path: /firestore-tokenAuth/organizations
| Method | Endpoint | Description |
|---|---|---|
| POST | /.../organizations | Create organization |
| GET | /.../organizations | List all organizations |
| GET | /.../organizations/:orgId | Get organization by ID |
| PUT | /.../organizations/:orgId | Update organization |
| DELETE | /.../organizations/:orgId | Delete organization |
| POST | /.../organizations/:orgId/members | Add member |
| PUT | /.../organizations/:orgId/members/:memberId/role | Change member role |
🤖 Assistants & Workflows
Commands-first API. Use /assistants/commands for external integrations and automation.
| Method | Endpoint | Description |
|---|---|---|
| GET | /assistants/ | List user's assistants |
| POST | /assistants/ | Create assistant (legacy path, still supported) |
| PUT | /assistants/:assistantId | Update assistant (legacy path) |
| PATCH | /assistants/:assistantId | Patch assistant (legacy path) |
| PUT | /assistants/:assistantId/workflow | Assign workflow to assistant |
| DELETE | /assistants/:assistantId/workflow | Remove workflow from assistant |
| POST | /assistants/commands | Unified commands endpoint for assistants/workflows/tasks |
| GET | /assistants/commands/audit | Read command execution audit logs |
| GET | /workflows/ | List workflows |
| POST | /workflows/ | Create workflow |
| PUT | /workflows/:workflowId | Update workflow |
| DELETE | /workflows/:workflowId | Delete workflow |
| POST | /workflows/test-draft | Test workflow draft |
| POST | /workflows/:workflowId/duplicate | Duplicate workflow |
| GET | /workflows/:workflowId/analytics | Workflow analytics |
🚦 Plan Limits & 429 Behavior
Assistant, workflow, and task creation now passes through usage tracking and enforces plan limits on both commands and legacy create endpoints.
| Method | Endpoint | Description |
|---|---|---|
| POST | /assistants/commands | Returns 429 when assistants/workflows/tasks plan limit is reached |
| POST | /assistants/ | Legacy assistant create also enforces plan limits |
| POST | /workflows/ | Legacy workflow create also enforces plan limits |
| POST | /tasks/ | Legacy task create also enforces plan limits |
| GET | /usage/current | Inspect current counters and limits for your plan |
🛠️ Tools
| Method | Endpoint | Description |
|---|---|---|
| GET | /tools/ | List all registered tools |
| GET | /tools/categories | Tools by category |
| GET | /tools/available | Tools available in user context |
| POST | /tools/result | Submit tool execution result (from frontend) |
| GET | /tools/pending/:threadId | Pending tool executions for a thread |
| PATCH | /tools/:name/toggle | Enable/disable a tool |
📱 Messaging Platforms
| Method | Endpoint | Description |
|---|---|---|
| POST | /platforms/connect | Connect a platform |
| POST | /platforms/disconnect | Disconnect a platform |
| GET | /platforms/status | Health status of connected platforms |
| GET | /platforms/list | List connected platforms |
| POST | /platforms/send-message | Send a message via a platform |
| POST | /platforms/broadcast | Broadcast to all contacts |
| POST | /platforms/web-widget/create | Create web chat widget |
| GET | /platforms/web-widget/list | List web widgets |
💬 WhatsApp Business
Base path: /platforms/whatsapp
| Method | Endpoint | Description |
|---|---|---|
| POST | /.../connect | Connect WhatsApp Business account |
| GET | /.../list | List WhatsApp connections |
| DELETE | .../:connectionId | Disconnect account |
| GET | .../:connectionId/conversations | List conversations |
| GET | .../:connectionId/conversations/:convId/messages | Get messages in a conversation |
| POST | .../:connectionId/send | Send a WhatsApp message |
| GET | .../:connectionId/contacts | View contacts |
🔌 REST API Connections
| Method | Endpoint | Description |
|---|---|---|
| POST | /rest-api-connections/ | Create a connection |
| GET | /rest-api-connections/ | List connections |
| PUT | /rest-api-connections/:id | Update connection |
| POST | /rest-api-connections/:id/execute | Execute outgoing API call |
| POST | /rest-api-connections/:id/test | Test the connection |
| GET | /rest-api-connections/:id/logs | View execution logs |
| ALL | /api/gateway/:slug | Inbound API gateway — routes by slug |