Core Modules

AI Assistants

AI Assistants are the core unit of CognitionDesk. Each assistant has a configurable system prompt, model provider, knowledge base, and optional LangGraph workflow — enabling anything from simple FAQ bots to complex multi-step agents.

Configuration

Assistants can be configured in the dashboard or fully managed via code using the commands endpoint.

Name & System Prompt — the assistant's identity and instructions
Model Provider — OpenAI, Anthropic, Google, or a local model
Knowledge Base — enable RAG retrieval from your ingested content
Workflow — attach a LangGraph workflow for tool-enabled agentic behavior
Platform Connections — link to WhatsApp, Messenger, Telegram, or web widgets

Plan limit enforcement

Assistant, workflow, and task creation are usage-tracked and plan-limited. When a plan cap is reached, create operations return 429 on both commands and legacy create endpoints.

Supported AI Providers

Provider	Available Models	Package
OpenAI	gpt-4o, gpt-4o-mini, gpt-3.5-turbo, ...	`@langchain/openai`
Anthropic	claude-opus-4, claude-sonnet-4-6, claude-haiku-4-5, ...	`@langchain/anthropic`
Google	gemini-2.0-flash, gemini-1.5-pro, ...	`@langchain/google-genai`
Local (Ollama)	llama3, mistral, ...	`langchain/ollama`

Create via commands

JSON

// Commands-first assistant creation (recommended)
POST /assistants/commands
Authorization: Bearer <token>
Content-Type: application/json

{
  "command": "assistants.create",
  "params": {
    "assistantData": {
      "name": "Support Bot",
      "model": "gpt-4o-mini",
      "description": "Handles customer support questions",
      "systemPrompt": "You are a concise and empathetic support assistant.",
      "temperature": 0.5,
      "maxTokens": 4096,
      "category": "support",
      "useRAG": true,
      "ragSettings": {
        "enabled": true,
        "indexName": "default",
        "maxDocuments": 8,
        "similarityThreshold": 0.65,
        "scope": "organization"
      },
      "useInventory": true,
      "inventorySettings": {
        "enabled": true,
        "allowSearch": true,
        "maxResults": 8,
        "promotionLevel": "balanced"
      },
      "features": {
        "webSearch": false,
        "codeExecution": false,
        "imageGeneration": false,
        "fileUpload": true
      },
      "workflowId": null,
      "workflowEnabled": false,
      "enabledTools": ["search_knowledge_base", "list_tasks"],
      "disabledTools": ["send_email"],
      "customToolIds": [],
      "skills": [],
      "enablePlatformContext": true,
      "appearance": { "style": "compact" },
      "theme": { "mode": "light", "primaryColor": "#3B82F6" },
      "welcomeMessage": "Hi! How can I help today?",
      "responseStyle": "concise",
      "tags": ["support", "tier-1"],
      "version": "1.0.0"
    }
  }
}

Patch/update via commands

JSON

// Partial updates with assistants.patch
POST /assistants/commands
Authorization: Bearer <token>
Content-Type: application/json

{
  "command": "assistants.patch",
  "params": {
    "assistantId": "asst_abc123",
    "updates": {
      "temperature": 0.3,
      "workflowId": "wf_xyz789",
      "workflowEnabled": true,
      "tags": ["support", "priority"]
    }
  }
}

Customization fields

Field	Type	Required	Notes
name	string	yes	Assistant display name
model	string	yes	LLM identifier (for example gpt-4o-mini)
description	string	no	Human-readable description
systemPrompt	string	no	Primary instruction prompt
temperature	number	no	0 to 2
maxTokens	integer	no	Output token cap
avatar	string	no	Emoji or URL-like string
category	string	no	Business category label
knowledgeBaseEnabled	boolean	no	Legacy compatibility flag
useRAG	boolean	no	Enable retrieval-augmented generation
ragSettings	object	no	enabled, indexName, maxDocuments, similarityThreshold, scope
useInventory	boolean	no	Enable inventory-aware responses
inventorySettings	object	no	enabled, allowSearch, maxResults, promotionLevel
features	object	no	webSearch, codeExecution, imageGeneration, fileUpload
workflowId	string\|null	no	Assigned workflow id
workflowEnabled	boolean	no	Turns workflow execution on/off
enabledTools	string[]	no	Tool names allowed by this assistant
disabledTools	string[]	no	Tool names explicitly blocked
customToolIds	string[]	no	IDs of custom tools
skills	object[]	no	Skill objects with custom metadata
enablePlatformContext	boolean	no	Inject platform channel context
appearance	object	no	Assistant presentation options
theme	string\|object	no	Theme mode or rich theme object
welcomeMessage	string	no	Initial user-facing message
responseStyle	string	no	Style preset such as concise
tags	string[]	no	Search and categorization tags
version	string\|number	no	Client-managed assistant version label
sharing	object	no	isPublic and sharedWith[] for access control

Using an assistant in chat

After creation, use assistantId in chat requests:

HTTP

POST /chat-apiKeyAuth/chat
x-api-key: <api-key>
Content-Type: application/json

{
  "assistantId": "asst_abc123",
  "message": "Hello!"
}

Listing assistants

HTTP

GET /assistants/
Authorization: Bearer <token>

// Response
{
  "assistants": [
    {
      "id": "asst_abc123",
      "name": "Support Bot",
      "model": "gpt-4o",
      "systemPrompt": "You are a helpful support agent...",
      "knowledgeBaseEnabled": true,
      "workflowId": null,
      "createdAt": "2026-01-10T08:00:00Z"
    }
  ]
}

Attaching workflows

Workflows add agentic capabilities — the assistant can call tools, make decisions, and run multi-step processes:

HTTP

// Workflow assignment helper command
POST /assistants/commands
Authorization: Bearer <token>

{
  "command": "assistants.assignWorkflow",
  "params": {
    "assistantId": "asst_abc123",
    "workflowId": "wf_xyz789",
    "workflowEnabled": true
  }
}

Platform connections

Connect an assistant to messaging platforms so it automatically responds to incoming messages. See the WhatsApp and Messaging Platforms guides.

Endpoints

Method	Endpoint	Auth	Description
GET	`/assistants/`	Firebase Token	List all user's assistants
POST	`/assistants/commands`	Firebase Token	Unified commands endpoint (recommended for external apps)
GET	`/assistants/commands/audit`	Token (admin/scopes)	Read command execution audit logs
POST	`/assistants/`	Firebase Token	Legacy assistant create endpoint (limit-enforced)
PATCH	`/assistants/:assistantId`	Firebase Token	Legacy assistant patch endpoint
PUT	`/assistants/:assistantId/workflow`	Firebase Token	Assign a LangGraph workflow to an assistant
DELETE	`/assistants/:assistantId/workflow`	Firebase Token	Remove workflow from an assistant
GET	`/platforms/assistants/list`	Firebase Token	List assistants available for platform connections