# Omni AI ## Domain Types ### Action Button - `ActionButton object { buttonId, label, prompt, structuredAction }` Button metadata shared by chart and suggested-actions payloads. - `buttonId: string` Stable button identifier within the content part. - `label: string` User-visible label. - `prompt: optional PromptButtonAction` Follow-up prompt to submit as the next user message. - `prompt: string` Prompt text to submit as the next user turn. - `structuredAction: optional StructuredActionButtonAction` Structured action in the same message to execute on click. - `actionId: optional string` UUID of a `structured_action` content part in the same message. ### Chart Payload - `ChartPayload object { chartId, actionButtons, dataChart, symbolChart }` Typed chart payload rendered inline in assistant content. - `chartId: string` Stable chart identifier scoped to the content part. - `actionButtons: optional array of ActionButton` Buttons associated with this chart. - `buttonId: string` Stable button identifier within the content part. - `label: string` User-visible label. - `prompt: optional PromptButtonAction` Follow-up prompt to submit as the next user message. - `prompt: string` Prompt text to submit as the next user turn. - `structuredAction: optional StructuredActionButtonAction` Structured action in the same message to execute on click. - `actionId: optional string` UUID of a `structured_action` content part in the same message. - `dataChart: optional DataChart` Explicit series-driven chart definition. - `series: optional array of ChartSeries` - `name: string` - `points: optional array of ChartPoint` - `x: string` - `y: number` - `symbolChart: optional SymbolChart` Symbol-driven chart definition. - `symbol: string` - `timeframe: optional string` ### Chart Point - `ChartPoint object { x, y }` Single chart coordinate. - `x: string` - `y: number` ### Chart Series - `ChartSeries object { name, points }` Named data series within a chart. - `name: string` - `points: optional array of ChartPoint` - `x: string` - `y: number` ### Content Part Chart Payload - `ContentPartChartPayload object { payload }` Chart payload content part. - `payload: ChartPayload` Typed chart payload rendered inline in assistant content. - `chartId: string` Stable chart identifier scoped to the content part. - `actionButtons: optional array of ActionButton` Buttons associated with this chart. - `buttonId: string` Stable button identifier within the content part. - `label: string` User-visible label. - `prompt: optional PromptButtonAction` Follow-up prompt to submit as the next user message. - `prompt: string` Prompt text to submit as the next user turn. - `structuredAction: optional StructuredActionButtonAction` Structured action in the same message to execute on click. - `actionId: optional string` UUID of a `structured_action` content part in the same message. - `dataChart: optional DataChart` Explicit series-driven chart definition. - `series: optional array of ChartSeries` - `name: string` - `points: optional array of ChartPoint` - `x: string` - `y: number` - `symbolChart: optional SymbolChart` Symbol-driven chart definition. - `symbol: string` - `timeframe: optional string` ### Content Part Custom Payload - `ContentPartCustomPayload object { payload }` Escape-hatch custom payload content part. - `payload: unknown` ### Content Part Structured Action Payload - `ContentPartStructuredActionPayload object { action, action_id }` Structured action content part. - `action: StructuredAction` Structured actions that Omni AI can return to clients. These actions provide machine-readable instructions for the client to execute, such as prefilling an order ticket, opening a chart, or navigating to a route. - `PrefillOrder object { prefill_order }` Prefill an order ticket for user confirmation - `prefill_order: PrefillOrderAction` Prefill an order ticket for user confirmation - `PrefillNewOrderAction = PrefillNewOrderAction` Create one or more new orders. - `action_type: "NEW"` - `"NEW"` - `PrefillCancelOrderAction = PrefillCancelOrderAction` Cancel one or more existing orders. - `action_type: "CANCEL"` - `"CANCEL"` - `OpenChart object { open_chart }` Open a chart for a symbol - `open_chart: OpenChartAction` Open a chart for a symbol - `symbol: string` Trading symbol to chart - `extras: optional unknown` Additional chart configuration (indicators, overlays, etc.) - `timeframe: optional string` Chart timeframe (e.g., "1D", "1W", "1M", "3M", "1Y", "5Y") - `OpenScreener object { open_screener }` Open a stock screener with filters - `open_screener: OpenScreenerAction` Open a stock screener with filters - `filters: array of ScreenerFilter` Filter criteria for the screener - `field: string` Field to filter on (e.g., "market_cap", "sector", "price") - `operator: string` Comparison operator (e.g., "eq", "gte", "lte", "in") - `value: unknown` Filter value - `field_filter: optional array of string` Optional field/column selection for screener results. - `page_size: optional number` Optional page size. - `sort_by: optional string` Optional sort field for screener rows. - `sort_direction: optional string` Optional sort direction (`ASC` or `DESC`). - `OpenEntitlementConsent object { open_entitlement_consent }` Open entitlement consent flow - `open_entitlement_consent: OpenEntitlementConsentAction` Open entitlement consent flow - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `reason: string` - `requested_entitlement_codes: array of EntitlementCode` - `"omni.account_data"` - `trading_account_ids: array of number` - `action_id: string` ### Content Part Suggested Actions Payload - `ContentPartSuggestedActionsPayload object { payload }` Suggested actions payload content part. - `payload: SuggestedActionsPayload` Suggested follow-up buttons rendered at the end of an assistant message. - `actionButtons: optional array of ActionButton` Ordered message-level buttons. - `buttonId: string` Stable button identifier within the content part. - `label: string` User-visible label. - `prompt: optional PromptButtonAction` Follow-up prompt to submit as the next user message. - `prompt: string` Prompt text to submit as the next user turn. - `structuredAction: optional StructuredActionButtonAction` Structured action in the same message to execute on click. - `actionId: optional string` UUID of a `structured_action` content part in the same message. ### Content Part Text Payload - `ContentPartTextPayload object { text }` Text content part. - `text: string` ### Content Part Thinking Payload - `ContentPartThinkingPayload object { thoughts }` Thinking content part shown on dynamic response polling. - `thoughts: array of string` ### Data Chart - `DataChart object { series }` Chart represented by explicit data series. - `series: optional array of ChartSeries` - `name: string` - `points: optional array of ChartPoint` - `x: string` - `y: number` ### Open Chart Action - `OpenChartAction object { symbol, extras, timeframe }` Action to open a chart for a symbol. - `symbol: string` Trading symbol to chart - `extras: optional unknown` Additional chart configuration (indicators, overlays, etc.) - `timeframe: optional string` Chart timeframe (e.g., "1D", "1W", "1M", "3M", "1Y", "5Y") ### Open Entitlement Consent Action - `OpenEntitlementConsentAction object { agreement_key, reason, requested_entitlement_codes, trading_account_ids }` Action to open entitlement consent flow for one or more accounts. - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `reason: string` - `requested_entitlement_codes: array of EntitlementCode` - `"omni.account_data"` - `trading_account_ids: array of number` ### Open Screener Action - `OpenScreenerAction object { filters, field_filter, page_size, 2 more }` Action to open a stock screener with filters. - `filters: array of ScreenerFilter` Filter criteria for the screener - `field: string` Field to filter on (e.g., "market_cap", "sector", "price") - `operator: string` Comparison operator (e.g., "eq", "gte", "lte", "in") - `value: unknown` Filter value - `field_filter: optional array of string` Optional field/column selection for screener results. - `page_size: optional number` Optional page size. - `sort_by: optional string` Optional sort field for screener rows. - `sort_direction: optional string` Optional sort direction (`ASC` or `DESC`). ### Prefill Cancel Order Action - `PrefillCancelOrderAction object { orders }` Cancel-order prefill action. - `orders: array of CancelOrderRequest` Orders to cancel using the same identifiers required by the cancel-order API. - `account_id: number` Account ID (from path parameter) - `order_id: string` Order ID to cancel (from path parameter) ### Prefill New Order Action - `PrefillNewOrderAction object { orders }` New-order prefill action. - `orders: array of NewOrderRequest` Orders to prefill using the same shape accepted by the orders API. - `instrument_type: SecurityType` Type of security - `"COMMON_STOCK"` - `"PREFERRED_STOCK"` - `"OPTION"` - `"CASH"` - `"OTHER"` - `order_type: RequestOrderType` Type of order - `"MARKET"` - `"LIMIT"` - `"STOP"` - `"STOP_LIMIT"` - `"TRAILING_STOP"` - `"TRAILING_STOP_LIMIT"` - `quantity: string` Quantity to trade. For COMMON_STOCK: shares (may be fractional if supported). For OPTION (single-leg): contracts (must be an integer) - `side: Side` Side of the order - `"BUY"` - `"SELL"` - `"SELL_SHORT"` - `"OTHER"` - `time_in_force: RequestTimeInForce` Time in force - `"DAY"` - `"GOOD_TILL_CANCEL"` - `"IMMEDIATE_OR_CANCEL"` - `"FILL_OR_KILL"` - `"GOOD_TILL_DATE"` - `"AT_THE_OPENING"` - `"AT_THE_CLOSE"` - `"GOOD_TILL_CROSSING"` - `"GOOD_THROUGH_CROSSING"` - `"AT_CROSSING"` - `id: optional string` Optional client-provided unique ID (idempotency). Required to be unique per account. - `expires_at: optional string` The timestamp when the order should expire (UTC). Required when time_in_force is GOOD_TILL_DATE. - `extended_hours: optional boolean` Allow trading outside regular trading hours. Some brokers disallow options outside RTH. - `instrument_id: optional InstrumentIDOrSymbol` OEMS instrument UUID - `limit_offset: optional string` Limit offset for trailing stop-limit orders (signed) - `limit_price: optional string` Limit price (required for LIMIT and STOP_LIMIT orders) - `position_effect: optional PositionEffect` Required when instrument_type is OPTION. Specifies whether the order opens or closes a position. - `"OPEN"` - `"CLOSE"` - `stop_price: optional string` Stop price (required for STOP and STOP_LIMIT orders) - `symbol: optional string` Trading symbol. For equities, use the ticker symbol (e.g., "AAPL"). For options, use the OSI symbol (e.g., "AAPL 250117C00190000"). Either `symbol` or `instrument_id` must be provided. - `trailing_offset: optional string` Trailing offset amount (required for trailing orders) - `trailing_offset_type: optional TrailingOffsetType` Trailing offset type (PRICE or PERCENT_BPS) - `"PRICE"` - `"BPS"` ### Prefill Order Action - `PrefillOrderAction = PrefillNewOrderAction or PrefillCancelOrderAction` Action to prefill order details for user confirmation. The user must review and authorize the order before submission to the trading API. This action provides parsed order data that can be used to prefill an order ticket UI or submitted directly via the orders API after user confirmation. - `PrefillNewOrderAction = PrefillNewOrderAction` Create one or more new orders. - `action_type: "NEW"` - `"NEW"` - `PrefillCancelOrderAction = PrefillCancelOrderAction` Cancel one or more existing orders. - `action_type: "CANCEL"` - `"CANCEL"` ### Prompt Button Action - `PromptButtonAction object { prompt }` Prompt-style button behavior. - `prompt: string` Prompt text to submit as the next user turn. ### Screener Filter - `ScreenerFilter object { field, operator, value }` A single filter criterion for the screener. - `field: string` Field to filter on (e.g., "market_cap", "sector", "price") - `operator: string` Comparison operator (e.g., "eq", "gte", "lte", "in") - `value: unknown` Filter value ### Structured Action - `StructuredAction = object { prefill_order } or object { open_chart } or object { open_screener } or object { open_entitlement_consent }` Structured actions that Omni AI can return to clients. These actions provide machine-readable instructions for the client to execute, such as prefilling an order ticket, opening a chart, or navigating to a route. - `PrefillOrder object { prefill_order }` Prefill an order ticket for user confirmation - `prefill_order: PrefillOrderAction` Prefill an order ticket for user confirmation - `PrefillNewOrderAction = PrefillNewOrderAction` Create one or more new orders. - `action_type: "NEW"` - `"NEW"` - `PrefillCancelOrderAction = PrefillCancelOrderAction` Cancel one or more existing orders. - `action_type: "CANCEL"` - `"CANCEL"` - `OpenChart object { open_chart }` Open a chart for a symbol - `open_chart: OpenChartAction` Open a chart for a symbol - `symbol: string` Trading symbol to chart - `extras: optional unknown` Additional chart configuration (indicators, overlays, etc.) - `timeframe: optional string` Chart timeframe (e.g., "1D", "1W", "1M", "3M", "1Y", "5Y") - `OpenScreener object { open_screener }` Open a stock screener with filters - `open_screener: OpenScreenerAction` Open a stock screener with filters - `filters: array of ScreenerFilter` Filter criteria for the screener - `field: string` Field to filter on (e.g., "market_cap", "sector", "price") - `operator: string` Comparison operator (e.g., "eq", "gte", "lte", "in") - `value: unknown` Filter value - `field_filter: optional array of string` Optional field/column selection for screener results. - `page_size: optional number` Optional page size. - `sort_by: optional string` Optional sort field for screener rows. - `sort_direction: optional string` Optional sort direction (`ASC` or `DESC`). - `OpenEntitlementConsent object { open_entitlement_consent }` Open entitlement consent flow - `open_entitlement_consent: OpenEntitlementConsentAction` Open entitlement consent flow - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `reason: string` - `requested_entitlement_codes: array of EntitlementCode` - `"omni.account_data"` - `trading_account_ids: array of number` ### Structured Action Button Action - `StructuredActionButtonAction object { actionId }` Structured-action button behavior. - `actionId: optional string` UUID of a `structured_action` content part in the same message. ### Suggested Actions Payload - `SuggestedActionsPayload object { actionButtons }` Suggested follow-up buttons rendered at the end of an assistant message. - `actionButtons: optional array of ActionButton` Ordered message-level buttons. - `buttonId: string` Stable button identifier within the content part. - `label: string` User-visible label. - `prompt: optional PromptButtonAction` Follow-up prompt to submit as the next user message. - `prompt: string` Prompt text to submit as the next user turn. - `structuredAction: optional StructuredActionButtonAction` Structured action in the same message to execute on click. - `actionId: optional string` UUID of a `structured_action` content part in the same message. ### Symbol Chart - `SymbolChart object { symbol, timeframe }` Chart for a single symbol and timeframe. - `symbol: string` - `timeframe: optional string` # Entitlements ## Get Entitlements **get** `/v1/omni-ai/entitlements` List caller's active entitlement grants. ### Query Parameters - `trading_account_id: optional number` ### Returns - `data: EntitlementResourceList` - `agreement_id: string` - `entitlement_code: EntitlementCode` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: string` - `granted_at: string` - `trading_account_id: number` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/entitlements \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": [ { "agreement_id": "agreement_id", "entitlement_code": "omni.account_data", "entitlement_id": "entitlement_id", "granted_at": "granted_at", "trading_account_id": 0 } ] } ``` ## Create Entitlements **post** `/v1/omni-ai/entitlements` Record consent and upsert one-or-more active grants. ### Body Parameters - `agreement_id: string` - `requested_entitlement_codes: array of EntitlementCode` - `"omni.account_data"` - `trading_account_ids: array of number` ### Returns - `data: EntitlementResourceList` - `agreement_id: string` - `entitlement_code: EntitlementCode` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: string` - `granted_at: string` - `trading_account_id: number` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/entitlements \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" \ -d '{ "agreement_id": "01JZ0000000000000000000000", "requested_entitlement_codes": [ "omni.account_data" ], "trading_account_ids": [ 100019, 100021 ] }' ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": [ { "agreement_id": "agreement_id", "entitlement_code": "omni.account_data", "entitlement_id": "entitlement_id", "granted_at": "granted_at", "trading_account_id": 0 } ] } ``` ## Delete Entitlement **delete** `/v1/omni-ai/entitlements/{entitlement_id}` Revoke one entitlement grant by id. ### Path Parameters - `entitlement_id: string` ### Returns - `data: DeleteEntitlementResponse` - `entitlement_id: string` - `revoked: boolean` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/entitlements/$ENTITLEMENT_ID \ -X DELETE \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": { "entitlement_id": "entitlement_id", "revoked": true } } ``` ## Get Entitlement Agreements **get** `/v1/omni-ai/entitlement-agreements` List current signable entitlement agreements for consent UX. ### Returns - `data: EntitlementAgreementResourceList` - `agreement_id: string` - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `document_content: string` - `document_sha256: string` - `entitlement_codes: array of EntitlementCode` - `"omni.account_data"` - `title: string` - `version: number` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/entitlement-agreements \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "metadata": { "request_id": "request_id", "next_page_token": "U3RhaW5sZXNzIHJvY2tz", "page_number": 0, "previous_page_token": "U3RhaW5sZXNzIHJvY2tz", "total_items": 0, "total_pages": 0 }, "error": { "code": 400, "message": "Order quantity must be greater than zero", "details": [ { "foo": "bar" } ] }, "data": [ { "agreement_id": "agreement_id", "agreement_key": "omni_account_data_access", "document_content": "document_content", "document_sha256": "document_sha256", "entitlement_codes": [ "omni.account_data" ], "title": "title", "version": 0 } ] } ``` ## Domain Types ### Delete Entitlement Response - `DeleteEntitlementResponse object { entitlement_id, revoked }` - `entitlement_id: string` - `revoked: boolean` ### Entitlement Agreement Key - `EntitlementAgreementKey = "omni_account_data_access"` Stable entitlement agreement family key. - `"omni_account_data_access"` ### Entitlement Agreement Resource - `EntitlementAgreementResource object { agreement_id, agreement_key, document_content, 4 more }` - `agreement_id: string` - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `document_content: string` - `document_sha256: string` - `entitlement_codes: array of EntitlementCode` - `"omni.account_data"` - `title: string` - `version: number` ### Entitlement Agreement Resource List - `EntitlementAgreementResourceList = array of EntitlementAgreementResource` - `agreement_id: string` - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `document_content: string` - `document_sha256: string` - `entitlement_codes: array of EntitlementCode` - `"omni.account_data"` - `title: string` - `version: number` ### Entitlement Code - `EntitlementCode = "omni.account_data"` Stable entitlement code granted by an agreement. - `"omni.account_data"` ### Entitlement Resource - `EntitlementResource object { agreement_id, entitlement_code, entitlement_id, 2 more }` - `agreement_id: string` - `entitlement_code: EntitlementCode` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: string` - `granted_at: string` - `trading_account_id: number` ### Entitlement Resource List - `EntitlementResourceList = array of EntitlementResource` - `agreement_id: string` - `entitlement_code: EntitlementCode` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: string` - `granted_at: string` - `trading_account_id: number` ### Entitlement Get Entitlements Response - `EntitlementGetEntitlementsResponse = BaseResponse` - `data: EntitlementResourceList` - `agreement_id: string` - `entitlement_code: EntitlementCode` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: string` - `granted_at: string` - `trading_account_id: number` ### Entitlement Create Entitlements Response - `EntitlementCreateEntitlementsResponse = BaseResponse` - `data: EntitlementResourceList` - `agreement_id: string` - `entitlement_code: EntitlementCode` Stable entitlement code granted by an agreement. - `"omni.account_data"` - `entitlement_id: string` - `granted_at: string` - `trading_account_id: number` ### Entitlement Delete Entitlement Response - `EntitlementDeleteEntitlementResponse = BaseResponse` - `data: DeleteEntitlementResponse` - `entitlement_id: string` - `revoked: boolean` ### Entitlement Get Entitlement Agreements Response - `EntitlementGetEntitlementAgreementsResponse = BaseResponse` - `data: EntitlementAgreementResourceList` - `agreement_id: string` - `agreement_key: EntitlementAgreementKey` Stable entitlement agreement family key. - `"omni_account_data_access"` - `document_content: string` - `document_sha256: string` - `entitlement_codes: array of EntitlementCode` - `"omni.account_data"` - `title: string` - `version: number` # Messages ## Get Message By ID **get** `/v1/omni-ai/messages/{message_id}` Get a finalized message by ID. Returns a single finalized message. Returns **404** if the message belongs to an in-progress assistant turn (use the response endpoint for live output). Once the turn completes, the message becomes available here. ### Path Parameters - `message_id: string` ### Query Parameters - `account_id: number` Account ID for the request ### Returns - `data: Message` Final immutable message. - `id: string` - `content: MessageContent` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `created_at: string` - `outcome: MessageOutcome` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: MessageRole` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: number` - `thread_id: string` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/messages/$MESSAGE_ID \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "content": { "parts": [ { "text": "**Pre-market as of 7:30 AM ET**\n\n ...", "type": "text" }, { "payload": { "actionButtons": [ { "buttonId": "btn_followup_0", "label": "Check my positions", "prompt": { "prompt": "What are my current positions?" } } ] }, "type": "suggested_actions" } ] }, "created_at": "2026-04-16T09:20:17.309212+00:00", "id": "019d9597-599c-7132-a7de-e5c21eaaab77", "outcome": "completed", "role": "ASSISTANT", "seq": 2, "thread_id": "019d9597-597c-7571-a0c9-a49c0e51f6eb" }, "metadata": { "request_id": "0f991501-757d-4051-bf00-6d7f452d6fcf" } } ``` ## Submit Feedback **post** `/v1/omni-ai/messages/{message_id}/feedback` Submit feedback on a finalized assistant message. Attaches a score and optional comment to a finalized assistant message. Feedback is only valid for messages with role `ASSISTANT` that have reached a terminal outcome. ### Path Parameters - `message_id: string` ### Body Parameters - `account_id: number` Account ID for the request - `score: number` Feedback score (-1, 0, +1 or 1-5) - `comment: optional string` Optional feedback comment - `metadata: optional unknown` Optional metadata ### Returns - `data: CreateFeedbackResponse` - `created_at: string` - `feedback_id: optional string` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/messages/$MESSAGE_ID/feedback \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" \ -d '{ "account_id": 0, "score": 0 }' ``` #### Response ```json { "data": { "created_at": "2026-04-23T16:09:51.746912+00:00", "feedback_id": "019dbb1a-d782-7f42-8dd8-a1a7ca5d48e3" }, "metadata": { "request_id": "372a359a-fd4f-4c69-8f11-d80831aa5f23" } } ``` ## Domain Types ### Create Feedback Response - `CreateFeedbackResponse object { created_at, feedback_id }` - `created_at: string` - `feedback_id: optional string` ### Message Get Message By ID Response - `MessageGetMessageByIDResponse = BaseResponse` - `data: Message` Final immutable message. - `id: string` - `content: MessageContent` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `created_at: string` - `outcome: MessageOutcome` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: MessageRole` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: number` - `thread_id: string` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` ### Message Submit Feedback Response - `MessageSubmitFeedbackResponse = BaseResponse` - `data: CreateFeedbackResponse` - `created_at: string` - `feedback_id: optional string` # Responses ## Get Response By ID **get** `/v1/omni-ai/responses/{response_id}` Poll a response for assistant output. Returns the current snapshot of an in-progress or completed response. While the status is `queued` or `running`, the content may be partial and may include `thinking` parts. Poll this endpoint periodically until the status reaches a terminal value (`succeeded`, `failed`, or `canceled`). Once terminal, the finalized assistant message is available in thread history via `GET /omni-ai/threads/{thread_id}/messages`. ### Path Parameters - `response_id: string` ### Query Parameters - `account_id: number` Account ID for the request ### Returns - `data: Response` Dynamic pollable response. - `id: string` - `status: ResponseStatus` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` - `thread_id: string` - `user_message_id: string` - `content: optional ResponseContent` Dynamic response content container. May include thinking parts. - `parts: array of ResponseContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` - `output_message_id: optional string` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/responses/$RESPONSE_ID \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "content": { "parts": [ { "text": "AAPL is currently trading at ...", "type": "text" }, { "thoughts": [ "Fetching current market data for AAPL..." ], "type": "thinking" } ] }, "id": "019dbafd-db54-7523-a412-ec9195cc5d99", "output_message_id": "019dbafd-db61-73a0-8bd9-d4034d132f81", "status": "succeeded", "thread_id": "019dbafd-db54-7523-a412-ec8a292246ad", "user_message_id": "019dbafd-db56-78a2-8a91-d54a39f44174" }, "metadata": { "request_id": "abc16101-2cbc-475a-84ef-98c8c588dcbb" } } ``` ## Cancel Response **delete** `/v1/omni-ai/responses/{response_id}` Cancel a response. Requests cancellation of a queued or running response. If the response has already reached a terminal status, this is an idempotent success. A canceled turn still produces a final assistant message with outcome `canceled` in the thread history. ### Path Parameters - `response_id: string` ### Query Parameters - `account_id: number` Account ID for the request ### Returns - `data: CancelResponsePayload` - `canceled: boolean` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/responses/$RESPONSE_ID \ -X DELETE \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "canceled": false }, "metadata": { "request_id": "fa26a786-f5d3-48b0-80eb-778e17af4964" } } ``` ## Domain Types ### Cancel Response Payload - `CancelResponsePayload object { canceled }` - `canceled: boolean` ### Error Status - `ErrorStatus object { code, message, details }` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` ### Response - `Response object { id, status, thread_id, 4 more }` Dynamic pollable response. - `id: string` - `status: ResponseStatus` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` - `thread_id: string` - `user_message_id: string` - `content: optional ResponseContent` Dynamic response content container. May include thinking parts. - `parts: array of ResponseContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` - `output_message_id: optional string` ### Response Content - `ResponseContent object { parts }` Dynamic response content container. May include thinking parts. - `parts: array of ResponseContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` ### Response Content Part - `ResponseContentPart = ContentPartTextPayload or ContentPartThinkingPayload or ContentPartStructuredActionPayload or 3 more` Dynamic content part visible on a pollable response. - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` ### Response Status - `ResponseStatus = "queued" or "running" or "succeeded" or 2 more` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` ### Response Get Response By ID Response - `ResponseGetResponseByIDResponse = BaseResponse` - `data: Response` Dynamic pollable response. - `id: string` - `status: ResponseStatus` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` - `thread_id: string` - `user_message_id: string` - `content: optional ResponseContent` Dynamic response content container. May include thinking parts. - `parts: array of ResponseContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` - `output_message_id: optional string` ### Response Cancel Response Response - `ResponseCancelResponseResponse = BaseResponse` - `data: CancelResponsePayload` - `canceled: boolean` # Threads ## Get Threads **get** `/v1/omni-ai/threads` List conversation threads. Returns thread metadata ordered by most recently created first. Use `page_size` and `page_token` for pagination. Thread objects contain only metadata (title, timestamps) — use the messages endpoint for conversation history. ### Query Parameters - `account_id: number` Account ID for the request - `page_size: optional number` The number of items to return per page. Only used when page_token is not provided. - `page_token: optional string` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. ### Returns - `data: ThreadList` - `id: string` - `created_at: string` - `title: string` - `updated_at: string` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/threads \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "created_at": "2026-04-23T15:15:54.929830+00:00", "id": "019dbae9-73b3-7fe0-bd14-25fe57e91475", "title": "What is current price of AAPL?", "updated_at": "2026-04-23T15:15:54.929830+00:00" } ], "metadata": { "request_id": "eb95e1b8-d245-41b1-bbd0-cc1073e68bfd" } } ``` ## Get Thread By ID **get** `/v1/omni-ai/threads/{thread_id}` Get a specific thread. Returns metadata (title, timestamps) for a single thread. Does not include messages — use `GET /omni-ai/threads/{thread_id}/messages` for conversation history. ### Path Parameters - `thread_id: string` ### Query Parameters - `account_id: number` Account ID for the request ### Returns - `data: Thread` Thread metadata returned by list/get thread endpoints. - `id: string` - `created_at: string` - `title: string` - `updated_at: string` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/threads/$THREAD_ID \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "created_at": "2026-04-23T15:15:54.929830+00:00", "id": "019dbae9-73b3-7fe0-bd14-25fe57e91475", "title": "What is current price of AAPL?", "updated_at": "2026-04-23T15:15:54.929830+00:00" }, "metadata": { "request_id": "5683a394-6dd1-4843-8591-f102ced2e636" } } ``` ## Create Thread **post** `/v1/omni-ai/threads` Create a new conversation thread. Atomically creates a new thread and submits the first user turn. The response contains a `response_id` that should be polled via `GET /omni-ai/responses/{response_id}` for assistant output. Two creation modes are supported: - **instant** — provide `text` with a natural-language prompt. - **deep\_insights** — provide a `target` ticker and optional `thesis` for long-form research. ### Body Parameters - `account_id: number` - `type: "instant" or "deep_insights"` Thread creation mode. - `"instant"` - `"deep_insights"` - `capabilities: optional array of "PREFILL_ORDER" or "OPEN_CHART" or "OPEN_SCREENER" or "OPEN_ENTITLEMENT_CONSENT"` - `"PREFILL_ORDER"` - `"OPEN_CHART"` - `"OPEN_SCREENER"` - `"OPEN_ENTITLEMENT_CONSENT"` - `target: optional object { ticker, type }` Deep-insights target payload. - `ticker: string` - `type: "ticker"` Deep-insights target type. Launch supports ticker-only. - `"ticker"` - `text: optional string` - `thesis: optional string` ### Returns - `data: CreateThreadResponse` Response payload for thread creation. - `response_id: string` - `thread_id: string` - `user_message_id: string` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/threads \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" \ -d '{ "account_id": 19816, "type": "instant" }' ``` #### Response ```json { "data": { "response_id": "019dbae9-73b4-7760-a947-8b4bcab57c49", "thread_id": "019dbae9-73b3-7fe0-bd14-25fe57e91475", "user_message_id": "019dbae9-73b8-75b2-9c06-ac348927696d" }, "metadata": { "request_id": "f7a9ad4d-753a-403e-aa0e-ca151f991a81" } } ``` ## Get Thread Response **get** `/v1/omni-ai/threads/{thread_id}/response` Get the active response for a thread. Convenience endpoint to look up the currently active response for a thread without knowing the `response_id`. Useful when reloading a thread whose last finalized message is a `USER` message — this indicates an assistant turn is likely in progress. Returns **404** if no active response exists (the thread is idle). ### Path Parameters - `thread_id: string` ### Query Parameters - `account_id: number` Account ID for the request ### Returns - `data: Response` Dynamic pollable response. - `id: string` - `status: ResponseStatus` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` - `thread_id: string` - `user_message_id: string` - `content: optional ResponseContent` Dynamic response content container. May include thinking parts. - `parts: array of ResponseContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` - `output_message_id: optional string` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/threads/$THREAD_ID/response \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": { "content": { "parts": [ { "text": "", "type": "text" }, { "thoughts": [ "[1/4] Running parallel analysis on AAPL -- fundamentals, technicals, sentiment, and macro..." ], "type": "thinking" } ] }, "id": "019dbb03-cf23-74e1-9c31-ef0136ff7fed", "output_message_id": "019dbb03-cf32-74d1-906b-a148d4be3da9", "status": "running", "thread_id": "019dbb03-cf22-7da0-a663-f51c756efa07", "user_message_id": "019dbb03-cf24-7b03-8286-5bfc2411b052" }, "metadata": { "request_id": "927a85a6-b11b-4cc5-a2cd-3f46ae64e85d" } } ``` ## Get Messages **get** `/v1/omni-ai/threads/{thread_id}/messages` List finalized messages in a thread. Returns **finalized** messages in chronological order. Messages from in-progress assistant turns are excluded — use `GET /omni-ai/threads/{thread_id}/response` or `GET /omni-ai/responses/{response_id}` for live output. If the last finalized message has role `USER`, an active response likely exists and should be polled separately. ### Path Parameters - `thread_id: string` ### Query Parameters - `account_id: number` Account ID for the request - `page_size: optional number` The number of items to return per page. Only used when page_token is not provided. - `page_token: optional string` Token for retrieving the next or previous page of results. Contains encoded pagination state; when provided, page_size is ignored. ### Returns - `data: MessageList` - `id: string` - `content: MessageContent` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `created_at: string` - `outcome: MessageOutcome` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: MessageRole` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: number` - `thread_id: string` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/threads/$THREAD_ID/messages \ -H "Authorization: Bearer $API_KEY" ``` #### Response ```json { "data": [ { "content": { "parts": [ { "text": "How are the markets doing today?", "type": "text" } ] }, "created_at": "2026-04-16T09:20:17.274943+00:00", "id": "019d9597-5983-7691-8281-7ce264127740", "outcome": "completed", "role": "USER", "seq": 1, "thread_id": "019d9597-597c-7571-a0c9-a49c0e51f6eb" }, { "content": { "parts": [ { "text": "**Pre-market as of 7:30 AM ET**\n\n ...", "type": "text" }, { "payload": { "actionButtons": [ { "buttonId": "btn_followup_0", "label": "Check my positions", "prompt": { "prompt": "What are my current positions?" } } ] }, "type": "suggested_actions" } ] }, "created_at": "2026-04-16T09:20:17.309212+00:00", "id": "019d9597-599c-7132-a7de-e5c21eaaab77", "outcome": "completed", "role": "ASSISTANT", "seq": 2, "thread_id": "019d9597-597c-7571-a0c9-a49c0e51f6eb" } ], "metadata": { "request_id": "664c0f85-cdab-4fac-afe3-8ecc0148cd4a" } } ``` ## Create Message **post** `/v1/omni-ai/threads/{thread_id}/messages` Continue an existing conversation thread. Appends a new user message to the thread and starts an assistant response. Only one response may be active per thread at a time — if the previous turn is still in progress, this endpoint returns **409 Conflict**. Wait for the active response to reach a terminal status before submitting the next turn. Poll the returned `response_id` via `GET /omni-ai/responses/{response_id}` for assistant output. ### Path Parameters - `thread_id: string` ### Body Parameters - `account_id: number` - `text: string` - `capabilities: optional array of "PREFILL_ORDER" or "OPEN_CHART" or "OPEN_SCREENER" or "OPEN_ENTITLEMENT_CONSENT"` - `"PREFILL_ORDER"` - `"OPEN_CHART"` - `"OPEN_SCREENER"` - `"OPEN_ENTITLEMENT_CONSENT"` ### Returns - `data: CreateMessageResponse` Response payload for continuing a thread with a new message. - `response_id: string` - `thread_id: string` - `user_message_id: string` ### Example ```http curl https://api.clearstreet.com/v1/omni-ai/threads/$THREAD_ID/messages \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $API_KEY" \ -d '{ "account_id": 19816, "text": "Compare that to AMD." }' ``` #### Response ```json { "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" } } ``` ## Domain Types ### Create Message Response - `CreateMessageResponse object { 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 Thread Response - `CreateThreadResponse object { response_id, thread_id, user_message_id }` Response payload for thread creation. - `response_id: string` - `thread_id: string` - `user_message_id: string` ### Message - `Message object { id, content, created_at, 5 more }` Final immutable message. - `id: string` - `content: MessageContent` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `created_at: string` - `outcome: MessageOutcome` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: MessageRole` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: number` - `thread_id: string` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` ### Message Content - `MessageContent object { parts }` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` ### Message Content Part - `MessageContentPart = ContentPartTextPayload or ContentPartStructuredActionPayload or ContentPartChartPayload or 2 more` Final immutable content part visible on persisted messages. - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` ### Message List - `MessageList = array of Message` - `id: string` - `content: MessageContent` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `created_at: string` - `outcome: MessageOutcome` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: MessageRole` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: number` - `thread_id: string` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` ### Message Outcome - `MessageOutcome = "completed" or "errored" or "canceled"` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` ### Message Role - `MessageRole = "USER" or "ASSISTANT"` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` ### Thread - `Thread object { id, created_at, title, updated_at }` Thread metadata returned by list/get thread endpoints. - `id: string` - `created_at: string` - `title: string` - `updated_at: string` ### Thread List - `ThreadList = array of Thread` - `id: string` - `created_at: string` - `title: string` - `updated_at: string` ### Thread Get Threads Response - `ThreadGetThreadsResponse = BaseResponse` - `data: ThreadList` - `id: string` - `created_at: string` - `title: string` - `updated_at: string` ### Thread Get Thread By ID Response - `ThreadGetThreadByIDResponse = BaseResponse` - `data: Thread` Thread metadata returned by list/get thread endpoints. - `id: string` - `created_at: string` - `title: string` - `updated_at: string` ### Thread Create Thread Response - `ThreadCreateThreadResponse = BaseResponse` - `data: CreateThreadResponse` Response payload for thread creation. - `response_id: string` - `thread_id: string` - `user_message_id: string` ### Thread Get Thread Response Response - `ThreadGetThreadResponseResponse = BaseResponse` - `data: Response` Dynamic pollable response. - `id: string` - `status: ResponseStatus` Dynamic lifecycle status for a pollable response. - `"queued"` - `"running"` - `"succeeded"` - `"failed"` - `"canceled"` - `thread_id: string` - `user_message_id: string` - `content: optional ResponseContent` Dynamic response content container. May include thinking parts. - `parts: array of ResponseContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartThinkingPayload` Thinking content part shown on dynamic response polling. - `type: "thinking"` - `"thinking"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` - `output_message_id: optional string` ### Thread Get Messages Response - `ThreadGetMessagesResponse = BaseResponse` - `data: MessageList` - `id: string` - `content: MessageContent` Finalized immutable message content container. Never includes thinking parts. - `parts: array of MessageContentPart` - `ContentPartTextPayload` Text content part. - `type: "text"` - `"text"` - `ContentPartStructuredActionPayload` Structured action content part. - `type: "structured_action"` - `"structured_action"` - `ContentPartChartPayload` Chart payload content part. - `type: "chart"` - `"chart"` - `ContentPartSuggestedActionsPayload` Suggested actions payload content part. - `type: "suggested_actions"` - `"suggested_actions"` - `ContentPartCustomPayload` Escape-hatch custom payload content part. - `type: "custom"` - `"custom"` - `created_at: string` - `outcome: MessageOutcome` Immutable terminal outcome for a finalized assistant message. - `"completed"` - `"errored"` - `"canceled"` - `role: MessageRole` Finalized message role in the public contract. - `"USER"` - `"ASSISTANT"` - `seq: number` - `thread_id: string` - `error: optional ErrorStatus` Shared sanitized error payload. - `code: string` - `message: string` - `details: optional unknown` ### Thread Create Message Response - `ThreadCreateMessageResponse = BaseResponse` - `data: CreateMessageResponse` Response payload for continuing a thread with a new message. - `response_id: string` - `thread_id: string` - `user_message_id: string`