---
title: "Create message"
method: POST
path: "/ai/messages"
tags: ["AI - Messages"]
---

# Create message

`POST /ai/messages`

Create a new message in a chat. Returns the user message and a pending assistant message. The assistant response is processed asynchronously.

## Request body

- object — Request body schema.
  - `chatUuid` string, uuid — Chat identifier. When omitted, a new draft chat is created automatically and the message is added to it.
  - `agentUuid` string, uuid — Agent identifier for the chat. Only used when chatUuid is omitted and a chat is created automatically.
  - `releaseUuid` string, uuid — Release identifier for the chat. Only used when chatUuid is omitted and a chat is created automatically.
  - `parts` unknown[], required — Message parts.
    - unknown
  - `actions` union[] — Actions available for the message.
    - union
      - object
        - `name` string, nullable, required
        - `slug` string, required
        - `description` string, nullable, required
        - `isBulkAllowed` boolean, required
        - `config` object, required
        - `kind` 'tool', required
        - `toolUuid` string, nullable, required
        - `templateSlug` string, nullable, required
        - `waitUntilFinished` boolean, required
      - object
        - `name` string, nullable, required
        - `slug` string, required
        - `description` string, nullable, required
        - `isBulkAllowed` boolean, required
        - `config` object, required
        - `kind` 'agent', required
        - `agentUuid` string, nullable, required
        - `templateSlug` string, nullable, required
        - `waitUntilFinished` boolean, required
      - object
        - `name` string, nullable, required
        - `slug` string, required
        - `description` string, nullable, required
        - `isBulkAllowed` boolean, required
        - `config` object, required
        - `kind` 'connector', required
        - `integrationSlug` string, required
        - `connectorUuid` string, nullable, required
        - `actionSlug` string, required
  - `resources` union[] — Resources available for the message.
    - union
      - object
        - `kind` 'model', required
        - `name` string, nullable, required
        - `slug` string, required
        - `description` string, nullable, required
        - `integrationSlug` string, nullable, required
        - `modelUuid` string, nullable, required
        - `filter` object, nullable, required
          - `conjonction` 'or' | 'and', required
          - `groups` unknown[], required
            - unknown
        - `selectedColumnSlugs` string[], nullable, required
        - `limit` number, nullable, required
        - `prompt` string, nullable, required
        - `isReadOnly` boolean, required
      - object
        - `kind` 'file', required
        - `name` string, nullable, required
        - `slug` string, required
        - `description` string, nullable, required
        - `items` union[], required
          - union
            - object
              - …
            - object
              - …
        - `prompt` string, nullable, required
  - `capabilities` union[] — Capabilities available for the message.
    - union
      - object
        - `slug` 'sandbox', required
        - `config` object, required
          - `scope` 'chat' | 'agent'
      - object
        - `slug` 'context', required
        - `config` object, required
          - `isReadOnly` boolean
      - object
        - `slug` 'app', required
        - `config` object, required
          - `appUuid` string
          - `canPromote` boolean
      - object
        - `slug` 'document', required
        - `config` object, required
      - object
        - `slug` 'webSearch', required
        - `config` object, required
      - object
        - `slug` 'fileSearch', required
        - `config` object, required
      - object
        - `slug` 'documentationSearch', required
        - `config` object, required
      - object
        - `slug` 'codeInterpreter', required
        - `config` object, required
      - object
        - `slug` 'memory', required
        - `config` object, required
      - object
        - `slug` 'suggestedActions', required
        - `config` object, required
  - `mcpClients` union[] — MCP clients to use for the message.
    - union
      - object
        - `kind` 'custom', required
        - `name` string, required
        - `url` string, required
        - `authentication` object, nullable, required
          - `issuedAt` string, required
          - `accessToken` string, required
          - `expiresIn` number
          - `refreshToken` string
          - `scope` string
          - `tokenType` string
          - `clientId` string
          - `clientSecret` string
        - `disabledToolSlugs` string[], required
      - object
        - `kind` 'connector', required
        - `name` string, required
        - `connectorUuid` string, required
        - `integrationSlug` string, required
        - `disabledToolSlugs` string[], required
  - `systemPrompt` string — System prompt for the message.
  - `withReasoning` boolean — Whether to include reasoning.
  - `temperature` number — Sampling temperature.
  - `maxSteps` number — Maximum number of steps.
  - `integrationSlug` string — Integration identifier.
  - `connectorUuid` string, uuid — Connector identifier.
  - `languageModelSlug` string — Language model identifier.
  - `output` union — Output format for the assistant message. Defaults to text when omitted.
    - object
      - `type` 'text', required
    - object
      - `type` 'jsonSchema', required
      - `jsonSchema` object, required

## Response `200`

Successful response

- object
  - `userMessage` object, required — The created user message.
    - `uuid` string, required
    - `workspaceUuid` string, required
    - `agentUuid` string, nullable, required
    - `releaseUuid` string, nullable, required
    - `chatUuid` string, required
    - `userUuid` string, nullable, required
    - `status` 'pending' | 'generating' | 'success' | 'error' | 'cancelling' | 'cancelled', required
    - `errorMessage` string, nullable, required
    - `type` 'user' | 'assistant', required
    - `parts` unknown[], required
      - unknown
    - `actions` union[], required
      - union
        - object
          - `name` string, nullable, required
          - `slug` string, required
          - `description` string, nullable, required
          - `isBulkAllowed` boolean, required
          - `config` object, required
          - `kind` 'tool', required
          - `toolUuid` string, nullable, required
          - `templateSlug` string, nullable, required
          - `waitUntilFinished` boolean, required
        - object
          - `name` string, nullable, required
          - `slug` string, required
          - `description` string, nullable, required
          - `isBulkAllowed` boolean, required
          - `config` object, required
          - `kind` 'agent', required
          - `agentUuid` string, nullable, required
          - `templateSlug` string, nullable, required
          - `waitUntilFinished` boolean, required
        - object
          - `name` string, nullable, required
          - `slug` string, required
          - `description` string, nullable, required
          - `isBulkAllowed` boolean, required
          - `config` object, required
          - `kind` 'connector', required
          - `integrationSlug` string, required
          - `connectorUuid` string, nullable, required
          - `actionSlug` string, required
    - `resources` union[], required
      - union
        - object
          - `kind` 'model', required
          - `name` string, nullable, required
          - `slug` string, required
          - `description` string, nullable, required
          - `integrationSlug` string, nullable, required
          - `modelUuid` string, nullable, required
          - `filter` object, nullable, required
            - `conjonction` 'or' | 'and', required
            - `groups` unknown[], required
              - …
          - `selectedColumnSlugs` string[], nullable, required
          - `limit` number, nullable, required
          - `prompt` string, nullable, required
          - `isReadOnly` boolean, required
        - object
          - `kind` 'file', required
          - `name` string, nullable, required
          - `slug` string, required
          - `description` string, nullable, required
          - `items` union[], required
            - union
              - …
          - `prompt` string, nullable, required
    - `capabilities` union[], required
      - union
        - object
          - `slug` 'sandbox', required
          - `config` object, required
            - `scope` 'chat' | 'agent'
        - object
          - `slug` 'context', required
          - `config` object, required
            - `isReadOnly` boolean
        - object
          - `slug` 'app', required
          - `config` object, required
            - `appUuid` string
            - `canPromote` boolean
        - object
          - `slug` 'document', required
          - `config` object, required
        - object
          - `slug` 'webSearch', required
          - `config` object, required
        - object
          - `slug` 'fileSearch', required
          - `config` object, required
        - object
          - `slug` 'documentationSearch', required
          - `config` object, required
        - object
          - `slug` 'codeInterpreter', required
          - `config` object, required
        - object
          - `slug` 'memory', required
          - `config` object, required
        - object
          - `slug` 'suggestedActions', required
          - `config` object, required
    - `mcpClients` union[], required
      - union
        - object
          - `kind` 'custom', required
          - `name` string, required
          - `url` string, required
          - `authentication` object, nullable, required
            - `issuedAt` string, required
            - `accessToken` string, required
            - `expiresIn` number
            - `refreshToken` string
            - `scope` string
            - `tokenType` string
            - `clientId` string
            - `clientSecret` string
          - `disabledToolSlugs` string[], required
        - object
          - `kind` 'connector', required
          - `name` string, required
          - `connectorUuid` string, required
          - `integrationSlug` string, required
          - `disabledToolSlugs` string[], required
    - `systemPrompt` string, nullable, required
    - `withReasoning` boolean, nullable, required
    - `temperature` number, nullable, required
    - `maxSteps` number, nullable, required
    - `integrationSlug` string, nullable, required
    - `connectorUuid` string, nullable, required
    - `languageModelSlug` string, nullable, required
    - `evaluatedTools` object, required
    - `usage` object, nullable, required
      - `tokensUsedCount` number, required
      - `creditsUsedCount` number, required
      - `languageModelSlug` string, required
      - `connectorUuid` string, required
    - `output` unknown, required
    - `meta` object, nullable, required
    - `suggestedActions` object[], required
      - `text` string, required
      - `actions` object[], required
        - `slug` string, required
    - `temporalWorkflowId` string, nullable, required
    - `createdAt` string, required
    - `updatedAt` string, required
    - `finishedAt` string, nullable, required
    - `deletedAt` string, nullable, required
  - `assistantMessage` object, required — The created assistant message (initially pending while processing).
    - `uuid` string, required
    - `workspaceUuid` string, required
    - `agentUuid` string, nullable, required
    - `releaseUuid` string, nullable, required
    - `chatUuid` string, required
    - `userUuid` string, nullable, required
    - `status` 'pending' | 'generating' | 'success' | 'error' | 'cancelling' | 'cancelled', required
    - `errorMessage` string, nullable, required
    - `type` 'user' | 'assistant', required
    - `parts` unknown[], required
      - unknown
    - `actions` union[], required
      - union
        - object
          - `name` string, nullable, required
          - `slug` string, required
          - `description` string, nullable, required
          - `isBulkAllowed` boolean, required
          - `config` object, required
          - `kind` 'tool', required
          - `toolUuid` string, nullable, required
          - `templateSlug` string, nullable, required
          - `waitUntilFinished` boolean, required
        - object
          - `name` string, nullable, required
          - `slug` string, required
          - `description` string, nullable, required
          - `isBulkAllowed` boolean, required
          - `config` object, required
          - `kind` 'agent', required
          - `agentUuid` string, nullable, required
          - `templateSlug` string, nullable, required
          - `waitUntilFinished` boolean, required
        - object
          - `name` string, nullable, required
          - `slug` string, required
          - `description` string, nullable, required
          - `isBulkAllowed` boolean, required
          - `config` object, required
          - `kind` 'connector', required
          - `integrationSlug` string, required
          - `connectorUuid` string, nullable, required
          - `actionSlug` string, required
    - `resources` union[], required
      - union
        - object
          - `kind` 'model', required
          - `name` string, nullable, required
          - `slug` string, required
          - `description` string, nullable, required
          - `integrationSlug` string, nullable, required
          - `modelUuid` string, nullable, required
          - `filter` object, nullable, required
            - `conjonction` 'or' | 'and', required
            - `groups` unknown[], required
              - …
          - `selectedColumnSlugs` string[], nullable, required
          - `limit` number, nullable, required
          - `prompt` string, nullable, required
          - `isReadOnly` boolean, required
        - object
          - `kind` 'file', required
          - `name` string, nullable, required
          - `slug` string, required
          - `description` string, nullable, required
          - `items` union[], required
            - union
              - …
          - `prompt` string, nullable, required
    - `capabilities` union[], required
      - union
        - object
          - `slug` 'sandbox', required
          - `config` object, required
            - `scope` 'chat' | 'agent'
        - object
          - `slug` 'context', required
          - `config` object, required
            - `isReadOnly` boolean
        - object
          - `slug` 'app', required
          - `config` object, required
            - `appUuid` string
            - `canPromote` boolean
        - object
          - `slug` 'document', required
          - `config` object, required
        - object
          - `slug` 'webSearch', required
          - `config` object, required
        - object
          - `slug` 'fileSearch', required
          - `config` object, required
        - object
          - `slug` 'documentationSearch', required
          - `config` object, required
        - object
          - `slug` 'codeInterpreter', required
          - `config` object, required
        - object
          - `slug` 'memory', required
          - `config` object, required
        - object
          - `slug` 'suggestedActions', required
          - `config` object, required
    - `mcpClients` union[], required
      - union
        - object
          - `kind` 'custom', required
          - `name` string, required
          - `url` string, required
          - `authentication` object, nullable, required
            - `issuedAt` string, required
            - `accessToken` string, required
            - `expiresIn` number
            - `refreshToken` string
            - `scope` string
            - `tokenType` string
            - `clientId` string
            - `clientSecret` string
          - `disabledToolSlugs` string[], required
        - object
          - `kind` 'connector', required
          - `name` string, required
          - `connectorUuid` string, required
          - `integrationSlug` string, required
          - `disabledToolSlugs` string[], required
    - `systemPrompt` string, nullable, required
    - `withReasoning` boolean, nullable, required
    - `temperature` number, nullable, required
    - `maxSteps` number, nullable, required
    - `integrationSlug` string, nullable, required
    - `connectorUuid` string, nullable, required
    - `languageModelSlug` string, nullable, required
    - `evaluatedTools` object, required
    - `usage` object, nullable, required
      - `tokensUsedCount` number, required
      - `creditsUsedCount` number, required
      - `languageModelSlug` string, required
      - `connectorUuid` string, required
    - `output` unknown, required
    - `meta` object, nullable, required
    - `suggestedActions` object[], required
      - `text` string, required
      - `actions` object[], required
        - `slug` string, required
    - `temporalWorkflowId` string, nullable, required
    - `createdAt` string, required
    - `updatedAt` string, required
    - `finishedAt` string, nullable, required
    - `deletedAt` string, nullable, required

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `404` — Not found
- `500` — Internal server error

---

[API](https://skmtc.net/getcargo/apis/cargo-api.md) · [All operations](https://skmtc.net/getcargo/apis/cargo-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getcargo/cargo-api/versions/1d5a19e01d83/schema)