Home PageLogin

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

Query parameters
assignment_idany ofOptional

Filter by assignment ID

stringOptional
or
nullOptional
agent_idany ofOptional

Filter by agent ID

stringOptional
or
nullOptional
page_numintegerOptional

Current page number

Default: 1
page_sizeintegerOptional

Items per page

Default: 20
orderany ofOptional

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

Default: recent
stringOptional
or
nullOptional
statusany ofOptional

Filter by status

stringOptional
or
nullOptional
statusesany ofOptional

Filter by statuses

string[]Optional
or
nullOptional
tenant_idany ofOptional

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c
stringOptional
or
nullOptional
tenant_unit_idany ofOptional

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589
stringOptional
or
nullOptional
Responses
200
Successful Response
application/json
get
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": "2025-07-16T16:47:08.804Z",
      "updated_time": "2025-07-16T16:47:08.804Z",
      "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

Path parameters
conversation_idstringRequired
Query parameters
pageintegerOptional

Page number

Default: 1
page_sizeintegerOptional

Page size

Default: 20
tenant_idany ofOptional

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c
stringOptional
or
nullOptional
tenant_unit_idany ofOptional

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589
stringOptional
or
nullOptional
Responses
200
Successful Response
application/json
get
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": "2025-07-16T16:47:08.804Z",
      "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

Query parameters
assignment_idany ofOptional

Filter by assignment ID

stringOptional
or
nullOptional
tenant_idany ofOptional

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c
stringOptional
or
nullOptional
tenant_unit_idany ofOptional

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589
stringOptional
or
nullOptional
Body

Conversation create request

topicstringOptional

Conversation topic

Default: New Conversation
statusany ofOptional

Conversation status

Default: running
objectOptional
or
nullOptional
agent_idany ofOptional

Agent ID

string · uuidOptional
or
nullOptional
inputsany ofOptional

Inputs

objectOptional
or
nullOptional
assignment_idany ofOptional

Assignment ID

stringOptional
or
nullOptional
Responses
201
Successful Response
application/json
post
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": "2025-07-16T16:47:08.804Z",
  "updated_time": "2025-07-16T16:47:08.804Z",
  "created_by_name": "text",
  "updated_by_name": "text",
  "agent_type": "text"
}

Update Conversation

patch

Update a conversation (currently only supports updating topic)

Path parameters
conversation_idstringRequired
Query parameters
tenant_idany ofOptional

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c
stringOptional
or
nullOptional
tenant_unit_idany ofOptional

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589
stringOptional
or
nullOptional
Body
object · UpdateDataOptional
Responses
200
Successful Response
application/json
patch
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": "2025-07-16T16:47:08.804Z",
  "updated_time": "2025-07-16T16:47:08.804Z",
  "created_by_name": "text",
  "updated_by_name": "text",
  "agent_type": "text"
}

Get Conversation

get

Get a conversation by ID

Path parameters
conversation_idstringRequired
Query parameters
tenant_idany ofOptional

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c
stringOptional
or
nullOptional
tenant_unit_idany ofOptional

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589
stringOptional
or
nullOptional
Responses
200
Successful Response
application/json
get
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": "2025-07-16T16:47:08.804Z",
  "updated_time": "2025-07-16T16:47:08.804Z",
  "created_by_name": "text",
  "updated_by_name": "text",
  "agent_type": "text"
}

Delete Conversation

delete

Delete a conversation and its messages

Path parameters
conversation_idstringRequired
Responses
204
Successful Response
application/json
Responseobject
delete
DELETE /admin/api/v2/conversations/{conversation_id} HTTP/1.1
Host: api.workfx.ai
Accept: */*

{}

Update Conversation Status

patch

Update conversation status

Path parameters
conversation_idstringRequired
Query parameters
tenant_idany ofOptional

Tenant Id

Example: 40d39c4b-9585-4123-8fd4-f1cc23a1184c
stringOptional
or
nullOptional
tenant_unit_idany ofOptional

Tenant Unit ID

Example: da114de3-d7e6-4161-bc55-0ce85dbee589
stringOptional
or
nullOptional
Body
statusany ofOptional
string · enumOptional

Workforce Run Status Enum

Possible values:
or
nullOptional
Responses
200
Successful Response
application/json
patch
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": "2025-07-16T16:47:08.804Z",
  "updated_time": "2025-07-16T16:47:08.804Z",
  "created_by_name": "text",
  "updated_by_name": "text",
  "agent_type": "text"
}
PreviousToolsNextFiles

Last updated

Was this helpful?