> ## 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.0.3
info:
  title: Paradigm API
  version: xenial-xerus (v3)
  description: >-
    A versatile and adaptable tool designed to integrate Generative AI into your
    applications
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: Files Processing
    description: Operations about files processing
  - name: Tags
    description: Operations about tags
  - name: Workspaces
    description: Operations about workspaces
  - name: Users
    description: Operations about users
  - name: User Groups
    description: Operations about user groups
  - name: Companies
    description: Operations about companies
  - 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_turns_create
      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.
      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
          nullable: true
          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: Include company's workspace
    AnswerResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          default: turn
        thread:
          type: string
        status:
          $ref: '#/components/schemas/AnswerResponseStatusEnum'
        error:
          allOf:
            - $ref: '#/components/schemas/AnswerError'
          nullable: true
        messages:
          type: array
          items:
            $ref: '#/components/schemas/MessageResponse'
        created_at:
          type: string
          format: date-time
        liked:
          type: boolean
          nullable: true
      required:
        - created_at
        - id
        - messages
        - status
        - thread
    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
          nullable: true
        message:
          type: string
          nullable: true
    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:
          allOf:
            - $ref: '#/components/schemas/ToolResponse'
          nullable: true
        immediate_final_answer:
          type: boolean
          nullable: true
        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
          nullable: true
        reasoning:
          type: string
          nullable: true
        tool_call:
          allOf:
            - $ref: '#/components/schemas/ToolCallResponse'
          nullable: true
        document:
          allOf:
            - $ref: '#/components/schemas/DocumentPart'
          nullable: true
        workspace:
          allOf:
            - $ref: '#/components/schemas/WorkspacePart'
          nullable: true
        tag:
          allOf:
            - $ref: '#/components/schemas/Tag'
          nullable: true
      required:
        - type
    ToolResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          default: tool
        name:
          type: string
        type:
          $ref: '#/components/schemas/Type310Enum'
        mcp_server_name:
          type: string
          nullable: true
        require_document:
          type: boolean
          nullable: true
        accepted_file_types:
          type: array
          items:
            type: string
          nullable: true
      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
          additionalProperties: {}
          nullable: true
        steps:
          type: array
          items:
            $ref: '#/components/schemas/ToolStepResponse'
          nullable: true
        result:
          allOf:
            - $ref: '#/components/schemas/ToolCallResultResponse'
          nullable: true
        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
          nullable: true
        type:
          nullable: true
          oneOf:
            - $ref: '#/components/schemas/WorkspacePartTypeEnum'
            - $ref: '#/components/schemas/NullEnum'
        files_count:
          type: integer
          nullable: true
      required:
        - id
    Tag:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the tag
        tag:
          type: string
          description: Tag name
      required:
        - id
        - tag
    Type310Enum:
      enum:
        - native
        - mcp
      type: string
      description: |-
        * `native` - native
        * `mcp` - mcp
    ToolStepResponse:
      type: object
      properties:
        status:
          type: string
        progress_report:
          allOf:
            - $ref: '#/components/schemas/ProgressReportResponse'
          nullable: true
        created_at:
          type: string
          format: date-time
      required:
        - created_at
        - status
    ToolCallResultResponse:
      type: object
      properties:
        text:
          type: string
          nullable: true
        file_artifacts:
          type: array
          items:
            type: object
            additionalProperties: {}
          nullable: true
        web_sources:
          type: array
          items:
            type: object
            additionalProperties: {}
          nullable: true
        chunk_sources:
          type: array
          items:
            type: object
            additionalProperties: {}
          nullable: true
        document_sources:
          type: array
          items:
            type: object
            additionalProperties: {}
          nullable: true
        timings:
          type: object
          additionalProperties:
            type: number
            format: double
          nullable: true
    WorkspacePartTypeEnum:
      enum:
        - company
        - personal
        - custom
      type: string
      description: |-
        * `company` - company
        * `personal` - personal
        * `custom` - custom
    NullEnum:
      enum:
        - null
    ProgressReportResponse:
      type: object
      properties:
        progress_percentage:
          type: number
          format: double
          nullable: true
        current_progress_text:
          type: string
          nullable: true
        time_remaining_estimate:
          type: integer
          nullable: true
        metadata:
          type: object
          additionalProperties: {}
          nullable: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer authentication header of the form `Bearer <token>`, where
        `<token>` is your auth token.

````