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

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": "2025-12-08T12:24:45.979Z",
      "updated_time": "2025-12-08T12:24:45.979Z",
      "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

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": "2025-12-08T12:24:45.979Z",
      "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

application/json

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

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": "2025-12-08T12:24:45.979Z",
  "updated_time": "2025-12-08T12:24:45.979Z",
  "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

application/json

object · UpdateDataOptional

Responses

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": "2025-12-08T12:24:45.979Z",
  "updated_time": "2025-12-08T12:24:45.979Z",
  "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

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": "2025-12-08T12:24:45.979Z",
  "updated_time": "2025-12-08T12:24:45.979Z",
  "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

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

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

application/json

statusany ofOptional

string · enumOptional

Workforce Run Status Enum

Possible values:

or

nullOptional

Responses

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": "2025-12-08T12:24:45.979Z",
  "updated_time": "2025-12-08T12:24:45.979Z",
  "created_by_name": "text",
  "updated_by_name": "text",
  "agent_type": "text"
}