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_idstring · nullableOptional

Filter by assignment ID

agent_idstring · nullableOptional

Filter by agent ID

page_numintegerOptional

Current page number

Default: 1

page_sizeintegerOptional

Items per page

Default: 20

orderstring · nullableOptional

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

Default: recent

statusstring · nullableOptional

Filter by status

statusesstring[] · nullableOptional

Filter by statuses

tenant_idstring · nullableOptional

Tenant Id

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

tenant_unit_idstring · nullableOptional

Tenant Unit ID

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

Responses

200

Successful Response

application/json

page_numintegerRequired

Current page number

page_sizeintegerRequired

Number of items per page

total_countintegerRequired

Total number of items

total_pagesintegerOptional

Total number of pages

Default: 1

has_next_pagebooleanRequired

Whether there is a next page

422

Validation Error

application/json

get/admin/api/v2/conversations

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-07-16T07:41:47.748Z",
      "updated_time": "2026-07-16T07:41:47.748Z",
      "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_idstring · nullableOptional

Tenant Id

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

tenant_unit_idstring · nullableOptional

Tenant Unit ID

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

Responses

200

Successful Response

application/json

page_numintegerRequired

Current page number

page_sizeintegerRequired

Number of items per page

total_countintegerRequired

Total number of items

total_pagesintegerOptional

Total number of pages

Default: 1

has_next_pagebooleanRequired

Whether there is a next page

422

Validation Error

application/json

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

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-07-16T07:41:47.748Z",
      "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_idstring · nullableOptional

Filter by assignment ID

tenant_idstring · nullableOptional

Tenant Id

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

tenant_unit_idstring · nullableOptional

Tenant Unit ID

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

Body

Conversation create request

topicstringOptional

Conversation topic

Default: New Conversation

statusobject · nullableOptional

Conversation status

Default: running

agent_idstring · uuid · nullableOptional

Agent ID

inputsobject · Inputs · nullableOptional

Inputs

assignment_idstring · nullableOptional

Assignment ID

Responses

201

Successful Response

application/json

created_bystring · nullableOptional

updated_bystring · nullableOptional

created_by_rolestring · nullableOptional

updated_by_rolestring · nullableOptional

idstringRequired

Conversation ID

topicstring · nullableOptional

Conversation topic

agent_idstringRequired

Agent ID

tenant_idstringRequired

Tenant ID

tenant_unit_idstringRequired

Tenant Unit ID

user_idstringRequired

User ID

agent_modestringRequired

Agent mode

extend_propertiesobject · Extend PropertiesOptional

Extended properties

invoke_fromstring · nullableOptional

Invoke from

inputsobject · Inputs · nullableOptional

Inputs

statusobject · nullableOptional

Workforce run status

Default: running

assignment_idstring · nullableOptional

Assignment ID

created_timestring · date-time · nullableOptional

Created time

updated_timestring · date-time · nullableOptional

Updated time

created_by_namestring · nullableOptional

Created by name

updated_by_namestring · nullableOptional

Updated by name

agent_typestring · nullableOptional

Agent type

422

Validation Error

application/json

post/admin/api/v2/conversations

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-07-16T07:41:47.748Z",
  "updated_time": "2026-07-16T07:41:47.748Z",
  "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_idstring · nullableOptional

Tenant Id

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

tenant_unit_idstring · nullableOptional

Tenant Unit ID

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

Body

object · Update DataOptional

Responses

200

Successful Response

application/json

created_bystring · nullableOptional

updated_bystring · nullableOptional

created_by_rolestring · nullableOptional

updated_by_rolestring · nullableOptional

idstringRequired

Conversation ID

topicstring · nullableOptional

Conversation topic

agent_idstringRequired

Agent ID

tenant_idstringRequired

Tenant ID

tenant_unit_idstringRequired

Tenant Unit ID

user_idstringRequired

User ID

agent_modestringRequired

Agent mode

extend_propertiesobject · Extend PropertiesOptional

Extended properties

invoke_fromstring · nullableOptional

Invoke from

inputsobject · Inputs · nullableOptional

Inputs

statusobject · nullableOptional

Workforce run status

Default: running

assignment_idstring · nullableOptional

Assignment ID

created_timestring · date-time · nullableOptional

Created time

updated_timestring · date-time · nullableOptional

Updated time

created_by_namestring · nullableOptional

Created by name

updated_by_namestring · nullableOptional

Updated by name

agent_typestring · nullableOptional

Agent type

422

Validation Error

application/json

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

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-07-16T07:41:47.748Z",
  "updated_time": "2026-07-16T07:41:47.748Z",
  "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_idstring · nullableOptional

Tenant Id

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

tenant_unit_idstring · nullableOptional

Tenant Unit ID

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

Responses

200

Successful Response

application/json

created_bystring · nullableOptional

updated_bystring · nullableOptional

created_by_rolestring · nullableOptional

updated_by_rolestring · nullableOptional

idstringRequired

Conversation ID

topicstring · nullableOptional

Conversation topic

agent_idstringRequired

Agent ID

tenant_idstringRequired

Tenant ID

tenant_unit_idstringRequired

Tenant Unit ID

user_idstringRequired

User ID

agent_modestringRequired

Agent mode

extend_propertiesobject · Extend PropertiesOptional

Extended properties

invoke_fromstring · nullableOptional

Invoke from

inputsobject · Inputs · nullableOptional

Inputs

statusobject · nullableOptional

Workforce run status

Default: running

assignment_idstring · nullableOptional

Assignment ID

created_timestring · date-time · nullableOptional

Created time

updated_timestring · date-time · nullableOptional

Updated time

created_by_namestring · nullableOptional

Created by name

updated_by_namestring · nullableOptional

Updated by name

agent_typestring · nullableOptional

Agent type

422

Validation Error

application/json

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

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-07-16T07:41:47.748Z",
  "updated_time": "2026-07-16T07:41:47.748Z",
  "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

objectOptional

422

Validation Error

application/json

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

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_idstring · nullableOptional

Tenant Id

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

tenant_unit_idstring · nullableOptional

Tenant Unit ID

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

Body

statusstring · enum · nullableOptional

Workforce Run Status Enum

Possible values:

Responses

200

Successful Response

application/json

created_bystring · nullableOptional

updated_bystring · nullableOptional

created_by_rolestring · nullableOptional

updated_by_rolestring · nullableOptional

idstringRequired

Conversation ID

topicstring · nullableOptional

Conversation topic

agent_idstringRequired

Agent ID

tenant_idstringRequired

Tenant ID

tenant_unit_idstringRequired

Tenant Unit ID

user_idstringRequired

User ID

agent_modestringRequired

Agent mode

extend_propertiesobject · Extend PropertiesOptional

Extended properties

invoke_fromstring · nullableOptional

Invoke from

inputsobject · Inputs · nullableOptional

Inputs

statusobject · nullableOptional

Workforce run status

Default: running

assignment_idstring · nullableOptional

Assignment ID

created_timestring · date-time · nullableOptional

Created time

updated_timestring · date-time · nullableOptional

Updated time

created_by_namestring · nullableOptional

Created by name

updated_by_namestring · nullableOptional

Updated by name

agent_typestring · nullableOptional

Agent type

422

Validation Error

application/json

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

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-07-16T07:41:47.748Z",
  "updated_time": "2026-07-16T07:41:47.748Z",
  "created_by_name": "text",
  "updated_by_name": "text",
  "agent_type": "text"
}

PreviousTools NextFiles

Last updated 1 year ago

Was this helpful?