Conversations

Manage conversations between users and agents. These endpoints allow you to create, retrieve, update, and delete conversations and their associated messages.

List Conversations

get

List conversations with pagination and filtering

查询参数

assignment_idany of可选

Filter by assignment ID

string可选

或

null可选

agent_idany of可选

Filter by agent ID

string可选

或

null可选

page_numinteger可选

Current page number

Default: 1

page_sizeinteger可选

Items per page

Default: 20

orderany of可选

order by: 'recent'(default) or 'oldest'

Default: recent

string可选

或

null可选

statusany of可选

Filter by status

string可选

或

null可选

statusesany of可选

Filter by statuses

string[]可选

或

null可选

tenant_idany of可选

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c

string可选

或

null可选

tenant_unit_idany of可选

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589

string可选

或

null可选

响应

200

Successful Response

application/json

422

Validation Error

application/json

get

/admin/api/v2/conversations

HTTPcURLJavaScriptPython

GET /admin/api/v2/conversations HTTP/1.1
Host: api.workfx.ai
Accept: */*

{
  "page_num": 1,
  "page_size": 1,
  "total_count": 1,
  "total_pages": 1,
  "has_next_page": true,
  "data": [
    {
      "created_by": "text",
      "updated_by": "text",
      "created_by_role": "text",
      "updated_by_role": "text",
      "id": "text",
      "topic": "text",
      "agent_id": "text",
      "tenant_id": "text",
      "tenant_unit_id": "text",
      "user_id": "text",
      "agent_mode": "text",
      "extend_properties": {},
      "invoke_from": "text",
      "inputs": {},
      "status": "running",
      "assignment_id": "text",
      "created_time": "2026-01-31T18:56:46.068Z",
      "updated_time": "2026-01-31T18:56:46.068Z",
      "created_by_name": "text",
      "updated_by_name": "text",
      "agent_type": "text",
      "message_count": 1
    }
  ]
}

List Messages By Conversation

get

List messages in a conversation with pagination

路径参数

conversation_idstring必填

查询参数

pageinteger可选

Page number

Default: 1

page_sizeinteger可选

Page size

Default: 20

tenant_idany of可选

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c

string可选

或

null可选

tenant_unit_idany of可选

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589

string可选

或

null可选

响应

200

Successful Response

application/json

422

Validation Error

application/json

get

/admin/api/v2/conversations/{conversation_id}/messages

HTTPcURLJavaScriptPython

GET /admin/api/v2/conversations/{conversation_id}/messages HTTP/1.1
Host: api.workfx.ai
Accept: */*

{
  "page_num": 1,
  "page_size": 1,
  "total_count": 1,
  "total_pages": 1,
  "has_next_page": true,
  "data": [
    {
      "created_by": "text",
      "updated_by": "text",
      "created_by_role": "text",
      "updated_by_role": "text",
      "id": "text",
      "tenant_id": "text",
      "tenant_unit_id": "text",
      "agent_id": "text",
      "user_id": "text",
      "conversation_id": "text",
      "run_id": "text",
      "message_from": "text",
      "content": "text",
      "requested_time": "2026-01-31T18:56:46.068Z",
      "input_tokens": 0,
      "answer_tokens": 0,
      "total_tokens": 0,
      "feedback": "text",
      "metadata": {},
      "type": "text",
      "user_type": "text",
      "status": "text",
      "event_trace": "text"
    }
  ]
}

Create Conversation

post

Create a new conversation

查询参数

assignment_idany of可选

Filter by assignment ID

string可选

或

null可选

tenant_idany of可选

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c

string可选

或

null可选

tenant_unit_idany of可选

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589

string可选

或

null可选

请求体

application/json

Conversation create request

topicstring可选

Conversation topic

Default: New Conversation

statusany of可选

Conversation status

Default: running

object可选

或

null可选

agent_idany of可选

Agent ID

string · uuid可选

或

null可选

inputsany of可选

Inputs

object可选

或

null可选

assignment_idany of可选

Assignment ID

string可选

或

null可选

响应

201

Successful Response

application/json

422

Validation Error

application/json

post

/admin/api/v2/conversations

HTTPcURLJavaScriptPython

POST /admin/api/v2/conversations HTTP/1.1
Host: api.workfx.ai
Content-Type: application/json
Accept: */*
Content-Length: 132

{
  "topic": "New Conversation",
  "status": "running",
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "inputs": {},
  "assignment_id": "text"
}

{
  "created_by": "text",
  "updated_by": "text",
  "created_by_role": "text",
  "updated_by_role": "text",
  "id": "text",
  "topic": "text",
  "agent_id": "text",
  "tenant_id": "text",
  "tenant_unit_id": "text",
  "user_id": "text",
  "agent_mode": "text",
  "extend_properties": {},
  "invoke_from": "text",
  "inputs": {},
  "status": "running",
  "assignment_id": "text",
  "created_time": "2026-01-31T18:56:46.068Z",
  "updated_time": "2026-01-31T18:56:46.068Z",
  "created_by_name": "text",
  "updated_by_name": "text",
  "agent_type": "text"
}

Update Conversation

patch

Update a conversation (currently only supports updating topic)

路径参数

conversation_idstring必填

查询参数

tenant_idany of可选

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c

string可选

或

null可选

tenant_unit_idany of可选

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589

string可选

或

null可选

请求体

application/json

object · UpdateData可选

响应

200

Successful Response

application/json

422

Validation Error

application/json

patch

/admin/api/v2/conversations/{conversation_id}

HTTPcURLJavaScriptPython

PATCH /admin/api/v2/conversations/{conversation_id} HTTP/1.1
Host: api.workfx.ai
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

{
  "created_by": "text",
  "updated_by": "text",
  "created_by_role": "text",
  "updated_by_role": "text",
  "id": "text",
  "topic": "text",
  "agent_id": "text",
  "tenant_id": "text",
  "tenant_unit_id": "text",
  "user_id": "text",
  "agent_mode": "text",
  "extend_properties": {},
  "invoke_from": "text",
  "inputs": {},
  "status": "running",
  "assignment_id": "text",
  "created_time": "2026-01-31T18:56:46.068Z",
  "updated_time": "2026-01-31T18:56:46.068Z",
  "created_by_name": "text",
  "updated_by_name": "text",
  "agent_type": "text"
}

Get Conversation

get

Get a conversation by ID

路径参数

conversation_idstring必填

查询参数

tenant_idany of可选

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c

string可选

或

null可选

tenant_unit_idany of可选

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589

string可选

或

null可选

响应

200

Successful Response

application/json

422

Validation Error

application/json

get

/admin/api/v2/conversations/{conversation_id}

HTTPcURLJavaScriptPython

GET /admin/api/v2/conversations/{conversation_id} HTTP/1.1
Host: api.workfx.ai
Accept: */*

{
  "created_by": "text",
  "updated_by": "text",
  "created_by_role": "text",
  "updated_by_role": "text",
  "id": "text",
  "topic": "text",
  "agent_id": "text",
  "tenant_id": "text",
  "tenant_unit_id": "text",
  "user_id": "text",
  "agent_mode": "text",
  "extend_properties": {},
  "invoke_from": "text",
  "inputs": {},
  "status": "running",
  "assignment_id": "text",
  "created_time": "2026-01-31T18:56:46.068Z",
  "updated_time": "2026-01-31T18:56:46.068Z",
  "created_by_name": "text",
  "updated_by_name": "text",
  "agent_type": "text"
}

Delete Conversation

delete

Delete a conversation and its messages

路径参数

conversation_idstring必填

响应

204

Successful Response

application/json

响应object

422

Validation Error

application/json

delete

/admin/api/v2/conversations/{conversation_id}

HTTPcURLJavaScriptPython

DELETE /admin/api/v2/conversations/{conversation_id} HTTP/1.1
Host: api.workfx.ai
Accept: */*

{}

Update Conversation Status

patch

Update conversation status

路径参数

conversation_idstring必填

查询参数

tenant_idany of可选

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c

string可选

或

null可选

tenant_unit_idany of可选

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589

string可选

或

null可选

请求体

application/json

statusany of可选

string · enum可选

Workforce Run Status Enum

可能的值:

或

null可选

响应

200

Successful Response

application/json

422

Validation Error

application/json

patch

/admin/api/v2/conversations/{conversation_id}/status

HTTPcURLJavaScriptPython

PATCH /admin/api/v2/conversations/{conversation_id}/status HTTP/1.1
Host: api.workfx.ai
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "status": "submitted"
}

{
  "created_by": "text",
  "updated_by": "text",
  "created_by_role": "text",
  "updated_by_role": "text",
  "id": "text",
  "topic": "text",
  "agent_id": "text",
  "tenant_id": "text",
  "tenant_unit_id": "text",
  "user_id": "text",
  "agent_mode": "text",
  "extend_properties": {},
  "invoke_from": "text",
  "inputs": {},
  "status": "running",
  "assignment_id": "text",
  "created_time": "2026-01-31T18:56:46.068Z",
  "updated_time": "2026-01-31T18:56:46.068Z",
  "created_by_name": "text",
  "updated_by_name": "text",
  "agent_type": "text"
}