> ## 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. # Update Chat > Update mutable fields (title, systemPrompt, metadata) of a chat. ## OpenAPI ````yaml patch /v1/chats/{chat_id} 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/{chat_id}: patch: tags: - Chats summary: Update Chat description: Update mutable fields (title, systemPrompt, metadata) of a chat. operationId: updateChat parameters: - name: chat_id in: path required: true schema: type: string description: Chat ID examples: - chat_abc123 title: Chat Id description: Chat ID - name: Idempotency-Key in: header required: false schema: anyOf: - type: string - type: 'null' title: Idempotency-Key requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatUpdate' responses: '200': description: Updated chat returned content: application/json: schema: $ref: '#/components/schemas/ChatOut' examples: updated_chat: value: id: a4f0c0a2-4b1d-4e57-8a2a-0c18f9d4b1e2 organizationId: org_abc123 title: Quarterly Planning modelId: 84d6f2f1-27a5-4b5c-8a53-e2f7f1f5b0a3 systemPrompt: You are a project planning assistant. metadata: priority: high createdAt: '2025-09-01T10:00:00Z' updatedAt: '2025-09-01T10:05:00Z' createdBy: member_xyz789 visibility: private documentsCount: 0 messages: [] '404': description: Chat not found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: ChatUpdate: properties: title: anyOf: - type: string maxLength: 500 - type: 'null' title: Title description: Updated chat title examples: - Updated Support Chat systemPrompt: anyOf: - type: string - type: 'null' title: Systemprompt description: System-level instructions for the AI model. examples: - You are a helpful assistant. metadata: anyOf: - type: object - type: 'null' format: json title: Metadata description: Updated metadata examples: - priority: high type: object title: ChatUpdate description: Request schema for updating a chat. ChatOut: properties: createdAt: type: string format: date-time title: Createdat description: Timestamp when the resource was created examples: - '2024-01-15T10:30:00Z' updatedAt: type: string format: date-time title: Updatedat description: Timestamp when the resource was last updated examples: - '2024-01-15T14:45:00Z' organizationId: type: string maxLength: 64 minLength: 1 title: Organizationid description: Organization ID for tenant isolation examples: - org_abc123 title: anyOf: - type: string maxLength: 500 - type: 'null' title: Title description: Chat title examples: - Product Support Chat systemPrompt: anyOf: - type: string - type: 'null' title: Systemprompt description: System-level instructions for the AI model. examples: - You are a helpful customer support assistant. metadata: anyOf: - type: object - type: 'null' format: json title: Metadata description: Custom metadata for the chat examples: - department: support priority: high id: type: string title: Id description: Unique chat identifier examples: - chat_abc123 status: anyOf: - type: string enum: - generating - error - type: 'null' title: Status description: >- Operational status of the chat. 'generating' indicates a background stream is actively running (poll again). 'error' indicates the last stream was interrupted or failed. null indicates the chat is in a normal, idle state. examples: - generating - error lastError: anyOf: - type: string - type: 'null' title: Lasterror description: Human-readable description of the last error, if status is 'error'. examples: - Stream interrupted (client disconnect or network error) lastErrorAt: anyOf: - type: string format: date-time - type: 'null' title: Lasterrorat description: Timestamp of the last error, if status is 'error'. modelId: type: string title: Modelid description: Identifier of the AI model used for this chat. examples: - model_large-model model: anyOf: - $ref: '#/components/schemas/ModelOut' - type: 'null' description: Full model object (included when expanded with ?expand[]=model) messages: items: $ref: '#/components/schemas/MessageOut' type: array title: Messages description: Messages in this chat documentsCount: type: integer minimum: 0 title: Documentscount description: Total number of documents associated with the chat. default: 0 examples: - 3 createdBy: type: string title: Createdby description: ID of the user who created this chat examples: - user_xyz789 visibility: type: string enum: - private - organization - shared title: Visibility description: Chat visibility level default: private examples: - private sharedWith: anyOf: - items: type: string type: array - type: 'null' title: Sharedwith description: List of user IDs this chat is shared with examples: - - user_123 - user_456 deletedAt: anyOf: - type: string format: date-time - type: 'null' title: Deletedat description: Timestamp when the chat was soft-deleted deletedBy: anyOf: - type: string - type: 'null' title: Deletedby description: ID of the user who deleted this chat source: type: string title: Source description: 'Request origin: api, m2m, connector' default: api sourceDetail: anyOf: - type: string - type: 'null' title: Sourcedetail description: 'Specific source: dashboard, slack, google_drive, etc.' ephemeral: type: boolean title: Ephemeral description: >- When true the chat has a finite TTL and will be automatically deleted once ephemeral_expires_at is reached. default: false ephemeralExpiresAt: anyOf: - type: string format: date-time - type: 'null' title: Ephemeralexpiresat description: >- UTC timestamp at which this ephemeral chat will be auto-deleted. Null for non-ephemeral chats. type: object required: - createdAt - updatedAt - organizationId - id - modelId - createdBy title: ChatOut description: Chat response with full details. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ModelOut: properties: id: type: string title: Id description: Unique identifier for the model examples: - 550e8400-e29b-41d4-a716-446655440000 displayName: type: string title: Displayname description: Human-readable display name examples: - large-model Omni - reasoning-model 3.5 Sonnet description: anyOf: - type: string - type: 'null' title: Description description: Model description examples: - Advanced language model for complex tasks - Fast model for simple queries provider: anyOf: - type: string - type: 'null' title: Provider description: AI provider name (NULL for user models, inherited from parent) examples: - provider-a - provider-b modelName: anyOf: - type: string - type: 'null' title: Modelname description: >- Provider-specific model identifier (NULL for user models, inherited from parent) examples: - large-modelo - reasoning-model-3-5-sonnet contextWindow: type: integer title: Contextwindow description: Model's context window size in tokens examples: - 4096 - 128000 maxTokensPerRequest: anyOf: - type: integer - type: 'null' title: Maxtokensperrequest description: Maximum tokens per request examples: - 4096 - 8192 supportsStreaming: type: boolean title: Supportsstreaming description: Whether the model supports streaming examples: - true supportsTools: type: boolean title: Supportstools description: Whether the model supports tool/function calling default: false examples: - true - false supportsVision: type: boolean title: Supportsvision description: Whether the model supports vision/image inputs default: false examples: - true - false supportsReasoning: type: boolean title: Supportsreasoning description: >- Whether the model supports reasoning/thinking tokens (AI models extended thinking, o1, AI models thinking) default: false examples: - true - false enabled: type: boolean title: Enabled description: Whether the model is enabled examples: - true isSystemModel: type: boolean title: Issystemmodel description: Whether this is a company-provided base model examples: - true - false creditMultiplier: anyOf: - type: integer - type: 'null' title: Creditmultiplier description: >- Credit multiplier for billing (system models only, user models inherit from parent) examples: - 1 - 2 modelTier: type: string title: Modeltier description: >- Access tier for this model. 'standard' models are available on all plans. 'premium' models require a Pro or Enterprise subscription. default: standard examples: - standard - premium lifecycleState: type: string enum: - active - disabled - deprecated - end_of_life title: Lifecyclestate description: >- Current lifecycle state of the model. 'active': normal operation. 'disabled': temporarily disabled by admin. 'deprecated': end-of-life date is scheduled (see endOfLifeAt). 'end_of_life': model has been retired and should no longer be used. default: active examples: - active - deprecated - end_of_life endOfLifeAt: anyOf: - type: string format: date-time - type: 'null' title: Endoflifeat description: >- Scheduled end-of-life date for this model. When set and in the future, the model is deprecated. When in the past, the model has reached end of life. Null means the model has no scheduled retirement. examples: - '2026-06-01T00:00:00Z' deprecationMessage: anyOf: - type: string - type: 'null' title: Deprecationmessage description: >- User-facing deprecation notice. Typically includes a reason and a suggested replacement model. Only present when lifecycleState is 'deprecated' or 'end_of_life'. examples: - >- This model is scheduled for retirement on 2026-06-01. Please migrate to large-modelo. replacementModelId: anyOf: - type: string - type: 'null' title: Replacementmodelid description: >- ID of the suggested replacement model when this model is deprecated or end-of-life. Use this to guide users toward a migration path. Null when no replacement is designated. examples: - 660e8400-e29b-41d4-a716-446655440001 isRecommended: type: boolean title: Isrecommended description: >- Whether this model is recommended for new configurations. Curated by Cuadra — typically the best balance of capability, speed, and cost for each provider. default: false examples: - true - false metadata: anyOf: - type: object - type: 'null' format: json title: Metadata description: Additional model metadata examples: - department: support createdAt: type: string format: date-time title: Createdat description: When the model was created examples: - '2025-09-08T06:33:19Z' updatedAt: type: string format: date-time title: Updatedat description: When the model was last updated examples: - '2025-09-08T06:33:19Z' parentModelId: anyOf: - type: string - type: 'null' title: Parentmodelid description: ID of the parent system model (for user models) examples: - 550e8400-e29b-41d4-a716-446655440001 systemPromptId: anyOf: - type: string - type: 'null' title: Systempromptid description: ID of the system prompt composition assigned to this model examples: - 550e8400-e29b-41d4-a716-446655440002 systemPrompt: anyOf: - type: string - type: 'null' title: Systemprompt description: Full system prompt override (if set, bypasses particle composition) examples: - You are a helpful assistant. type: object required: - id - displayName - contextWindow - supportsStreaming - enabled - isSystemModel - createdAt - updatedAt title: ModelOut description: Schema for AI model response data. example: contextWindow: 128000 createdAt: '2025-09-08T06:33:19Z' creditMultiplier: 2 description: Advanced language model for complex tasks displayName: large-model Omni enabled: true id: 550e8400-e29b-41d4-a716-446655440000 isRecommended: true isSystemModel: false lifecycleState: active maxTokensPerRequest: 4096 metadata: {} modelName: large-modelo provider: provider-a supportsStreaming: true updatedAt: '2025-09-08T06:33:19Z' 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. 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 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. 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 ````