Skip to main content
POST
/
api
/
v3
/
threads
/
turns
Create a conversation thread with initial turn
curl --request POST \
  --url https://paradigm.lighton.ai/api/v3/threads/turns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "chat_setting_id": 123,
  "name": "<string>",
  "ml_model": "<string>",
  "is_ephemeral": false,
  "query": "<string>",
  "force_tool": "<string>",
  "suggested_query_id": 123,
  "force_mcp_server": "<string>",
  "immediate_final_answer": false,
  "background": false,
  "system_prompt_suffix": "<string>",
  "max_steps": 8,
  "response_format": "<unknown>",
  "workspace_ids": [
    123
  ],
  "file_ids": [
    123
  ],
  "private_scope": true,
  "company_scope": true
}
'
{
  "id": "<string>",
  "thread": "<string>",
  "status": "running",
  "messages": [
    {
      "id": "<string>",
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "<string>",
          "reasoning": "<string>",
          "tool_call": {
            "id": "<string>",
            "tool": {
              "id": "<string>",
              "name": "<string>",
              "type": "native",
              "object": "tool",
              "mcp_server_name": "<string>",
              "require_document": true,
              "accepted_file_types": [
                "<string>"
              ]
            },
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "object": "tool_call",
            "tool_args": {},
            "steps": [
              {
                "status": "<string>",
                "created_at": "2023-11-07T05:31:56Z",
                "progress_report": {
                  "progress_percentage": 123,
                  "current_progress_text": "<string>",
                  "time_remaining_estimate": 123,
                  "metadata": {}
                }
              }
            ],
            "result": {
              "text": "<string>",
              "file_artifacts": [
                {}
              ],
              "web_sources": [
                {}
              ],
              "chunk_sources": [
                {}
              ]
            }
          },
          "document": {
            "id": "<string>"
          },
          "workspace": {
            "id": "<string>",
            "name": "<string>",
            "type": "company",
            "files_count": 123
          }
        }
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "object": "message",
      "force_tool": {
        "id": "<string>",
        "name": "<string>",
        "type": "native",
        "object": "tool",
        "mcp_server_name": "<string>",
        "require_document": true,
        "accepted_file_types": [
          "<string>"
        ]
      },
      "immediate_final_answer": true
    }
  ],
  "created_at": "2023-11-07T05:31:56Z",
  "object": "turn",
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "liked": true
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

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.

chat_setting_id
integer
required

ID of the chat setting to use

name
string

Thread name

Maximum string length: 255
ml_model
string

Technical name of the ML model to use

is_ephemeral
boolean
default:false

Enable ephemeral mode

query
string | null

The user's query

force_tool
string

Name of tool to force use

suggested_query_id
integer

ID of a suggested query

force_mcp_server
string

Name of MCP server to restrict tools to

immediate_final_answer
boolean
default:false

Skip tool calls and return final answer immediately

background
boolean
default:false

Process asynchronously and return immediately

system_prompt_suffix
string

Additional system prompt instructions

Maximum string length: 5000
max_steps
integer
default:8

Maximum reasoning steps

Required range: 1 <= x <= 20
response_format
any

JSON schema specifying response structure

workspace_ids
integer[]

Workspaces to search for documents

file_ids
integer[]

Specific files to include

private_scope
boolean

Include user's private workspace

company_scope
boolean

Include company's workspace

Response

Final answer returned synchronously.

id
string
required
thread
string
required
status
enum<string>
required
  • running - running
  • completed - completed
  • failed - failed
  • cancelled - cancelled
  • cancelling - cancelling
Available options:
running,
completed,
failed,
cancelled,
cancelling
messages
object[]
required
created_at
string<date-time>
required
object
string
default:turn
error
object
liked
boolean | null