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

# Create a conversation thread with initial turn

> Create a new thread and immediately ask a query in a single request. 
This endpoint combines thread creation and turn creation to reduce round trips. 

Supports synchronous and background processing modes. Streaming is not supported.If you need to use streaming mode then directly use the endpoint to create a turn within a thread

Note: `chat_setting_id` has been deprecated, now use `agent_id` instead, `chat_settings_id` is still supported for back-compatibility purposes. If no `agent_id` nor `chat_setting_id` is provided, the default agent for the company is used.



## OpenAPI

````yaml /api-reference/openapi-v3.yaml post /api/v3/threads/turns
openapi: 3.1.0
info:
  title: LightOn API
  version: 3.15.0 (v3)
  description: >-
    LightOn gives you an API to search, parse, and ingest documents at scale.
    Build knowledge-retrieval pipelines without managing vector databases or OCR
    models.
servers:
  - url: https://paradigm.lighton.ai
security: []
tags:
  - name: Agents
    description: Operations about agents
  - name: Threads
    description: Operations about agents conversation threads
  - name: Tools
    description: Operations about native tools
  - name: Models
    description: Operations about AI models
  - name: MCP
    description: Operations about MCP servers
  - name: Sources
    description: Operations about sources used by agents conversation threads
  - name: Artifacts
    description: Operations about artifacts generated by agents conversation threads
  - name: Agent
    description: >-
      Operations about agents (deprecated). Please use the 'Agents' API
      component instead.
  - name: Files
    description: Operations about files
  - name: Facets
    description: Operations about facets
  - name: Tags
    description: Operations about tags
  - name: Workspaces
    description: Operations about workspaces
  - name: Files Processing
    description: Operations about files processing
  - name: Users
    description: Operations about users
  - name: API Keys
    description: Operations about API keys
  - name: User Groups
    description: Operations about user groups
  - name: SCIM
    description: Operations about SCIM
paths:
  /api/v3/threads/turns:
    post:
      tags:
        - Threads
      summary: Create a conversation thread with initial turn
      description: >-
        Create a new thread and immediately ask a query in a single request. 

        This endpoint combines thread creation and turn creation to reduce round
        trips. 


        Supports synchronous and background processing modes. Streaming is not
        supported.If you need to use streaming mode then directly use the
        endpoint to create a turn within a thread


        Note: `chat_setting_id` has been deprecated, now use `agent_id` instead,
        `chat_settings_id` is still supported for back-compatibility purposes.
        If no `agent_id` nor `chat_setting_id` is provided, the default agent
        for the company is used.
      operationId: api_v3_threads_create_with_turn
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateThreadWithTurnRequest'
            examples:
              CreateThreadWithSimpleQuery:
                value:
                  agent_id: 1
                  query: What is the capital of France?
                summary: Create thread with simple query
              CreateThreadWithBackgroundProcessing:
                value:
                  agent_id: 1
                  query: What is the capital of France?
                  background: true
                summary: Create thread with background processing
              CreateThreadWithResponseFormat:
                value:
                  agent_id: 1
                  query: What is the capital of France?
                  response_format:
                    type: object
                    properties:
                      capital:
                        type: string
                      country:
                        type: string
                    required:
                      - capital
                      - country
                summary: Create thread with response format
              CreateThreadWithForcedTool:
                value:
                  agent_id: 1
                  query: 781+8171?
                  force_tool: code_execution
                summary: Create thread with forced tool
              CreateThreadWithImmediateFinalAnswer:
                value:
                  agent_id: 1
                  query: What is the capital of France?
                  immediate_final_answer: true
                summary: Create thread with immediate final answer
              CreateThreadWithCustomDocumentSearchParameters:
                value:
                  agent_id: 1
                  query: What is the company revenue?
                  force_tool: document_search
                  tool_parameters:
                    document_search:
                      top_k: 20
                      top_n: 10
                summary: Create thread with custom document search parameters
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateThreadWithTurnRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateThreadWithTurnRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnswerResponse'
          description: Final answer returned synchronously.
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnswerResponse'
          description: >-
            Answer accepted and still processing. The payload contains the
            current answer resource; clients should poll or listen for updates
            until the status is final.
        '503':
          description: >-
            API is under maintenance. Check `GET /api/v3/system/status` for
            active periods and retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceMaintenance503'
      security:
        - bearerAuth: []
components:
  schemas:
    CreateThreadWithTurnRequest:
      type: object
      description: >-
        Combined serializer for creating a thread and immediately creating a
        turn (answer).


        This serializer composes the existing thread and answer serializers to
        maximize

        code reuse and maintain consistent validation logic.


        Note: The 'stream' parameter is not supported for this endpoint.
      properties:
        name:
          type: string
          description: Thread name
          maxLength: 255
        agent_id:
          type: integer
          description: >-
            ID of the agent to use. If not provided, uses the default agent for
            the company.
        chat_setting_id:
          type: integer
          description: >-
            DEPRECATED: Use 'agent_id' instead. ID of the chat setting to use.
            If not provided, uses the default agent for the company.
        is_ephemeral:
          type: boolean
          default: false
          description: Enable ephemeral mode
        query:
          type:
            - string
            - 'null'
          description: The user's query
        force_tool:
          type: string
          description: Name of tool to force use
        suggested_query_id:
          type: integer
          description: ID of a suggested query
        force_mcp_server:
          type: string
          description: Name of MCP server to restrict tools to
        immediate_final_answer:
          type: boolean
          default: false
          description: Skip tool calls and return final answer immediately
        background:
          type: boolean
          default: false
          description: Process asynchronously and return immediately
        system_prompt_suffix:
          type: string
          description: Additional system prompt instructions
          maxLength: 5000
        max_steps:
          type: integer
          maximum: 20
          minimum: 1
          default: 8
          description: Maximum reasoning steps
        response_format:
          description: JSON schema specifying response structure
        tool_parameters:
          description: Tool-specific parameters
        workspace_ids:
          type: array
          items:
            type: integer
          description: Workspaces to search for documents
        file_ids:
          type: array
          items:
            type: integer
          description: Specific files to include
        tag_ids:
          type: array
          items:
            type: integer
          description: Specific tags to include
        private_scope:
          type: boolean
          description: Include user's private workspace
        company_scope:
          type: boolean
          description: >-
            Deprecated. True expands to every shared workspace where the COMPANY
            group is a member (at any role). Will be removed in a future API
            version — pass explicit workspace_ids instead.
    AnswerResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          default: turn
        thread:
          type: string
        status:
          $ref: '#/components/schemas/AnswerResponseStatusEnum'
        error:
          oneOf:
            - $ref: '#/components/schemas/AnswerError'
            - type: 'null'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/MessageResponse'
        created_at:
          type: string
          format: date-time
        liked:
          type:
            - boolean
            - 'null'
      required:
        - created_at
        - id
        - messages
        - status
        - thread
    ServiceMaintenance503:
      type: object
      description: >-
        Returned by the maintenance middleware when the requested endpoint is
        blocked.
      required:
        - detail
        - error
        - mode
      properties:
        detail:
          type: string
          example: System is under maintenance.
        error:
          type: string
          example: service_maintenance
        mode:
          type: string
          enum:
            - full_shutdown
            - warning_banner
          description: >-
            `full_shutdown` blocks all traffic; `warning_banner` also blocks and
            shows a dismissible toast.
        reason:
          type: string
          description: Operator-supplied maintenance reason, if any.
        started_at:
          type: string
          format: date-time
        endpoint_category_names:
          type: array
          items:
            type: string
          description: >-
            Non-empty only for category-scoped periods. Empty means all
            endpoints are affected.
    AnswerResponseStatusEnum:
      enum:
        - running
        - completed
        - failed
        - cancelled
        - cancelling
      type: string
      description: |-
        * `running` - running
        * `completed` - completed
        * `failed` - failed
        * `cancelled` - cancelled
        * `cancelling` - cancelling
    AnswerError:
      type: object
      properties:
        code:
          type:
            - string
            - 'null'
        message:
          type:
            - string
            - 'null'
    MessageResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          default: message
        role:
          $ref: '#/components/schemas/MessageResponseRoleEnum'
        parts:
          type: array
          items:
            $ref: '#/components/schemas/MessagePartResponse'
        force_tool:
          oneOf:
            - $ref: '#/components/schemas/ToolResponse'
            - type: 'null'
        immediate_final_answer:
          type:
            - boolean
            - 'null'
        created_at:
          type: string
          format: date-time
      required:
        - created_at
        - id
        - parts
        - role
    MessageResponseRoleEnum:
      enum:
        - user
        - assistant
      type: string
      description: |-
        * `user` - user
        * `assistant` - assistant
    MessagePartResponse:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/MessagePartResponseTypeEnum'
        text:
          type:
            - string
            - 'null'
        reasoning:
          type:
            - string
            - 'null'
        tool_call:
          oneOf:
            - $ref: '#/components/schemas/ToolCallResponse'
            - type: 'null'
        document:
          oneOf:
            - $ref: '#/components/schemas/DocumentPart'
            - type: 'null'
        workspace:
          oneOf:
            - $ref: '#/components/schemas/WorkspacePart'
            - type: 'null'
        tag:
          oneOf:
            - $ref: '#/components/schemas/Tag'
            - type: 'null'
      required:
        - type
    ToolResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          default: tool
        name:
          type: string
        type:
          $ref: '#/components/schemas/ToolTypeEnum'
        mcp_server_name:
          type:
            - string
            - 'null'
        require_document:
          type:
            - boolean
            - 'null'
        accepted_file_types:
          type:
            - array
            - 'null'
          items:
            type: string
      required:
        - id
        - name
        - type
    MessagePartResponseTypeEnum:
      enum:
        - text
        - reasoning
        - tool_call
        - document
        - workspace
        - tag
      type: string
      description: |-
        * `text` - text
        * `reasoning` - reasoning
        * `tool_call` - tool_call
        * `document` - document
        * `workspace` - workspace
        * `tag` - tag
    ToolCallResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          default: tool_call
        tool:
          $ref: '#/components/schemas/ToolResponse'
        tool_args:
          type:
            - object
            - 'null'
          additionalProperties: {}
        steps:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ToolStepResponse'
        result:
          oneOf:
            - $ref: '#/components/schemas/ToolCallResultResponse'
            - type: 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - created_at
        - id
        - tool
        - updated_at
    DocumentPart:
      type: object
      properties:
        id:
          type: string
      required:
        - id
    WorkspacePart:
      type: object
      properties:
        id:
          type: string
        name:
          type:
            - string
            - 'null'
        type:
          oneOf:
            - $ref: '#/components/schemas/WorkspacePartTypeEnum'
            - $ref: '#/components/schemas/NullEnum'
        files_count:
          type:
            - integer
            - 'null'
      required:
        - id
    Tag:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the tag
        tag:
          type: string
          description: Tag name
      required:
        - id
        - tag
    ToolTypeEnum:
      enum:
        - native
        - mcp
      type: string
      description: |-
        * `native` - native
        * `mcp` - mcp
    ToolStepResponse:
      type: object
      properties:
        status:
          type: string
        progress_report:
          oneOf:
            - $ref: '#/components/schemas/ProgressReportResponse'
            - type: 'null'
        created_at:
          type: string
          format: date-time
      required:
        - created_at
        - status
    ToolCallResultResponse:
      type: object
      properties:
        text:
          type:
            - string
            - 'null'
        file_artifacts:
          type:
            - array
            - 'null'
          items:
            type: object
            additionalProperties: {}
        web_sources:
          type:
            - array
            - 'null'
          items:
            type: object
            additionalProperties: {}
        chunk_sources:
          type:
            - array
            - 'null'
          items:
            type: object
            additionalProperties: {}
        document_sources:
          type:
            - array
            - 'null'
          items:
            type: object
            additionalProperties: {}
        timings:
          type:
            - object
            - 'null'
          additionalProperties:
            type: number
            format: double
    WorkspacePartTypeEnum:
      enum:
        - shared
        - personal
        - public
      type: string
      description: |-
        * `shared` - shared
        * `personal` - personal
        * `public` - public
    NullEnum:
      type: 'null'
    ProgressReportResponse:
      type: object
      properties:
        progress_percentage:
          type:
            - number
            - 'null'
          format: double
        current_progress_text:
          type:
            - string
            - 'null'
        time_remaining_estimate:
          type:
            - integer
            - 'null'
        metadata:
          type:
            - object
            - 'null'
          additionalProperties: {}
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer authentication header of the form `Bearer <token>`, where
        `<token>` is your auth token.

````