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 '
{
  "name": "<string>",
  "agent_id": 123,
  "chat_setting_id": 123,
  "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>",
  "tool_parameters": "<unknown>",
  "workspace_ids": [
    123
  ],
  "file_ids": [
    123
  ],
  "tag_ids": [
    123
  ],
  "private_scope": true,
  "company_scope": true
}
'

import requests

url = "https://paradigm.lighton.ai/api/v3/threads/turns"

payload = {
    "name": "<string>",
    "agent_id": 123,
    "chat_setting_id": 123,
    "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>",
    "tool_parameters": "<unknown>",
    "workspace_ids": [123],
    "file_ids": [123],
    "tag_ids": [123],
    "private_scope": True,
    "company_scope": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    agent_id: 123,
    chat_setting_id: 123,
    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>',
    tool_parameters: '<unknown>',
    workspace_ids: [123],
    file_ids: [123],
    tag_ids: [123],
    private_scope: true,
    company_scope: true
  })
};

fetch('https://paradigm.lighton.ai/api/v3/threads/turns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "<string>",
  "thread": "<string>",
  "messages": [
    {
      "id": "<string>",
      "parts": [
        {
          "text": "<string>",
          "reasoning": "<string>",
          "tool_call": {
            "id": "<string>",
            "tool": {
              "id": "<string>",
              "name": "<string>",
              "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_sources": [
                {}
              ],
              "timings": {}
            }
          },
          "document": {
            "id": "<string>"
          },
          "workspace": {
            "id": "<string>",
            "name": "<string>",
            "files_count": 123
          },
          "tag": {
            "id": 123,
            "tag": "<string>"
          }
        }
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "object": "message",
      "force_tool": {
        "id": "<string>",
        "name": "<string>",
        "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
}

{
  "id": "<string>",
  "thread": "<string>",
  "messages": [
    {
      "id": "<string>",
      "parts": [
        {
          "text": "<string>",
          "reasoning": "<string>",
          "tool_call": {
            "id": "<string>",
            "tool": {
              "id": "<string>",
              "name": "<string>",
              "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_sources": [
                {}
              ],
              "timings": {}
            }
          },
          "document": {
            "id": "<string>"
          },
          "workspace": {
            "id": "<string>",
            "name": "<string>",
            "files_count": 123
          },
          "tag": {
            "id": 123,
            "tag": "<string>"
          }
        }
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "object": "message",
      "force_tool": {
        "id": "<string>",
        "name": "<string>",
        "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
}

Threads

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.

POST

api

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 '
{
  "name": "<string>",
  "agent_id": 123,
  "chat_setting_id": 123,
  "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>",
  "tool_parameters": "<unknown>",
  "workspace_ids": [
    123
  ],
  "file_ids": [
    123
  ],
  "tag_ids": [
    123
  ],
  "private_scope": true,
  "company_scope": true
}
'

import requests

url = "https://paradigm.lighton.ai/api/v3/threads/turns"

payload = {
    "name": "<string>",
    "agent_id": 123,
    "chat_setting_id": 123,
    "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>",
    "tool_parameters": "<unknown>",
    "workspace_ids": [123],
    "file_ids": [123],
    "tag_ids": [123],
    "private_scope": True,
    "company_scope": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    agent_id: 123,
    chat_setting_id: 123,
    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>',
    tool_parameters: '<unknown>',
    workspace_ids: [123],
    file_ids: [123],
    tag_ids: [123],
    private_scope: true,
    company_scope: true
  })
};

fetch('https://paradigm.lighton.ai/api/v3/threads/turns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "<string>",
  "thread": "<string>",
  "messages": [
    {
      "id": "<string>",
      "parts": [
        {
          "text": "<string>",
          "reasoning": "<string>",
          "tool_call": {
            "id": "<string>",
            "tool": {
              "id": "<string>",
              "name": "<string>",
              "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_sources": [
                {}
              ],
              "timings": {}
            }
          },
          "document": {
            "id": "<string>"
          },
          "workspace": {
            "id": "<string>",
            "name": "<string>",
            "files_count": 123
          },
          "tag": {
            "id": 123,
            "tag": "<string>"
          }
        }
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "object": "message",
      "force_tool": {
        "id": "<string>",
        "name": "<string>",
        "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
}

{
  "id": "<string>",
  "thread": "<string>",
  "messages": [
    {
      "id": "<string>",
      "parts": [
        {
          "text": "<string>",
          "reasoning": "<string>",
          "tool_call": {
            "id": "<string>",
            "tool": {
              "id": "<string>",
              "name": "<string>",
              "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_sources": [
                {}
              ],
              "timings": {}
            }
          },
          "document": {
            "id": "<string>"
          },
          "workspace": {
            "id": "<string>",
            "name": "<string>",
            "files_count": 123
          },
          "tag": {
            "id": 123,
            "tag": "<string>"
          }
        }
      ],
      "created_at": "2023-11-07T05:31:56Z",
      "object": "message",
      "force_tool": {
        "id": "<string>",
        "name": "<string>",
        "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.

name

string

Thread name

Maximum string length: 255

agent_id

integer

ID of the agent to use. If not provided, uses the default agent for the company.

chat_setting_id

integer

DEPRECATED: Use 'agent_id' instead. ID of the chat setting to use. If not provided, uses the default agent for the company.

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

tool_parameters

any

Tool-specific parameters

workspace_ids

integer[]

Workspaces to search for documents

file_ids

integer[]

Specific files to include

tag_ids

integer[]

Specific tags to include

private_scope

boolean

Include user's private workspace

company_scope

boolean

Include company's workspace

Response

Final answer returned synchronously.

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

Show child attributes

created_at

string<date-time>

required

object

string

default:turn

error

object | null

Show child attributes

liked

boolean | null

Update a conversation turn in a thread List native tools

Agents

Threads

Tools

Models

MCP

Sources

Artifacts

Agent

Files

Files Processing

Tags

Workspaces

Users

User Groups

Companies

SCIM

Facets

Create a conversation thread with initial turn

Authorizations

Body

Response