Threads - PLai Framework Documentation

List All Threads

List all conversation threads across your project with advanced filtering and pagination options.

Query Parameters

skip

integer

Number of threads to skip for pagination (default: 0)

take

integer

Number of threads to return (default: 50, max: 100)

order

string

Sort order for results (default: “desc”)

asc - Ascending order (oldest first)
desc - Descending order (newest first)

userId

string

Filter threads by user ID

externalRef

string

Filter threads by external reference identifier

agentId

string

Filter threads by agent ID

date_from

string

Start date filter (ISO 8601 format, e.g., “2024-01-01”)

date_to

string

End date filter (ISO 8601 format, e.g., “2024-01-31”)

Response

count

integer

Total number of threads matching the criteria

has_more

boolean

Whether more results are available

string

Cursor for the next page of results

string

Cursor for the previous page of results

data

array

Array of thread objects with messages

Show Thread with Messages Object

string

Thread unique identifier

agent_id

string

ID of the agent handling this thread

user_id

string

ID of the user participating in this thread

external_ref

string

External reference identifier for integration purposes

title

string

Thread title (auto-generated or custom)

created_at

string

When the thread was created (ISO 8601 format)

updated_at

string

When the thread was last updated (ISO 8601 format)

messages

array

Array of messages in this thread

Show Message Object

string

Message unique identifier

thread_id

string

ID of the thread this message belongs to

role

string

Message sender role (user, assistant, system, tool)

content

string

Message content/text

message_type

string

Type of message (text, image, pdf)

tool_call_id

string

ID of tool call if message is a tool response

tool_calls

array

Array of tool calls made in this message

tool_result

object

Result data from tool execution

title

string

Message title or summary

created_at

string

When the message was created (ISO 8601 format)

updated_at

string

When the message was last updated (ISO 8601 format)

curl --location --request GET 'https://api.plaisolutions.com/threads?take=20&agentId=agent_123&date_from=2024-01-01' \
--header 'Authorization: Bearer YOUR_TOKEN'

Create Thread for Agent

Create a new conversation thread for a specific agent.

Path Parameters

agent_id

string

required

The unique identifier of the agent

Request Body

external_ref

string

External reference identifier for integration tracking

Response

Returns the created thread object.

string

Thread unique identifier

agent_id

string

ID of the agent handling this thread

user_id

string

ID of the user who created this thread

external_ref

string

External reference identifier

title

string

Thread title

created_at

string

When the thread was created (ISO 8601 format)

updated_at

string

When the thread was last updated (ISO 8601 format)

curl --location --request POST 'https://api.plaisolutions.com/agents/agent_123/threads' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "external_ref": "support_ticket_456"
}'

List Agent Threads

List all conversation threads for a specific agent.

Path Parameters

agent_id

string

required

The unique identifier of the agent

Query Parameters

skip

integer

Number of threads to skip (default: 0)

take

integer

Number of threads to return (default: 50)

order

string

Sort order for results (default: “desc”)

Response

count

integer

Total number of threads for this agent

has_more

boolean

Whether more results are available

string

Cursor for the next page

string

Cursor for the previous page

data

array

Array of thread objects (without messages)

curl --location --request GET 'https://api.plaisolutions.com/agents/agent_123/threads?take=25' \
--header 'Authorization: Bearer YOUR_TOKEN'

Get Thread with Messages

Get detailed information about a specific thread including all messages.

Path Parameters

agent_id

string

required

The unique identifier of the agent

thread_id

string

required

The unique identifier of the thread

Response

Returns the complete thread object with all messages and conversation history.

curl --location --request GET 'https://api.plaisolutions.com/agents/agent_123/threads/thread_456' \
--header 'Authorization: Bearer YOUR_TOKEN'

Chat Session Threads

Create Thread from Chat Session

Create a new thread within a chat session context.

Path Parameters

chat_session_id

string

required

The unique identifier of the chat session

Response

Returns the created thread object within the chat session context.

curl --location --request POST 'https://api.plaisolutions.com/chat_sessions/session_123/threads' \
--header 'Authorization: Bearer YOUR_TOKEN'

List Chat Session Threads

List all threads within a specific chat session.

Path Parameters

chat_session_id

string

required

The unique identifier of the chat session

Response

Returns an array of thread objects associated with the chat session.

curl --location --request GET 'https://api.plaisolutions.com/chat_sessions/session_123/threads' \
--header 'Authorization: Bearer YOUR_TOKEN'

Get Thread from Chat Session

Get a specific thread within a chat session context.

Path Parameters

chat_session_id

string

required

The unique identifier of the chat session

thread_id

string

required

The unique identifier of the thread

curl --location --request GET 'https://api.plaisolutions.com/chat_sessions/session_123/threads/thread_456' \
--header 'Authorization: Bearer YOUR_TOKEN'

Delete Thread from Chat Session

Delete a specific thread from a chat session.

Path Parameters

chat_session_id

string

required

The unique identifier of the chat session

thread_id

string

required

The unique identifier of the thread to delete

Response

Returns a confirmation of thread deletion.

Deleting a thread will permanently remove all messages and conversation history. This action cannot be undone.

curl --location --request DELETE 'https://api.plaisolutions.com/chat_sessions/session_123/threads/thread_456' \
--header 'Authorization: Bearer YOUR_TOKEN'

Invoke Thread from Chat Session

Send a message to an agent through a chat session thread.

Path Parameters

chat_session_id

string

required

The unique identifier of the chat session

thread_id

string

required

The unique identifier of the thread

Request Body

prompt

string

required

The message/prompt to send to the agent

enabled_tools

array

Array of tool IDs to enable for this specific interaction

Response

Returns the agent’s response and any tool results.

curl --location --request POST 'https://api.plaisolutions.com/chat_sessions/session_123/threads/thread_456/invoke' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
  "prompt": "Hello, can you help me with product recommendations?",
  "enabled_tools": ["web_search", "product_database"]
}'

Thread Management Best Practices

Thread Organization

Use meaningful external references to track threads across your application

Message History

Regularly retrieve thread messages to maintain conversation context

Session Management

Utilize chat sessions for temporary or anonymous user interactions

Cleanup Strategy

Implement thread lifecycle management to remove old or inactive conversations

Performance

Use pagination when listing threads to avoid performance issues

Thread Lifecycle

Creation

Threads are created automatically when users start conversations or manually via API

Active State

Threads remain active while users exchange messages with agents

Persistence

All messages and context are preserved throughout the thread lifetime

Cleanup

Implement cleanup policies based on age, activity, or business requirements

External Reference Patterns

Common External Reference Patterns:

Support tickets: ticket_12345
User sessions: session_user_67890
Order inquiries: order_98765
Product questions: product_sku_abc123
Channel integration: slack_channel_general

Message Types and Structure

Text Messages

Standard text-based conversations between users and agents

{
  "role": "user",
  "message_type": "text",
  "content": "Hello, I need help with my order"
}

Tool Messages

Messages containing tool calls and results

{
  "role": "assistant", 
  "message_type": "text",
  "content": "I'll help you check your order status",
  "tool_calls": [
    {
      "function": "check_order_status",
      "arguments": {"order_id": "12345"}
    }
  ]
}

Media Messages

Messages containing images, documents, or other media

{
  "role": "user",
  "message_type": "image", 
  "content": null,
  "title": "Product photo for identification"
}

Filtering and Search

Advanced Filtering Options:

Filter by date range to find recent conversations
Filter by agent to analyze specific agent performance
Filter by external reference for integration lookup
Filter by user for customer support scenarios
Combine filters for precise thread discovery

Security Considerations

Thread Security:

Threads inherit permissions from their associated agents and projects
External references should not contain sensitive information
Implement proper access controls for chat session management
Consider message retention policies for compliance
Monitor thread access patterns for security anomalies

Integration Patterns

Use threads effectively in different integration scenarios:

// Customer Support Integration
async function createSupportThread(ticketId, agentId) {
  const thread = await fetch(`/agents/${agentId}/threads`, {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_TOKEN' },
    body: JSON.stringify({
      external_ref: `support_${ticketId}`
    })
  });
  return await thread.json();
}

// Chat Widget Integration  
async function getOrCreateChatThread(sessionId, agentId) {
  // Try to find existing thread
  const threads = await fetch(`/agents/${agentId}/threads?externalRef=chat_${sessionId}`);
  const threadList = await threads.json();
  
  if (threadList.data.length > 0) {
    return threadList.data[0];
  }
  
  // Create new thread if none exists
  return createSupportThread(`chat_${sessionId}`, agentId);
}

Performance Optimization

Optimize Thread Performance:

Use appropriate pagination limits (20-50 threads per request)
Filter by date range to reduce result sets
Cache frequently accessed threads
Use external references for quick thread lookup
Implement thread archiving for old conversations

API Documentation

User & Organization Management

Projects & Agents

Data Management

Tools & Models

Processing & Analytics

Advanced Features

​List All Threads

​Query Parameters

​Response

​Create Thread for Agent

​Path Parameters

​Request Body

​Response

​List Agent Threads

​Path Parameters

​Query Parameters

​Response

​Get Thread with Messages

​Path Parameters

​Response

​Chat Session Threads

​Create Thread from Chat Session

​Path Parameters

​Response

​List Chat Session Threads

​Path Parameters

​Response

​Get Thread from Chat Session

​Path Parameters

​Delete Thread from Chat Session

​Path Parameters

​Response

​Invoke Thread from Chat Session

​Path Parameters

​Request Body

​Response

​Thread Management Best Practices

​Thread Lifecycle

Creation

Active State

Persistence

Cleanup

​External Reference Patterns

​Message Types and Structure

​Filtering and Search

​Security Considerations

​Integration Patterns

​Performance Optimization

List All Threads

Query Parameters

Response

Create Thread for Agent

Path Parameters

Request Body

Response

List Agent Threads

Path Parameters

Query Parameters

Response

Get Thread with Messages

Path Parameters

Response

Chat Session Threads

Create Thread from Chat Session

Path Parameters

Response

List Chat Session Threads

Path Parameters

Response

Get Thread from Chat Session

Path Parameters

Delete Thread from Chat Session

Path Parameters

Response

Invoke Thread from Chat Session

Path Parameters

Request Body

Response

Thread Management Best Practices

Thread Lifecycle

External Reference Patterns

Message Types and Structure

Filtering and Search

Security Considerations

Integration Patterns

Performance Optimization