Create Message

POST/v1/omni-ai/threads/{thread_id}/messages

Append a user message to an existing thread and start an assistant response. Poll the returned response_id via GET /omni-ai/responses/{response_id} for assistant output.

Only one response may be active per thread. Wait for it to reach a terminal status before submitting another turn; otherwise this endpoint returns 409.

The first accepted selected-account message links an unlinked thread. A linked thread keeps its account regardless of omission or another selection. A changed scope also returns 409 without accepting a turn.

Path ParametersExpand Collapse

thread_id: string

Body ParametersJSONExpand Collapse

text: string

account_id: optional number

Selected account for creation or the first account-linked turn. Omit for an unlinked conversation. An existing account link remains authoritative even when another account is selected.

formatint64

minimum1

capabilities: optional array of "PREFILL_ORDER" or "OPEN_CHART" or "OPEN_SCREENER" or "OPEN_ENTITLEMENT_CONSENT"

One of the following:

"PREFILL_ORDER"

"OPEN_CHART"

"OPEN_SCREENER"

"OPEN_ENTITLEMENT_CONSENT"

context: optional TurnContext { items }

Snapshots for this instant-chat message. Omission does not remove earlier attachments.

items: array of ContextItem { data, kind, label, captured_at }

One to four snapshots. Each snapshot’s data may contain at most 32 levels of nesting.

data: map[unknown]

Relevant widget data, selections, and units. Use strings for exact decimals and large IDs.

kind: string

Nonblank descriptive kind. New kinds do not require a backend release.

minLength1

label: string

Nonblank attachment label for conversation rendering.

minLength1

captured_at: optional string

Client-reported snapshot time. Omit when unknown.

formatdate-time

ReturnsExpand Collapse

data: CreateMessageResponse { response_id, thread_id, user_message_id }

Response payload for continuing a thread with a new message.

response_id: string

thread_id: string

user_message_id: string

Create Message

curl https://api.clearstreet.com/v1/omni-ai/threads/$THREAD_ID/messages \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $API_KEY" \
    -d '{
          "text": "Compare that to AMD.",
          "account_id": 19816
        }'

{
  "data": {
    "response_id": "019dbaec-8dd3-7fa3-89d0-5303609f125f",
    "thread_id": "019dbae9-73b3-7fe0-bd14-25fe57e91475",
    "user_message_id": "019dbaec-8dd4-7f91-bce2-3ec8fba79eb7"
  },
  "metadata": {
    "request_id": "48775400-61f4-4c6c-bc6d-8f4996c571c7"
  }
}

{
  "error": {
    "code": 400,
    "message": "account_id must be positive"
  },
  "metadata": {
    "request_id": "9fbd975d-be1e-4710-9004-1f54d0d4dfb6"
  }
}

{
  "error": {
    "code": 400,
    "message": "Failed to parse the request body as JSON: EOF while parsing an object at line 3 column 0"
  },
  "metadata": {
    "request_id": "8cf61bb3-a8c6-4f3e-abe8-5a5327001b55"
  }
}

{
  "error": {
    "code": 409,
    "message": "thread already has an active response"
  },
  "metadata": {
    "request_id": "7b34ad9b-e09a-40d1-aab8-2185a8df5a31"
  }
}

Returns Examples

{
  "data": {
    "response_id": "019dbaec-8dd3-7fa3-89d0-5303609f125f",
    "thread_id": "019dbae9-73b3-7fe0-bd14-25fe57e91475",
    "user_message_id": "019dbaec-8dd4-7f91-bce2-3ec8fba79eb7"
  },
  "metadata": {
    "request_id": "48775400-61f4-4c6c-bc6d-8f4996c571c7"
  }
}

{
  "error": {
    "code": 400,
    "message": "account_id must be positive"
  },
  "metadata": {
    "request_id": "9fbd975d-be1e-4710-9004-1f54d0d4dfb6"
  }
}

{
  "error": {
    "code": 400,
    "message": "Failed to parse the request body as JSON: EOF while parsing an object at line 3 column 0"
  },
  "metadata": {
    "request_id": "8cf61bb3-a8c6-4f3e-abe8-5a5327001b55"
  }
}

{
  "error": {
    "code": 409,
    "message": "thread already has an active response"
  },
  "metadata": {
    "request_id": "7b34ad9b-e09a-40d1-aab8-2185a8df5a31"
  }
}