Create a conversation turn in a thread

Ask a query to the agent.

Behaviour:

• Returns 200 with the final answer when the task completes quickly within the request.
• Returns 202 Accepted with the current answer payload when processing continues in the background; clients should poll the turn status or subscribe to updates until completion.
• If stream=true, the endpoint responds with Server-Sent Events (SSE) and streams tokens/events until completion (content-type: text/event-stream).
• If background=true, the endpoint enqueues processing and returns the created answer immediately.

POST /api/v3/threads/{id}/turns

Create a conversation turn in a thread

cURL

curl --request POST \
  --url https://paradigm.lighton.ai/api/v3/threads/{id}/turns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "force_tool": "<string>",
  "suggested_query_id": 123,
  "force_mcp_server": "<string>",
  "immediate_final_answer": false,
  "stream": 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/{id}/turns"

payload = {
    "query": "<string>",
    "force_tool": "<string>",
    "suggested_query_id": 123,
    "force_mcp_server": "<string>",
    "immediate_final_answer": False,
    "stream": 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({
    query: '<string>',
    force_tool: '<string>',
    suggested_query_id: 123,
    force_mcp_server: '<string>',
    immediate_final_answer: false,
    stream: 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/{id}/turns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

200

{
  "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.

Path Parameters

id · string · required

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

query · string | null

force_tool · string

suggested_query_id · integer

force_mcp_server · string

immediate_final_answer · boolean · default: false

stream · boolean · default: false

background · boolean · default: false

system_prompt_suffix · string

Maximum string length: 5000

max_steps · integer · default: 8

Required range: 1 <= x <= 20

response_format · any

tool_parameters · any

workspace_ids · integer[]

file_ids · integer[]

tag_ids · integer[]

private_scope · boolean

company_scope · boolean

Response

200

application/json

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

Show child attributes

created_at · string<date-time> · required

object · string · default: turn

error · object | null

Show child attributes

liked · boolean | null