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

# Execute conversation run

> Executes a conversation run within an existing thread to process AI interactions. This is the core AI processing endpoint - sends messages to the AI assistant and initiates processing. Used for both real-time chat interactions and clinical note extraction from transcriptions. The run executes asynchronously and can be monitored via the join endpoint.




## OpenAPI

````yaml /openapi/openapi.yaml post /v1/lang-graph/threads/{threadId}/runs
openapi: 3.0.3
info:
  title: Sofia Clinical Documentation API
  version: 1.0.0
  description: >
    Comprehensive AI-powered clinical documentation platform that includes
    ICD-10 medical coding, transcription management, AI conversation threads,
    and clinical note generation with support for various clinical templates
    (SOAP, BIRP, etc.).
servers:
  - url: https://{your-prod-endpoint}
    description: Production (provided after deployment)
  - url: https://{your-dev-endpoint}
    description: Development (provided upon request)
security:
  - bearerAuth: []
paths:
  /v1/lang-graph/threads/{threadId}/runs:
    post:
      summary: Execute conversation run
      description: >
        Executes a conversation run within an existing thread to process AI
        interactions. This is the core AI processing endpoint - sends messages
        to the AI assistant and initiates processing. Used for both real-time
        chat interactions and clinical note extraction from transcriptions. The
        run executes asynchronously and can be monitored via the join endpoint.
      operationId: executeRun
      parameters:
        - in: path
          name: threadId
          required: true
          schema:
            type: string
          description: The thread identifier to execute the run in
          example: thread-abc123
        - in: header
          name: x-is-chat
          schema:
            type: boolean
          required: false
          description: >-
            Boolean flag to determine assistant type (true = chat/scribe, false
            = extraction)
          example: true
        - in: header
          name: x-doctor
          schema:
            type: string
          required: true
          description: Doctor identifier for tracking and auditing
          example: dr_123
        - in: header
          name: x-patient
          schema:
            type: string
          required: false
          description: Patient identifier for tracking and auditing
          example: pt_456
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunExecuteRequest'
            example:
              input:
                messages:
                  - role: user
                    content: Hello, how can you help me today?
              config:
                configurable:
                  thread_id: thread-abc123
      responses:
        '201':
          description: Run created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunExecuteResponse'
              example:
                run_id: run-xyz789
                thread_id: thread-abc123
                status: pending
                created_at: '2023-10-09T10:00:00.000Z'
        '400':
          description: Bad request (invalid input or missing thread_id)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Thread not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                error: Not Found
                details: Thread with id 'thread-abc123' not found
components:
  schemas:
    RunExecuteRequest:
      type: object
      required:
        - input
        - config
      properties:
        input:
          type: object
          required:
            - messages
          properties:
            messages:
              type: array
              description: Array of conversation messages
              items:
                type: object
                required:
                  - role
                  - content
                properties:
                  role:
                    type: string
                    enum:
                      - user
                      - assistant
                      - system
                    description: Role of the message sender
                    example: user
                  content:
                    type: string
                    description: Message content
                    example: Hello, how can you help me today?
        config:
          type: object
          required:
            - configurable
          properties:
            configurable:
              type: object
              required:
                - thread_id
              properties:
                thread_id:
                  type: string
                  description: Thread identifier for this run
                  example: thread-abc123
    RunExecuteResponse:
      type: object
      required:
        - run_id
        - thread_id
        - status
        - created_at
      properties:
        run_id:
          type: string
          description: Unique run identifier
          example: run-xyz789
        thread_id:
          type: string
          description: Associated thread identifier
          example: thread-abc123
        status:
          type: string
          enum:
            - pending
            - running
            - completed
            - failed
          description: Current status of the run
          example: pending
        created_at:
          type: string
          format: date-time
          description: Timestamp when run was created
          example: '2023-10-09T10:00:00.000Z'
    Error:
      type: object
      required:
        - success
        - error
        - details
      properties:
        success:
          type: boolean
          enum:
            - false
          description: Always false for error responses
        error:
          type: string
          description: Error name/type
          example: Bad Request
        details:
          type: string
          description: Detailed error message
          example: Either medical_note or pdf_file must be provided
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token for API authentication

````