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

# Send a turn and wait for the full response



## OpenAPI

````yaml /openapi/v3.yaml post /api/v2/assistant/chat
openapi: 3.1.0
info:
  title: Semicola Exchange API
  version: 3.0.0-preview
  description: >-
    Platform endpoints of Semicola: sign-in and accounts, members and keys,
    billing, notifications, the Semi assistant (chat stream, confirmations,
    conversations), the MCP App widget host and realtime feeds. Typed agent
    tools live on the MCP server at /mcp/v3.
servers:
  - url: https://api.semicola.com
security:
  - bearerAuth: []
  - sessionCookie: []
tags:
  - name: Auth
  - name: Accounts
  - name: Billing
  - name: Notifications
  - name: Assistant
  - name: Widget host
  - name: Realtime
  - name: Demo
paths:
  /api/v2/assistant/chat:
    post:
      tags:
        - Assistant
      summary: Send a turn and wait for the full response
      operationId: postAssistantChat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  maxLength: 32000
                conversationUid:
                  type: string
                  minLength: 6
                scopeType:
                  type: string
                  enum:
                    - customer
                    - advertiser
                scopeId:
                  type: string
                  minLength: 1
                attachments:
                  maxItems: 5
                  type: array
                  items:
                    type: object
                    properties:
                      attachmentId:
                        type: string
                        minLength: 1
                      filename:
                        type: string
                        minLength: 1
                      mimeType:
                        type: string
                        minLength: 1
                      bytes:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                    required:
                      - attachmentId
                      - filename
                      - mimeType
                      - bytes
                preferredLanguage:
                  type: string
                  enum:
                    - ar
                    - de
                    - en
                    - es
                    - fr
                    - hi
                    - it
                    - ko
                    - nl
                    - pl
                    - pt
                    - sv
                    - tr
                    - ja
                    - zh
                modelContext:
                  type: array
                  items:
                    type: object
                    properties:
                      resourceUri:
                        type: string
                        pattern: ^ui:\/\/semicola\/[a-z0-9-]+\/mcp-app\.html$
                      text:
                        type: string
                      data: {}
                    required:
                      - text
                pageContext:
                  type: object
                  properties:
                    route:
                      type: string
                    title:
                      type: string
                    extra:
                      type: object
                      properties:
                        workspace:
                          type: string
                        scopeName:
                          type: string
                        intent:
                          type: string
                        entity:
                          type: string
                        feature:
                          type: string
                        learningMode:
                          type: string
                        diagnosticsSourceId:
                          type: string
                        diagnosticsSourceName:
                          type: string
                  required:
                    - route
              required:
                - prompt
                - scopeType
                - scopeId
                - attachments
                - pageContext
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    anyOf:
                      - type: object
                        properties:
                          conversationUid:
                            type: string
                            minLength: 6
                          answer:
                            type: string
                          toolsUsed:
                            type: array
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                input: {}
                                output: {}
                                isError:
                                  type: boolean
                              required:
                                - name
                                - input
                                - output
                                - isError
                              additionalProperties: false
                          mcpAppWidget:
                            type: object
                            properties:
                              kind:
                                type: string
                                enum:
                                  - page
                                  - task
                                  - glance
                              resourceUri:
                                type: string
                                pattern: ^ui:\/\/semicola\/[a-z0-9-]+\/mcp-app\.html$
                              title:
                                type: string
                              description:
                                type: string
                              data: {}
                              suppressUserMessage:
                                type: boolean
                            required:
                              - kind
                              - resourceUri
                              - title
                              - description
                              - data
                              - suppressUserMessage
                            additionalProperties: false
                          pendingConfirmations:
                            type: array
                            items:
                              type: object
                              properties:
                                status:
                                  type: string
                                  const: pending_confirmation
                                confirmationUid:
                                  type: string
                                  minLength: 5
                                toolName:
                                  type: string
                                toolKey:
                                  type: string
                                summary:
                                  type: string
                                policy:
                                  type: string
                                  enum:
                                    - always
                                    - tainted
                                resolvedParams:
                                  type: object
                                  propertyNames:
                                    type: string
                                  additionalProperties: {}
                                writeExecuted:
                                  type: boolean
                                  const: false
                                plainAffirmativeAccepted:
                                  type: boolean
                                expiresAt:
                                  type: string
                                  format: date-time
                                  pattern: >-
                                    ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                                risk:
                                  type: string
                                  enum:
                                    - none
                                    - durable
                                    - spend
                                    - external
                              required:
                                - status
                                - confirmationUid
                                - toolName
                                - toolKey
                                - summary
                                - policy
                                - resolvedParams
                                - writeExecuted
                                - plainAffirmativeAccepted
                                - expiresAt
                              additionalProperties: false
                          customerSwitch:
                            type: object
                            properties:
                              customerId:
                                type: integer
                                exclusiveMinimum: 0
                                maximum: 9007199254740991
                              customerName:
                                type: string
                              accountType:
                                anyOf:
                                  - type: string
                                    enum:
                                      - BUYER
                                      - SELLER
                                      - PARTNER
                                  - type: 'null'
                            required:
                              - customerId
                              - customerName
                              - accountType
                            additionalProperties: false
                        required:
                          - conversationUid
                          - answer
                          - toolsUsed
                          - pendingConfirmations
                        additionalProperties: false
                      - type: 'null'
                  error:
                    anyOf:
                      - type: object
                        properties:
                          code:
                            type: string
                          message:
                            type: string
                          field:
                            type: string
                          details: {}
                        required:
                          - code
                          - message
                        additionalProperties: false
                      - type: 'null'
                required:
                  - data
                  - error
                additionalProperties: false
        default:
          description: >-
            Error envelope `{data: null, error: {code, message, field?,
            details?}}`.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or OAuth access token.
    sessionCookie:
      type: apiKey
      in: cookie
      name: sc_session

````