> ## Documentation Index > Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create message > Create a new message in a chat. Returns the user message and a pending assistant message. The assistant response is processed asynchronously. ## OpenAPI ````yaml https://api.getcargo.io/openapi.json post /ai/messages openapi: 3.1.0 info: title: Cargo API version: 1.0.0 description: Cargo Platform API v1 servers: - url: https://api.getcargo.io/v1 description: Cargo API security: - bearerAuth: [] paths: /ai/messages: post: tags: - AI - Messages summary: Create message description: >- Create a new message in a chat. Returns the user message and a pending assistant message. The assistant response is processed asynchronously. requestBody: required: true content: application/json: schema: type: object properties: chatUuid: title: Chat UUID description: >- Chat identifier. When omitted, a new draft chat is created automatically and the message is added to it. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$ agentUuid: title: Agent UUID description: >- Agent identifier for the chat. Only used when chatUuid is omitted and a chat is created automatically. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$ releaseUuid: title: Release UUID description: >- Release identifier for the chat. Only used when chatUuid is omitted and a chat is created automatically. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$ parts: type: array items: {} title: Parts description: Message parts. actions: title: Actions description: Actions available for the message. type: array items: allOf: - type: object properties: name: anyOf: - type: string - type: 'null' slug: type: string description: anyOf: - type: string - type: 'null' isBulkAllowed: type: boolean config: type: object propertyNames: type: string additionalProperties: {} required: - name - slug - description - isBulkAllowed - config - anyOf: - type: object properties: kind: type: string const: tool toolUuid: anyOf: - type: string - type: 'null' templateSlug: anyOf: - type: string - type: 'null' waitUntilFinished: type: boolean required: - kind - toolUuid - templateSlug - waitUntilFinished - type: object properties: kind: type: string const: agent agentUuid: anyOf: - type: string - type: 'null' templateSlug: anyOf: - type: string - type: 'null' waitUntilFinished: type: boolean required: - kind - agentUuid - templateSlug - waitUntilFinished - type: object properties: kind: type: string const: connector integrationSlug: type: string connectorUuid: anyOf: - type: string - type: 'null' actionSlug: type: string required: - kind - integrationSlug - connectorUuid - actionSlug resources: title: Resources description: Resources available for the message. type: array items: anyOf: - type: object properties: kind: type: string const: model name: anyOf: - type: string - type: 'null' slug: type: string description: anyOf: - type: string - type: 'null' integrationSlug: anyOf: - type: string - type: 'null' modelUuid: anyOf: - type: string - type: 'null' filter: anyOf: - type: object properties: conjonction: type: string enum: - or - and groups: type: array items: {} required: - conjonction - groups - type: 'null' selectedColumnSlugs: anyOf: - type: array items: type: string - type: 'null' limit: anyOf: - type: number - type: 'null' prompt: anyOf: - type: string - type: 'null' isReadOnly: type: boolean required: - kind - name - slug - description - integrationSlug - modelUuid - filter - selectedColumnSlugs - limit - prompt - isReadOnly - type: object properties: kind: type: string const: file name: anyOf: - type: string - type: 'null' slug: type: string description: anyOf: - type: string - type: 'null' items: type: array items: anyOf: - type: object properties: kind: type: string const: file fileUuid: type: string required: - kind - fileUuid - type: object properties: kind: type: string const: folder folderUuid: type: string required: - kind - folderUuid prompt: anyOf: - type: string - type: 'null' required: - kind - name - slug - description - items - prompt capabilities: title: Capabilities description: Capabilities available for the message. type: array items: oneOf: - type: object properties: slug: type: string const: sandbox config: type: object properties: scope: type: string enum: - chat - agent required: - slug - config - type: object properties: slug: type: string const: context config: type: object properties: isReadOnly: type: boolean required: - slug - config - type: object properties: slug: type: string const: app config: type: object properties: appUuid: type: string canPromote: type: boolean required: - slug - config - type: object properties: slug: type: string const: document config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config - type: object properties: slug: type: string const: webSearch config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config - type: object properties: slug: type: string const: fileSearch config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config - type: object properties: slug: type: string const: documentationSearch config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config - type: object properties: slug: type: string const: codeInterpreter config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config - type: object properties: slug: type: string const: memory config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config - type: object properties: slug: type: string const: suggestedActions config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config type: object mcpClients: title: MCP clients description: MCP clients to use for the message. type: array items: oneOf: - type: object properties: kind: type: string const: custom name: type: string url: type: string authentication: anyOf: - type: object properties: issuedAt: type: string accessToken: type: string expiresIn: type: number refreshToken: type: string scope: type: string tokenType: type: string clientId: type: string clientSecret: type: string required: - issuedAt - accessToken - type: 'null' disabledToolSlugs: type: array items: type: string required: - kind - name - url - authentication - disabledToolSlugs - type: object properties: kind: type: string const: connector name: type: string connectorUuid: type: string integrationSlug: type: string disabledToolSlugs: type: array items: type: string required: - kind - name - connectorUuid - integrationSlug - disabledToolSlugs type: object systemPrompt: title: System prompt description: System prompt for the message. type: string withReasoning: title: With reasoning description: Whether to include reasoning. type: boolean temperature: title: Temperature description: Sampling temperature. type: number maxSteps: title: Max steps description: Maximum number of steps. type: number integrationSlug: title: Integration slug description: Integration identifier. type: string connectorUuid: title: Connector UUID description: Connector identifier. type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$ languageModelSlug: title: Language model slug description: Language model identifier. type: string output: title: Output description: >- Output format for the assistant message. Defaults to text when omitted. oneOf: - type: object properties: type: type: string const: text required: - type - type: object properties: type: type: string const: jsonSchema jsonSchema: type: object propertyNames: type: string additionalProperties: {} required: - type - jsonSchema type: object required: - parts additionalProperties: false title: Request body description: Request body schema. responses: '200': description: Successful response content: application/json: schema: type: object properties: userMessage: type: object properties: uuid: type: string workspaceUuid: type: string agentUuid: anyOf: - type: string - type: 'null' releaseUuid: anyOf: - type: string - type: 'null' chatUuid: type: string userUuid: anyOf: - type: string - type: 'null' status: type: string enum: - pending - generating - success - error - cancelling - cancelled errorMessage: anyOf: - type: string - type: 'null' type: type: string enum: - user - assistant parts: type: array items: {} actions: type: array items: allOf: - type: object properties: name: anyOf: - type: string - type: 'null' slug: type: string description: anyOf: - type: string - type: 'null' isBulkAllowed: type: boolean config: type: object propertyNames: type: string additionalProperties: {} required: - name - slug - description - isBulkAllowed - config additionalProperties: false - anyOf: - type: object properties: kind: type: string const: tool toolUuid: anyOf: - type: string - type: 'null' templateSlug: anyOf: - type: string - type: 'null' waitUntilFinished: type: boolean required: - kind - toolUuid - templateSlug - waitUntilFinished additionalProperties: false - type: object properties: kind: type: string const: agent agentUuid: anyOf: - type: string - type: 'null' templateSlug: anyOf: - type: string - type: 'null' waitUntilFinished: type: boolean required: - kind - agentUuid - templateSlug - waitUntilFinished additionalProperties: false - type: object properties: kind: type: string const: connector integrationSlug: type: string connectorUuid: anyOf: - type: string - type: 'null' actionSlug: type: string required: - kind - integrationSlug - connectorUuid - actionSlug additionalProperties: false resources: type: array items: anyOf: - type: object properties: kind: type: string const: model name: anyOf: - type: string - type: 'null' slug: type: string description: anyOf: - type: string - type: 'null' integrationSlug: anyOf: - type: string - type: 'null' modelUuid: anyOf: - type: string - type: 'null' filter: anyOf: - type: object properties: conjonction: type: string enum: - or - and groups: type: array items: {} required: - conjonction - groups additionalProperties: false - type: 'null' selectedColumnSlugs: anyOf: - type: array items: type: string - type: 'null' limit: anyOf: - type: number - type: 'null' prompt: anyOf: - type: string - type: 'null' isReadOnly: type: boolean required: - kind - name - slug - description - integrationSlug - modelUuid - filter - selectedColumnSlugs - limit - prompt - isReadOnly additionalProperties: false - type: object properties: kind: type: string const: file name: anyOf: - type: string - type: 'null' slug: type: string description: anyOf: - type: string - type: 'null' items: type: array items: anyOf: - type: object properties: kind: type: string const: file fileUuid: type: string required: - kind - fileUuid additionalProperties: false - type: object properties: kind: type: string const: folder folderUuid: type: string required: - kind - folderUuid additionalProperties: false prompt: anyOf: - type: string - type: 'null' required: - kind - name - slug - description - items - prompt additionalProperties: false capabilities: type: array items: oneOf: - type: object properties: slug: type: string const: sandbox config: type: object properties: scope: type: string enum: - chat - agent additionalProperties: false required: - slug - config additionalProperties: false - type: object properties: slug: type: string const: context config: type: object properties: isReadOnly: type: boolean additionalProperties: false required: - slug - config additionalProperties: false - type: object properties: slug: type: string const: app config: type: object properties: appUuid: type: string canPromote: type: boolean additionalProperties: false required: - slug - config additionalProperties: false - type: object properties: slug: type: string const: document config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config additionalProperties: false - type: object properties: slug: type: string const: webSearch config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config additionalProperties: false - type: object properties: slug: type: string const: fileSearch config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config additionalProperties: false - type: object properties: slug: type: string const: documentationSearch config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config additionalProperties: false - type: object properties: slug: type: string const: codeInterpreter config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config additionalProperties: false - type: object properties: slug: type: string const: memory config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config additionalProperties: false - type: object properties: slug: type: string const: suggestedActions config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config additionalProperties: false type: object mcpClients: type: array items: oneOf: - type: object properties: kind: type: string const: custom name: type: string url: type: string authentication: anyOf: - type: object properties: issuedAt: type: string accessToken: type: string expiresIn: type: number refreshToken: type: string scope: type: string tokenType: type: string clientId: type: string clientSecret: type: string required: - issuedAt - accessToken additionalProperties: false - type: 'null' disabledToolSlugs: type: array items: type: string required: - kind - name - url - authentication - disabledToolSlugs additionalProperties: false - type: object properties: kind: type: string const: connector name: type: string connectorUuid: type: string integrationSlug: type: string disabledToolSlugs: type: array items: type: string required: - kind - name - connectorUuid - integrationSlug - disabledToolSlugs additionalProperties: false type: object systemPrompt: anyOf: - type: string - type: 'null' withReasoning: anyOf: - type: boolean - type: 'null' temperature: anyOf: - type: number - type: 'null' maxSteps: anyOf: - type: number - type: 'null' integrationSlug: anyOf: - type: string - type: 'null' connectorUuid: anyOf: - type: string - type: 'null' languageModelSlug: anyOf: - type: string - type: 'null' evaluatedTools: type: object propertyNames: type: string additionalProperties: {} usage: anyOf: - type: object properties: tokensUsedCount: type: number creditsUsedCount: type: number languageModelSlug: type: string connectorUuid: type: string required: - tokensUsedCount - creditsUsedCount - languageModelSlug - connectorUuid additionalProperties: false - type: 'null' output: {} meta: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' suggestedActions: type: array items: type: object properties: text: type: string actions: type: array items: type: object properties: slug: type: string required: - slug additionalProperties: false required: - text - actions additionalProperties: false temporalWorkflowId: anyOf: - type: string - type: 'null' createdAt: type: string updatedAt: type: string finishedAt: anyOf: - type: string - type: 'null' deletedAt: anyOf: - type: string - type: 'null' required: - uuid - workspaceUuid - agentUuid - releaseUuid - chatUuid - userUuid - status - errorMessage - type - parts - actions - resources - capabilities - mcpClients - systemPrompt - withReasoning - temperature - maxSteps - integrationSlug - connectorUuid - languageModelSlug - evaluatedTools - usage - output - meta - suggestedActions - temporalWorkflowId - createdAt - updatedAt - finishedAt - deletedAt additionalProperties: false title: User message description: The created user message. assistantMessage: type: object properties: uuid: type: string workspaceUuid: type: string agentUuid: anyOf: - type: string - type: 'null' releaseUuid: anyOf: - type: string - type: 'null' chatUuid: type: string userUuid: anyOf: - type: string - type: 'null' status: type: string enum: - pending - generating - success - error - cancelling - cancelled errorMessage: anyOf: - type: string - type: 'null' type: type: string enum: - user - assistant parts: type: array items: {} actions: type: array items: allOf: - type: object properties: name: anyOf: - type: string - type: 'null' slug: type: string description: anyOf: - type: string - type: 'null' isBulkAllowed: type: boolean config: type: object propertyNames: type: string additionalProperties: {} required: - name - slug - description - isBulkAllowed - config additionalProperties: false - anyOf: - type: object properties: kind: type: string const: tool toolUuid: anyOf: - type: string - type: 'null' templateSlug: anyOf: - type: string - type: 'null' waitUntilFinished: type: boolean required: - kind - toolUuid - templateSlug - waitUntilFinished additionalProperties: false - type: object properties: kind: type: string const: agent agentUuid: anyOf: - type: string - type: 'null' templateSlug: anyOf: - type: string - type: 'null' waitUntilFinished: type: boolean required: - kind - agentUuid - templateSlug - waitUntilFinished additionalProperties: false - type: object properties: kind: type: string const: connector integrationSlug: type: string connectorUuid: anyOf: - type: string - type: 'null' actionSlug: type: string required: - kind - integrationSlug - connectorUuid - actionSlug additionalProperties: false resources: type: array items: anyOf: - type: object properties: kind: type: string const: model name: anyOf: - type: string - type: 'null' slug: type: string description: anyOf: - type: string - type: 'null' integrationSlug: anyOf: - type: string - type: 'null' modelUuid: anyOf: - type: string - type: 'null' filter: anyOf: - type: object properties: conjonction: type: string enum: - or - and groups: type: array items: {} required: - conjonction - groups additionalProperties: false - type: 'null' selectedColumnSlugs: anyOf: - type: array items: type: string - type: 'null' limit: anyOf: - type: number - type: 'null' prompt: anyOf: - type: string - type: 'null' isReadOnly: type: boolean required: - kind - name - slug - description - integrationSlug - modelUuid - filter - selectedColumnSlugs - limit - prompt - isReadOnly additionalProperties: false - type: object properties: kind: type: string const: file name: anyOf: - type: string - type: 'null' slug: type: string description: anyOf: - type: string - type: 'null' items: type: array items: anyOf: - type: object properties: kind: type: string const: file fileUuid: type: string required: - kind - fileUuid additionalProperties: false - type: object properties: kind: type: string const: folder folderUuid: type: string required: - kind - folderUuid additionalProperties: false prompt: anyOf: - type: string - type: 'null' required: - kind - name - slug - description - items - prompt additionalProperties: false capabilities: type: array items: oneOf: - type: object properties: slug: type: string const: sandbox config: type: object properties: scope: type: string enum: - chat - agent additionalProperties: false required: - slug - config additionalProperties: false - type: object properties: slug: type: string const: context config: type: object properties: isReadOnly: type: boolean additionalProperties: false required: - slug - config additionalProperties: false - type: object properties: slug: type: string const: app config: type: object properties: appUuid: type: string canPromote: type: boolean additionalProperties: false required: - slug - config additionalProperties: false - type: object properties: slug: type: string const: document config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config additionalProperties: false - type: object properties: slug: type: string const: webSearch config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config additionalProperties: false - type: object properties: slug: type: string const: fileSearch config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config additionalProperties: false - type: object properties: slug: type: string const: documentationSearch config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config additionalProperties: false - type: object properties: slug: type: string const: codeInterpreter config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config additionalProperties: false - type: object properties: slug: type: string const: memory config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config additionalProperties: false - type: object properties: slug: type: string const: suggestedActions config: type: object propertyNames: type: string additionalProperties: {} required: - slug - config additionalProperties: false type: object mcpClients: type: array items: oneOf: - type: object properties: kind: type: string const: custom name: type: string url: type: string authentication: anyOf: - type: object properties: issuedAt: type: string accessToken: type: string expiresIn: type: number refreshToken: type: string scope: type: string tokenType: type: string clientId: type: string clientSecret: type: string required: - issuedAt - accessToken additionalProperties: false - type: 'null' disabledToolSlugs: type: array items: type: string required: - kind - name - url - authentication - disabledToolSlugs additionalProperties: false - type: object properties: kind: type: string const: connector name: type: string connectorUuid: type: string integrationSlug: type: string disabledToolSlugs: type: array items: type: string required: - kind - name - connectorUuid - integrationSlug - disabledToolSlugs additionalProperties: false type: object systemPrompt: anyOf: - type: string - type: 'null' withReasoning: anyOf: - type: boolean - type: 'null' temperature: anyOf: - type: number - type: 'null' maxSteps: anyOf: - type: number - type: 'null' integrationSlug: anyOf: - type: string - type: 'null' connectorUuid: anyOf: - type: string - type: 'null' languageModelSlug: anyOf: - type: string - type: 'null' evaluatedTools: type: object propertyNames: type: string additionalProperties: {} usage: anyOf: - type: object properties: tokensUsedCount: type: number creditsUsedCount: type: number languageModelSlug: type: string connectorUuid: type: string required: - tokensUsedCount - creditsUsedCount - languageModelSlug - connectorUuid additionalProperties: false - type: 'null' output: {} meta: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' suggestedActions: type: array items: type: object properties: text: type: string actions: type: array items: type: object properties: slug: type: string required: - slug additionalProperties: false required: - text - actions additionalProperties: false temporalWorkflowId: anyOf: - type: string - type: 'null' createdAt: type: string updatedAt: type: string finishedAt: anyOf: - type: string - type: 'null' deletedAt: anyOf: - type: string - type: 'null' required: - uuid - workspaceUuid - agentUuid - releaseUuid - chatUuid - userUuid - status - errorMessage - type - parts - actions - resources - capabilities - mcpClients - systemPrompt - withReasoning - temperature - maxSteps - integrationSlug - connectorUuid - languageModelSlug - evaluatedTools - usage - output - meta - suggestedActions - temporalWorkflowId - createdAt - updatedAt - finishedAt - deletedAt additionalProperties: false title: Assistant message description: >- The created assistant message (initially pending while processing). required: - userMessage - assistantMessage additionalProperties: false '400': description: Bad request '401': description: Unauthorized '404': description: Not found '500': description: Internal server error components: securitySchemes: bearerAuth: type: http scheme: bearer ````