CumulusDocs
Open Studio
On this page

Send a chat message

Send a user turn to a cloud chat run. Read the reply through run events or the transcript.

Operation ID: runs.send_message.

Request

POST /api/v1/runs/{run_id}/messages

  • TypeScript SDK: client.runs.send_message (path arguments use path).
  • MCP tool: sdk_client_call with operationId: "runs.send_message" (path arguments use input.path). Legacy alias: runs_send_message. Connect to your authenticated /mcp endpoint with an API key for the same environment.
  • Minimum API key role: member.
  • Idempotency: Required. Send Idempotency-Key (TypeScript SDK: idempotencyKey) and keep it for retries.

Read resource IDs from earlier responses and use a key for the same environment.

Request example

Use the ID of an active cloud chat run in the URL.

Set CUMULUS_BASE_URL to your workspace API URL and CUMULUS_API_KEY to a key for that environment. Set IDEMPOTENCY_KEY to a new UUID for this action and keep it for retries. Example values are synthetic.

cURL

curl
curl --fail-with-body -sS -X POST "${CUMULUS_BASE_URL%/}/api/v1/runs/${RUN_ID}/messages" \
  -H "Authorization: Bearer $CUMULUS_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "text": "Can you explain the charge on my invoice?"
}'

TypeScript

typescript
import { Cumulus } from "@cumulus/sdk";

const baseUrl = process.env.CUMULUS_BASE_URL;
const apiKey = process.env.CUMULUS_API_KEY;
if (!baseUrl || !apiKey) throw new Error("Set CUMULUS_BASE_URL and CUMULUS_API_KEY");
const client = new Cumulus({ baseUrl, apiKey });

const idempotencyKey = process.env.IDEMPOTENCY_KEY;
if (!idempotencyKey) throw new Error("Set IDEMPOTENCY_KEY for this request");

const response = await client.runs.send_message({
  "path": {
    "run_id": "<run_id>"
  },
  "body": {
    "text": "Can you explain the charge on my invoice?"
  },
  idempotencyKey,
});

Input schema

Path, query and header parameters

run_id

path parameter · Required.

Type: string (uuid). pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.

Idempotency-Key

header parameter · Required.

Type: string. minLength: 1. maxLength: 256.

JSON request body

FieldType or valuesRequiredDescription and limits
textstringRequiredminLength: 1. maxLength: 32000.
Complete OpenAPI schema
OpenAPI JSON
{
  "parameters": [
    {
      "name": "run_id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
      }
    },
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 1,
        "maxLength": 256
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/RunsSendMessageRequest"
        }
      }
    }
  }
}

Responses

HTTP 202

Send a user message to a cloud chat run

application/json

FieldType or valuesRequiredDescription and limits
run_idstring (uuid)RequiredRun identifier returned when the run was admitted. pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
indexintegerRequiredAt least 0. At most 9007199254740991.

Error responses

HTTPDescription
4XXTyped error (ApiError)
5XXTyped error (ApiError)

Errors use the shared error envelope. Inspect error.code, retryable, outcome and details before retrying.

Complete OpenAPI schema
OpenAPI JSON
{
  "202": {
    "description": "Send a user message to a cloud chat run",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/RunsSendMessageResponse202"
        }
      }
    }
  },
  "4XX": {
    "description": "Typed error (ApiError)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "5XX": {
    "description": "Typed error (ApiError)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}

Referenced schemas

Expand the complete OpenAPI definitions for integrations that generate their own clients.

Complete OpenAPI schema
OpenAPI JSON
{
  "components": {
    "schemas": {
      "RunsSendMessageRequest": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 32000
          }
        },
        "required": [
          "text"
        ],
        "additionalProperties": false
      },
      "RunsSendMessageResponse202": {
        "type": "object",
        "properties": {
          "run_id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
          },
          "index": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "run_id",
          "index"
        ],
        "additionalProperties": false
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthenticated",
                  "forbidden",
                  "not_found",
                  "conflict",
                  "invalid_request",
                  "idempotency_conflict",
                  "policy_denied",
                  "capability_unavailable",
                  "provider_unavailable",
                  "knowledge_unavailable",
                  "publication_invalid",
                  "run_not_active",
                  "rate_limited",
                  "outcome_unknown",
                  "internal"
                ]
              },
              "message": {
                "type": "string"
              },
              "retryable": {
                "type": "boolean"
              },
              "outcome": {
                "type": "string",
                "enum": [
                  "none",
                  "unknown"
                ]
              },
              "details": {
                "type": "object",
                "additionalProperties": {}
              }
            },
            "required": [
              "code",
              "message",
              "retryable",
              "outcome"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      }
    }
  }
}

Errors and recovery

See API error handling and Troubleshooting.

Content version a446f66bCustomer SDKMarkdown source
Send a chat message · Cumulus developer docs