> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracecat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Message

> Send a message to the agent session with streaming response.

This endpoint combines message sending with streaming response,
compatible with Vercel's AI SDK useChat hook. It:
1. Accepts Vercel UI message format or continuation requests
2. Starts the agent execution
3. Streams the response back in Vercel's data protocol format



## OpenAPI

````yaml https://platform.tracecat.com/api/openapi.json post /workspaces/{workspace_id}/agent/sessions/{session_id}/messages
openapi: 3.1.0
info:
  title: Tracecat API
  summary: Tracecat API
  description: The open source AI automation platform for security teams and agents.
  termsOfService: >-
    https://docs.google.com/document/d/e/2PACX-1vQvDe3SoVAPoQc51MgfGCP71IqFYX_rMVEde8zC4qmBCec5f8PLKQRdxa6tsUABT8gWAR9J-EVs2CrQ/pub
  contact:
    name: Tracecat Founders
    email: founders@tracecat.com
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.html
  version: '1'
servers:
  - url: /api
security: []
tags:
  - name: public
    description: Public facing endpoints
  - name: workflows
    description: Workflow management
  - name: actions
    description: Action management
  - name: triggers
    description: Workflow triggers
  - name: secrets
    description: Secret management
  - name: variables
    description: Workspace variable management
paths:
  /workspaces/{workspace_id}/agent/sessions/{session_id}/messages:
    post:
      tags:
        - agent-sessions
      summary: Send Message
      description: |-
        Send a message to the agent session with streaming response.

        This endpoint combines message sending with streaming response,
        compatible with Vercel's AI SDK useChat hook. It:
        1. Accepts Vercel UI message format or continuation requests
        2. Starts the agent execution
        3. Streams the response back in Vercel's data protocol format
      operationId: agent-sessions-send_message
      parameters:
        - name: session_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Session Id
        - name: workspace_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Workspace Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/VercelChatRequest'
                - $ref: '#/components/schemas/ContinueRunRequest'
              discriminator:
                propertyName: kind
                mapping:
                  vercel:
                    $ref: '#/components/schemas/VercelChatRequest'
                  continue:
                    $ref: '#/components/schemas/ContinueRunRequest'
              title: Request
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyCookie: []
        - ServiceAccountApiKeyBearer: []
components:
  schemas:
    VercelChatRequest:
      properties:
        kind:
          type: string
          const: vercel
          title: Kind
          default: vercel
        message:
          $ref: '#/components/schemas/UIMessage'
          description: User message in Vercel UI format
        model:
          type: string
          title: Model
          description: AI model to use
          default: gpt-4o-mini
        model_provider:
          type: string
          maxLength: 50
          minLength: 1
          title: Model Provider
          description: AI model provider
          default: openai
        base_url:
          anyOf:
            - type: string
              maxLength: 500
            - type: 'null'
          title: Base Url
          description: Optional base URL for the model provider
      type: object
      required:
        - message
      title: VercelChatRequest
      description: Vercel AI SDK format request with structured UI messages.
    ContinueRunRequest:
      properties:
        kind:
          type: string
          const: continue
          title: Kind
          default: continue
        decisions:
          items:
            $ref: '#/components/schemas/ApprovalDecision'
          type: array
          title: Decisions
        source:
          type: string
          enum:
            - inbox
            - slack
          title: Source
          description: >-
            Origin of the approval decision submission. Use 'inbox' for Tracecat
            UI/API and 'slack' for Slack actions.
          default: inbox
      type: object
      required:
        - decisions
      title: ContinueRunRequest
      description: Payload to continue a CE run after collecting approvals.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    UIMessage:
      properties:
        id:
          type: string
          title: Id
        role:
          type: string
          enum:
            - system
            - user
            - assistant
          title: Role
        metadata:
          anyOf:
            - {}
            - type: 'null'
          title: Metadata
        parts:
          items:
            anyOf:
              - $ref: '#/components/schemas/TextUIPart'
              - $ref: '#/components/schemas/ReasoningUIPart'
              - $ref: '#/components/schemas/SourceUrlUIPart'
              - $ref: '#/components/schemas/SourceDocumentUIPart'
              - $ref: '#/components/schemas/FileUIPart'
              - $ref: '#/components/schemas/StepStartUIPart'
              - $ref: '#/components/schemas/DynamicToolUIPartInputStreaming'
              - $ref: '#/components/schemas/DynamicToolUIPartInputAvailable'
              - $ref: '#/components/schemas/DynamicToolUIPartOutputAvailable'
              - $ref: '#/components/schemas/DynamicToolUIPartOutputError'
              - $ref: '#/components/schemas/ToolUIPartInputStreaming'
              - $ref: '#/components/schemas/ToolUIPartInputAvailable'
              - $ref: '#/components/schemas/ToolUIPartOutputAvailable'
              - $ref: '#/components/schemas/ToolUIPartOutputError'
              - $ref: '#/components/schemas/DataUIPart'
          type: array
          title: Parts
      additionalProperties: false
      type: object
      required:
        - id
        - role
        - parts
      title: UIMessage
      description: |-
        Pydantic model for AI SDK UI Messages, used for validation between
        frontend and backend.
    ApprovalDecision:
      properties:
        tool_call_id:
          type: string
          title: Tool Call Id
        action:
          type: string
          enum:
            - approve
            - override
            - deny
          title: Action
        override_args:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Override Args
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: >-
            Optional metadata captured with the decision (e.g. external actor
            identity).
      type: object
      required:
        - tool_call_id
        - action
      title: ApprovalDecision
      description: Operator decision for a pending approval.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    TextUIPart:
      properties:
        type:
          type: string
          const: text
          title: Type
        text:
          type: string
          title: Text
        state:
          type: string
          enum:
            - streaming
            - done
          title: State
        providerMetadata:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Providermetadata
      additionalProperties: false
      type: object
      required:
        - type
        - text
      title: TextUIPart
      description: A text part of a message.
    ReasoningUIPart:
      properties:
        type:
          type: string
          const: reasoning
          title: Type
        text:
          type: string
          title: Text
        state:
          type: string
          enum:
            - streaming
            - done
          title: State
        providerMetadata:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Providermetadata
      additionalProperties: false
      type: object
      required:
        - type
        - text
      title: ReasoningUIPart
      description: A reasoning part of a message.
    SourceUrlUIPart:
      properties:
        type:
          type: string
          const: source-url
          title: Type
        sourceId:
          type: string
          title: Sourceid
        url:
          type: string
          title: Url
        title:
          type: string
          title: Title
        providerMetadata:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Providermetadata
      additionalProperties: false
      type: object
      required:
        - type
        - sourceId
        - url
      title: SourceUrlUIPart
      description: A source URL part of a message.
    SourceDocumentUIPart:
      properties:
        type:
          type: string
          const: source-document
          title: Type
        sourceId:
          type: string
          title: Sourceid
        mediaType:
          type: string
          title: Mediatype
        title:
          type: string
          title: Title
        filename:
          type: string
          title: Filename
        providerMetadata:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Providermetadata
      additionalProperties: false
      type: object
      required:
        - type
        - sourceId
        - mediaType
        - title
      title: SourceDocumentUIPart
      description: A document source part of a message.
    FileUIPart:
      properties:
        type:
          type: string
          const: file
          title: Type
        mediaType:
          type: string
          title: Mediatype
        url:
          type: string
          title: Url
        filename:
          type: string
          title: Filename
        providerMetadata:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Providermetadata
      additionalProperties: false
      type: object
      required:
        - type
        - mediaType
        - url
      title: FileUIPart
      description: A file part of a message.
    StepStartUIPart:
      properties:
        type:
          type: string
          const: step-start
          title: Type
      additionalProperties: false
      type: object
      required:
        - type
      title: StepStartUIPart
      description: A step boundary part of a message.
    DynamicToolUIPartInputStreaming:
      properties:
        type:
          type: string
          const: dynamic-tool
          title: Type
        toolName:
          type: string
          title: Toolname
        toolCallId:
          type: string
          title: Toolcallid
        state:
          type: string
          const: input-streaming
          title: State
        input:
          title: Input
        output:
          type: 'null'
          title: Output
        errorText:
          type: 'null'
          title: Errortext
      additionalProperties: false
      type: object
      required:
        - type
        - toolName
        - toolCallId
        - state
      title: DynamicToolUIPartInputStreaming
    DynamicToolUIPartInputAvailable:
      properties:
        type:
          type: string
          const: dynamic-tool
          title: Type
        toolName:
          type: string
          title: Toolname
        toolCallId:
          type: string
          title: Toolcallid
        state:
          type: string
          const: input-available
          title: State
        input:
          title: Input
        output:
          type: 'null'
          title: Output
        errorText:
          type: 'null'
          title: Errortext
        callProviderMetadata:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Callprovidermetadata
      additionalProperties: false
      type: object
      required:
        - type
        - toolName
        - toolCallId
        - state
        - input
      title: DynamicToolUIPartInputAvailable
    DynamicToolUIPartOutputAvailable:
      properties:
        type:
          type: string
          const: dynamic-tool
          title: Type
        toolName:
          type: string
          title: Toolname
        toolCallId:
          type: string
          title: Toolcallid
        state:
          type: string
          const: output-available
          title: State
        input:
          title: Input
        output:
          title: Output
        errorText:
          type: 'null'
          title: Errortext
        callProviderMetadata:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Callprovidermetadata
        preliminary:
          type: boolean
          title: Preliminary
      additionalProperties: false
      type: object
      required:
        - type
        - toolName
        - toolCallId
        - state
        - input
        - output
      title: DynamicToolUIPartOutputAvailable
    DynamicToolUIPartOutputError:
      properties:
        type:
          type: string
          const: dynamic-tool
          title: Type
        toolName:
          type: string
          title: Toolname
        toolCallId:
          type: string
          title: Toolcallid
        state:
          type: string
          const: output-error
          title: State
        input:
          title: Input
        output:
          type: 'null'
          title: Output
        errorText:
          type: string
          title: Errortext
        callProviderMetadata:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Callprovidermetadata
      additionalProperties: false
      type: object
      required:
        - type
        - toolName
        - toolCallId
        - state
        - input
        - errorText
      title: DynamicToolUIPartOutputError
    ToolUIPartInputStreaming:
      properties:
        type:
          type: string
          title: Type
        toolCallId:
          type: string
          title: Toolcallid
        state:
          type: string
          const: input-streaming
          title: State
        input:
          title: Input
        providerExecuted:
          type: boolean
          title: Providerexecuted
        output:
          type: 'null'
          title: Output
        errorText:
          type: 'null'
          title: Errortext
      additionalProperties: false
      type: object
      required:
        - type
        - toolCallId
        - state
      title: ToolUIPartInputStreaming
    ToolUIPartInputAvailable:
      properties:
        type:
          type: string
          title: Type
        toolCallId:
          type: string
          title: Toolcallid
        state:
          type: string
          const: input-available
          title: State
        input:
          title: Input
        providerExecuted:
          type: boolean
          title: Providerexecuted
        output:
          type: 'null'
          title: Output
        errorText:
          type: 'null'
          title: Errortext
        callProviderMetadata:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Callprovidermetadata
      additionalProperties: false
      type: object
      required:
        - type
        - toolCallId
        - state
        - input
      title: ToolUIPartInputAvailable
    ToolUIPartOutputAvailable:
      properties:
        type:
          type: string
          title: Type
        toolCallId:
          type: string
          title: Toolcallid
        state:
          type: string
          const: output-available
          title: State
        input:
          title: Input
        output:
          title: Output
        errorText:
          type: 'null'
          title: Errortext
        providerExecuted:
          type: boolean
          title: Providerexecuted
        callProviderMetadata:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Callprovidermetadata
        preliminary:
          type: boolean
          title: Preliminary
      additionalProperties: false
      type: object
      required:
        - type
        - toolCallId
        - state
        - input
        - output
      title: ToolUIPartOutputAvailable
    ToolUIPartOutputError:
      properties:
        type:
          type: string
          title: Type
        toolCallId:
          type: string
          title: Toolcallid
        state:
          type: string
          const: output-error
          title: State
        input:
          title: Input
        rawInput:
          title: Rawinput
        output:
          type: 'null'
          title: Output
        errorText:
          type: string
          title: Errortext
        providerExecuted:
          type: boolean
          title: Providerexecuted
        callProviderMetadata:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Callprovidermetadata
      additionalProperties: false
      type: object
      required:
        - type
        - toolCallId
        - state
        - errorText
      title: ToolUIPartOutputError
    DataUIPart:
      properties:
        type:
          type: string
          pattern: ^data-.+$
          title: Type
        id:
          type: string
          title: Id
        data:
          title: Data
      additionalProperties: false
      type: object
      required:
        - type
        - data
      title: DataUIPart
      description: A custom data part, where type matches 'data-...'.
  securitySchemes:
    APIKeyCookie:
      type: apiKey
      in: cookie
      name: fastapiusersauth
    ServiceAccountApiKeyBearer:
      type: http
      description: Tracecat service account API key.
      scheme: bearer

````