> ## Documentation Index > Fetch the complete documentation index at: https://docs.cuadra.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create or Continue Chat > Generate a chat completion. **Streaming (`stream: true`):** Returns an SSE stream. The LLM call runs in a background task that is decoupled from the HTTP connection — if the client disconnects mid-stream (tab close, navigation, network drop) the model continues generating and the assistant message + artifacts are persisted once it finishes. Poll `GET /v1/chats/{id}` to check completion status. **Non-streaming (`stream: false`):** Returns a single JSON response after the model finishes generating. **Extended thinking:** Models that support reasoning (e.g. `AI models-opus-4-6`) emit `reasoning-start` / `reasoning-delta` / `reasoning-end` SSE events before the text response. These events can take 60-120 seconds; keep the connection open and display a thinking indicator while they arrive. ## OpenAPI ````yaml post /v1/chats openapi: 3.1.0 info: title: Cuadra AI API description: >- REST API for AI-powered chat, RAG, and multi-channel messaging. Full documentation at https://docs.cuadra.ai version: 1.0.0 contact: name: Cuadra AI Support url: https://cuadra.ai/support email: support@cuadra.ai license: name: Proprietary url: https://cuadra.ai/terms termsOfService: https://cuadra.ai/terms servers: - url: https://api.cuadra.ai description: Production security: - bearerAuth: [] - oauth2: [] tags: - name: Health description: >- System health monitoring and readiness checks. Essential for load balancers and deployment automation. - name: Models description: >- Manage custom AI model configurations derived from base models. Create, update, and delete with flexible pricing and token limits. - name: Chats description: >- Interact with AI models for intelligent chat completions. Supports streaming and non-streaming modes with message history. - name: Files description: >- Manage file uploads for chat attachments and dataset knowledge bases. Supports automatic processing, chunking, and embedding for RAG. - name: Datasets description: >- Manage RAG knowledge base datasets with versioning and semantic search. Organize uploaded files into searchable knowledge bases. - name: Particles description: >- Manage reusable system prompt particles for AI model behavior. Particles are modular components (role, tone, guardrails, constraints, format) that compose into system prompts. - name: System Prompts description: >- Compose particles into complete system prompts for AI models. System prompts define model behavior through ordered particle compositions with support for version pinning and token budget validation. - name: Usage description: >- Monitor and analyze API usage with detailed token counting. Track usage across models, tenants, and time periods. - name: Artifacts description: >- Manage rich content artifacts generated during chat conversations. Supports markdown, code, HTML, SVG, and Mermaid diagrams. paths: /v1/chats: post: tags: - Chats summary: Create or Continue Chat description: >- Generate a chat completion with persistent storage. ## Message Formats Accepts both standard message format and AI SDK UIMessage format: **Standard format:** ```json {"role": "user", "content": "Hello"} ``` **AI SDK UIMessage format:** ```json {"role": "user", "parts": [{"type": "text", "text": "Hello"}]} ``` UIMessage format is automatically converted during validation. ## Streaming Formats When `stream=true`, two response formats are available: **Default format:** ``` data: {"id":"...","delta":"Hello","finished":false} data: {"id":"...","delta":" world","finished":false} data: {"id":"...","delta":"","finished":true,"usage":{...}} data: [DONE] ``` **AI SDK format** (set `X-Stream-Format: ai-sdk` header): ``` data: {"type":"start","messageId":"..."} data: {"type":"text-delta","id":"...","delta":"Hello"} data: {"type":"finish","usage":{"promptTokens":10,"completionTokens":5}} data: [DONE] ``` The AI SDK format includes response header `x-vercel-ai-ui-message-stream: v1`. ## AI SDK Protocol Parts When using AI SDK format, the following event types are emitted: - **start**: Message metadata with messageId - **start-step**: Beginning of an LLM step - **source-document**: RAG source references (emitted before text content) - **text-start/delta/end**: Text content streaming - **reasoning-start/delta/end**: Reasoning content (for supported models) - **tool-input-start/delta/available**: Tool call streaming - **finish-step**: End of an LLM step - **finish**: Message completion with usage stats - **error**: Error information - **[DONE]**: Stream termination ## RAG Sources When RAG is enabled for the model, source references are included: **Non-streaming response:** ```json { "id": "chat_abc123", "message": {...}, "sources": [ {"sourceId": "src_0", "filename": "document.pdf", "score": 0.95, "chunkId": "...", "datasetId": "..."} ], "usage": {...} } ``` **Streaming response (default format):** Sources are included in the first chunk only: ```json {"id":"...","delta":"","sources":[{"sourceId":"src_0","filename":"doc.pdf","score":0.95,...}],"finished":false} {"id":"...","delta":"Based on the document...","finished":false} ``` **AI SDK format:** ```json {"type":"source-document","sourceId":"src_0","mediaType":"text/plain","title":"document.pdf"} {"type":"text-delta","id":"...","delta":"Based on the document..."} ``` ## Reasoning (Extended Thinking) For models that support extended thinking (AI models, o1, AI models 2.0+), reasoning tokens are streamed: **Default format:** ```json {"id":"...","reasoning":"Let me analyze...","delta":"","finished":false} {"id":"...","reasoning":"","delta":"The answer is...","finished":false} ``` **AI SDK format:** ```json {"type":"reasoning-start","id":"block_123"} {"type":"reasoning-delta","id":"block_123","delta":"Let me analyze..."} {"type":"reasoning-end","id":"block_123"} {"type":"text-start","id":"block_456"} {"type":"text-delta","id":"block_456","delta":"The answer is..."} ``` operationId: createOrContinueChat parameters: - name: X-Stream-Format in: header required: false description: >- Stream format for SSE responses. Set to `ai-sdk` to enable Vercel AI SDK UI Message Stream Protocol compatibility. When enabled, response includes `x-vercel-ai-ui-message-stream: v1` header. schema: type: string enum: - ai-sdk example: ai-sdk requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatRequest' responses: '200': description: >- Server-Sent Events stream of chat completion chunks (when stream=true). Each SSE event has the format: `data: \n\n` where `` matches the StreamingChatResponse schema. The final event has `finished: true` and includes `usage` stats. A `data: [DONE]\n\n` event is sent after the last chunk. content: text/event-stream: schema: type: object required: - id properties: id: type: string description: Chat ID delta: type: string description: Text content delta default: '' reasoning: type: string description: Reasoning/thinking content delta default: '' toolCalls: description: Tool call deltas (accumulated by client) anyOf: - type: array items: type: object properties: index: type: integer minimum: 0 description: Index of the tool call being built id: type: string description: Tool call ID (first chunk only) type: type: string enum: - function description: Tool type function: type: object additionalProperties: type: string description: >- Partial function data (name and/or arguments delta) required: - index - type: 'null' sources: description: RAG sources used for this response (sent once at start) anyOf: - items: $ref: '#/components/schemas/SourceOut' type: array - type: 'null' finished: type: boolean default: false usage: anyOf: - type: object properties: inputTokens: type: integer minimum: 0 description: Number of input tokens outputTokens: type: integer minimum: 0 description: Number of output tokens totalTokens: type: integer minimum: 0 description: Total tokens (input + output) cost: type: string description: Cost in USD required: - inputTokens - outputTokens - totalTokens - type: 'null' additionalProperties: false headers: X-Request-Id: description: Unique identifier for request tracing and debugging schema: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 X-RateLimit-Limit: description: Total number of requests allowed per time window schema: type: integer minimum: 1 example: 1000 X-RateLimit-Remaining: description: Number of requests remaining in current time window schema: type: integer minimum: 0 example: 999 X-RateLimit-Reset: description: Unix timestamp when rate limit window resets schema: type: integer format: int64 example: 1694102400 x-vercel-ai-ui-message-stream: description: | Present when `X-Stream-Format: ai-sdk` header is set. Indicates Vercel AI SDK UI Message Stream Protocol version. schema: type: string enum: - v1 example: v1 '201': description: Chat completion response (when stream=false) content: application/json: schema: $ref: '#/components/schemas/ChatResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' x-codeSamples: - lang: cURL label: Basic request source: | curl -X POST "https://api.cuadra.ai/v1/chats" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "modelId": "84d6f2f1-27a5-4b5c-8a53-e2f7f1f5b0a3", "messages": [ { "role": "user", "content": "Hello!" } ] }' - lang: TypeScript label: Fetch source: | const res = await fetch('https://api.cuadra.ai/v1/chats', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ modelId: '84d6f2f1-27a5-4b5c-8a53-e2f7f1f5b0a3', messages: [{ role: 'user', content: 'Hello!' }] }) }); const data = await res.json(); - lang: Python label: requests source: | import requests resp = requests.post( 'https://api.cuadra.ai/v1/chats', headers={ 'Authorization': f'Bearer {TOKEN}', 'Content-Type': 'application/json' }, json={ 'modelId': '84d6f2f1-27a5-4b5c-8a53-e2f7f1f5b0a3', 'messages': [ { 'role': 'user', 'content': 'Hello!' } ] } ) print(resp.json()) components: schemas: ChatRequest: properties: messages: items: $ref: '#/components/schemas/MessageCreate' type: array minItems: 1 title: Messages description: Messages to send to the model chatId: anyOf: - type: string - type: 'null' title: Chatid description: Existing chat ID to continue conversation examples: - chat_abc123 modelId: anyOf: - type: string - type: 'null' title: Modelid description: >- Identifier of the AI model for this request. If omitted and chatId is provided, the chat's existing model is used. Must match a model 'id' from the /v1/models API. system_prompt: anyOf: - type: string - type: 'null' title: System Prompt description: System-level instructions for the AI model. ephemeral: type: boolean title: Ephemeral description: >- Create temporary chat for testing. Ephemeral chats are automatically deleted. default: false examples: - false stream: type: boolean title: Stream description: Enable streaming response default: false examples: - true maxTokens: anyOf: - type: integer maximum: 32000 minimum: 1 - type: 'null' title: Maxtokens description: Maximum number of tokens to generate for this response examples: - 128 - 256 - 512 temperature: anyOf: - type: number maximum: 2 minimum: 0 - type: 'null' format: float title: Temperature description: >- Controls randomness of the output. Lower values (e.g., 0.0-0.3) are more deterministic; higher values (e.g., 0.7-1.0+) increase creativity. Provider defaults vary; typical range is 0.0 to 2.0. examples: - 0 - 0.2 - 0.7 - 1 responseFormat: anyOf: - type: object - type: 'null' title: Responseformat description: >- Structured output format specification (AI models-compatible json_schema format). Enforces the AI response to match the specified JSON schema. examples: - json_schema: name: response schema: additionalProperties: false properties: summary: type: string confidence: maximum: 1 minimum: 0 type: number required: - summary type: object strict: true type: json_schema enableReasoning: type: boolean title: Enablereasoning description: >- Enable reasoning/thinking tokens for supported models. When enabled, the model will expose its thinking process in the response. Supported by: AI models (extended thinking), AI models o1/o3, AI models thinking models. Note: Reasoning tokens are billed separately and may significantly increase costs. default: false examples: - true - false reasoningBudget: anyOf: - type: integer maximum: 128000 minimum: 1000 - type: 'null' title: Reasoningbudget description: >- Maximum tokens for reasoning/thinking (only used when enableReasoning=true). Higher budgets allow deeper reasoning but increase latency and cost. Default: 10000 for AI models, varies by provider. examples: - 10000 - 20000 tools: anyOf: - items: $ref: '#/components/schemas/ToolSchema' type: array - type: 'null' title: Tools description: >- List of tools the model may call. Pass-through to AI provider. Tools are defined and executed by the client, not the server. examples: - - function: description: Get current weather for a location name: get_weather parameters: properties: location: type: string unit: enum: - celsius - fahrenheit type: string required: - location type: object type: function toolChoice: anyOf: - type: string - type: object - type: 'null' title: Toolchoice description: >- Controls tool selection. Options: 'auto' (model decides), 'none' (no tools), 'required' (must use a tool), or specific tool object. examples: - auto - none - required parallelToolCalls: anyOf: - type: boolean - type: 'null' title: Paralleltoolcalls description: >- Whether to allow parallel tool calls (AI models-specific, default true) enableArtifacts: type: boolean title: Enableartifacts description: >- Enable artifact creation. When enabled, the AI can create standalone documents (reports, code files, HTML pages, diagrams) that appear in a side panel. Requires stream=true. Artifact tools are injected server-side. default: false examples: - false - true fetchUrls: type: boolean title: Fetchurls description: >- When enabled, URLs in user messages are automatically fetched and their content is provided to the AI as context. Enables 'summarize this article' or 'what does this page say' use cases. If a URL cannot be fetched (e.g., too large, blocked, or inaccessible), the error is communicated so the AI can inform the user. default: true examples: - true - false fileIds: anyOf: - items: type: string type: array - type: 'null' title: Fileids description: >- File IDs to associate with this chat before processing. Use when the frontend uploads files first then creates/sends a chat message. Files are associated with the chat (creating vectors if needed) and included in RAG context. If vectors are not ready yet, extracted text is used as fallback context. examples: - - 7aa0316a-0a56-4c11-8d37-45f5cf40febd useVlmRag: anyOf: - type: boolean - type: 'null' title: Usevlmrag description: >- Control whether original images are fetched from storage and attached to the LLM prompt for image_ocr RAG chunks. null (default) — server decides: enabled when the model supports vision and RAG_IMAGE_ATTACHMENT_ENABLED is true. true — force on for this request (model must support vision). false — disable for this request regardless of server defaults. Image tokens are billed as part of the normal input token charge. examples: - null - true - false type: object required: - messages title: ChatRequest description: Request schema for chat completions. examples: - max_tokens: 500 messages: - content: What are the key features of your product? role: user modelId: model-large-model-custom temperature: 0.7 - max_tokens: 300 messages: - content: You are a helpful customer support assistant. role: system - content: How do I reset my password? role: user modelId: model-reasoning-model-support temperature: 0.5 - chatId: chat-existing-123 max_tokens: 500 messages: - content: Can you elaborate on the pricing? role: user modelId: model-large-model-custom - max_tokens: 2000 messages: - content: Summarize this legal document... role: user modelId: model-reasoning-model-legal stream: true temperature: 0.3 SourceOut: properties: sourceId: type: string title: Sourceid description: Unique identifier for the source filename: type: string title: Filename description: Source filename score: type: number maximum: 1 minimum: 0 title: Score description: Relevance score (0-1) chunkId: anyOf: - type: string - type: 'null' title: Chunkid description: ID of the specific chunk datasetId: anyOf: - type: string - type: 'null' title: Datasetid description: Dataset containing the source contentType: anyOf: - type: string - type: 'null' title: Contenttype description: >- Content type of the retrieved chunk. Possible values: tabular, prose, email, presentation, image_ocr, other. Null for legacy chunks ingested before content-type tagging was introduced. sourceUrl: anyOf: - type: string - type: 'null' title: Sourceurl description: >- Canonical source URL for web connector pages. Present when the chunk originates from a URL synced via the web connector. Null for files uploaded directly or synced from non-web connectors. type: object required: - sourceId - filename - score title: SourceOut description: RAG source reference returned with chat responses. ChatResponse: properties: id: type: string title: Id description: Chat ID examples: - chat_abc123 message: allOf: - $ref: '#/components/schemas/MessageOut' description: The assistant's response message toolCalls: anyOf: - items: $ref: '#/components/schemas/ToolCallOut' type: array - type: 'null' title: Toolcalls description: Tool calls requested by the model (when finish_reason='tool_calls') sources: anyOf: - items: $ref: '#/components/schemas/SourceOut' type: array - type: 'null' title: Sources description: RAG sources used for this response usage: anyOf: - $ref: '#/components/schemas/TokenUsage' - type: 'null' description: Token usage statistics type: object required: - id - message title: ChatResponse description: Response schema for chat completions. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError MessageCreate: properties: role: type: string enum: - user - assistant - system - tool title: Role description: Message role (user, assistant, system, or tool) examples: - user - assistant content: anyOf: - type: string - type: 'null' title: Content description: Message content examples: - What is the weather in San Francisco? toolCallId: anyOf: - type: string - type: 'null' title: Toolcallid description: >- Required for role='tool' - references the tool call being responded to toolCalls: anyOf: - items: $ref: '#/components/schemas/ToolCallOut' type: array - type: 'null' title: Toolcalls description: Tool calls from assistant (role='assistant' only) type: object required: - role title: MessageCreate description: >- Message input for chat requests. Supports both standard format and AI SDK UIMessage format. UIMessage format (with `parts` array) is automatically converted. ToolSchema: properties: type: type: string enum: - function const: function title: Type description: Tool type default: function examples: - function function: allOf: - $ref: '#/components/schemas/ToolFunctionSchema' description: Function definition type: object required: - function title: ToolSchema description: Tool definition (AI models-compatible format). MessageOut: properties: role: type: string enum: - user - assistant - system - tool title: Role description: Message role (user, assistant, system, or tool) examples: - user - assistant content: anyOf: - type: string - type: 'null' title: Content description: Message content examples: - What is the weather in San Francisco? id: type: string title: Id description: Unique message identifier examples: - msg_abc123 chatId: type: string title: Chatid description: ID of the chat this message belongs to examples: - chat_xyz789 tokenCount: anyOf: - type: integer - type: 'null' title: Tokencount description: Number of tokens in this message examples: - 150 cost: anyOf: - type: string - type: 'null' type: string title: Cost description: Cost of this message in USD examples: - '0.0015' responseTimeMs: anyOf: - type: integer - type: 'null' title: Responsetimems description: Response time in milliseconds examples: - 1250 metadata: anyOf: - type: object - type: 'null' title: Metadata description: Additional message metadata examples: - source: api toolCallId: anyOf: - type: string - type: 'null' title: Toolcallid description: 'For role=''tool'': ID of the tool call being responded to' examples: - call_abc123 toolCalls: anyOf: - items: $ref: '#/components/schemas/ToolCallOut' type: array - type: 'null' title: Toolcalls description: 'For role=''assistant'': Tool calls requested by the model' createdAt: type: string format: date-time title: Createdat description: Timestamp when the message was created examples: - '2024-01-15T10:30:00Z' files: anyOf: - items: $ref: '#/components/schemas/MessageFileOut' type: array - type: 'null' title: Files description: Files attached to this message (images, documents) type: object required: - role - id - chatId - createdAt title: MessageOut description: Message response from a chat conversation. ToolCallOut: properties: id: type: string title: Id description: Unique identifier for this tool call examples: - call_abc123 type: type: string enum: - function const: function title: Type description: Tool call type default: function examples: - function function: allOf: - $ref: '#/components/schemas/ToolCallFunctionOut' description: Function call details type: object required: - id - function title: ToolCallOut description: Tool call from AI model response. TokenUsage: properties: inputTokens: type: integer minimum: 0 title: Inputtokens description: Number of input tokens examples: - 150 outputTokens: type: integer minimum: 0 title: Outputtokens description: Number of output tokens examples: - 250 totalTokens: type: integer minimum: 0 title: Totaltokens description: Total tokens (input + output) examples: - 400 cost: anyOf: - type: string - type: 'null' type: string title: Cost description: Cost in USD examples: - '0.0024' type: object required: - inputTokens - outputTokens - totalTokens title: TokenUsage description: Token usage and cost statistics. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError ToolFunctionSchema: properties: name: type: string maxLength: 64 minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ title: Name description: Function name (alphanumeric, underscores, hyphens) examples: - get_weather - search_documents description: anyOf: - type: string maxLength: 1024 - type: 'null' title: Description description: Human-readable function description examples: - Get current weather for a location parameters: anyOf: - type: object - type: 'null' title: Parameters description: JSON Schema for function parameters examples: - properties: location: type: string type: object type: object required: - name title: ToolFunctionSchema description: Function definition for a tool. MessageFileOut: properties: id: type: string title: Id description: File ID examples: - file_abc123 filename: type: string title: Filename description: Original filename examples: - photo.png contentType: anyOf: - type: string - type: 'null' title: Contenttype description: MIME content type examples: - image/png sizeBytes: anyOf: - type: integer - type: 'null' title: Sizebytes description: File size in bytes examples: - 204800 url: anyOf: - type: string - type: 'null' title: Url description: URL to fetch file content examples: - /v1/files/file_abc123/content type: object required: - id - filename title: MessageFileOut description: File attachment metadata for a message. ToolCallFunctionOut: properties: name: type: string title: Name description: Name of the function to call examples: - get_weather arguments: type: string title: Arguments description: JSON string of function arguments examples: - '{"location": "San Francisco", "unit": "celsius"}' type: object required: - name - arguments title: ToolCallFunctionOut description: Function call details in response. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT token from Stytch B2B authentication (magic link, SSO, or M2M) oauth2: type: oauth2 flows: clientCredentials: tokenUrl: https://auth.cuadra.ai/oauth/token scopes: chats:invoke: Invoke chat completions (billable) chats:read: Read and list chats chats:write: Create and update chats chats:delete: Delete chats chats:admin: Full chat access (read/write/delete/invoke) models:read: Read model configurations models:write: Create and update models models:delete: Delete models models:admin: Full access to models (grants read + write + delete) datasets:read: Read and list datasets and snapshots datasets:write: Create and update datasets and snapshots datasets:delete: Delete datasets and snapshots datasets:admin: Full dataset access (read/write/delete) files:read: Read, list, and download files files:write: Upload, associate, and reprocess files files:delete: Delete files (single and bulk) files:admin: Full access to files (grants read + write + delete) particles:read: View particles and particle versions particles:write: Create and update particles particles:delete: Delete particles particles:admin: Full particle access (read/write/delete) system-prompts:read: View system prompts and compositions system-prompts:write: Create and update system prompts system-prompts:delete: Delete system prompts system-prompts:admin: Full system prompt access (read/write/delete) usage:read: Read usage and billing information usage:admin: Full access to usage data (grants read) connections:read: View external connections and sync status connections:write: Create and update external connections connections:delete: Delete connections and sync configurations connections:admin: Full connection access (read/write/delete) channels:read: View channels and channel configuration channels:write: Create and update channels channels:delete: Delete channels and release phone numbers channels:admin: Full channel access (read/write/delete) org:admin: Full resource access, manage members org:owner: 'Owner: all access including billing' chat:write: Delete and manage chats ````