Tools

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

List Tool Vendors

get

Returns a paginated list of available tool vendors for the current tenant and unit.

• Note: This endpoint only returns metadata about the tool vendors (e.g., ID, name, mode, favorite status).

• To retrieve detailed tool configurations or schema information, use the corresponding GET /tools/{mode}_tools/{id} or related detail endpoints.

Query parameters

page_numintegerOptional

Current page number

Default: 1

page_sizeintegerOptional

Number of items per page

Default: 14

is_favoriteany ofOptional

Filter by favorite status

booleanOptional

or

nullOptional

modeany ofOptional

Filter by mode, value is flow, builtin

string · enumOptionalPossible values:

or

nullOptional

orderany ofOptional

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

Default: recent

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

Responses

200

Successful Response

application/json

page_numintegerRequired

Current page number

page_sizeintegerRequired

Number of items per page

total_countintegerRequired

Total number of tools

has_next_pagebooleanRequired

Whether there is a next page

dataobject[]Required

List of tools

422

Validation Error

application/json

get

/admin/api/v2/tools

HTTPcURLJavaScriptPython

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

{
  "page_num": 1,
  "page_size": 1,
  "total_count": 1,
  "has_next_page": true,
  "data": [
    {}
  ]
}

Get Tool Vendor By Id

get

Retrieve common information and metadata for a single tool by its ID.

Path parameters

tool_idstring · uuidRequired

Tool ID to fetch

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

icon_typeany ofOptional

Source type: 'emoji' or 'url'

string · enumOptionalPossible values:

or

nullOptional

iconany ofOptional

Raw icon value: emoji char, full URL, or gallery key

stringOptional

or

nullOptional

icon_backgroundany ofOptional

Hex background color behind the icon

Default: #FFF

stringOptional

or

nullOptional

descriptionany ofOptional

Tool description

Default: ""

stringOptional

or

nullOptional

idany ofOptional

Tool vendor ID

stringOptional

or

nullOptional

namestringRequired

Tool vendor name

display_nameany ofOptional

Tool vendor display name

stringOptional

or

nullOptional

modestring · enumRequired

Tool type, e.g., builtin, flow

Possible values:

created_byany ofOptional

User ID of creator

stringOptional

or

nullOptional

created_by_nameany ofOptional

User name of creator

stringOptional

or

nullOptional

created_timeany ofOptional

Timestamp of creation

string · date-timeOptional

or

nullOptional

updated_byany ofOptional

User ID of last updater

stringOptional

or

nullOptional

updated_by_nameany ofOptional

User name of updater

stringOptional

or

nullOptional

updated_timeany ofOptional

Timestamp of last update

string · date-timeOptional

or

nullOptional

is_favoriteany ofOptional

Indicates if the item is marked as favorite

booleanOptional

or

nullOptional

icon_urlany ofRead-onlyRequired

stringOptional

or

nullOptional

422

Validation Error

application/json

get

/admin/api/v2/tools/{tool_id}

HTTPcURLJavaScriptPython

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

{
  "icon_type": "emoji",
  "icon": "text",
  "icon_background": "#FFF",
  "description": "",
  "id": "text",
  "name": "text",
  "display_name": "text",
  "mode": "flow",
  "created_by": "text",
  "created_by_name": "text",
  "created_time": "2026-04-03T08:02:25.145Z",
  "updated_by": "text",
  "updated_by_name": "text",
  "updated_time": "2026-04-03T08:02:25.145Z",
  "is_favorite": true,
  "icon_url": "text"
}

Update Tool Vendor

put

Update the common information and metadata for a tool by its ID.

Path parameters

tool_idstringRequired

Tool id

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

Payload containing fields to update for the tool

icon_typeany ofOptional

Source type: 'emoji' or 'url'

string · enumOptionalPossible values:

or

nullOptional

iconany ofOptional

Raw icon value: emoji char, full URL, or gallery key

stringOptional

or

nullOptional

icon_backgroundany ofOptional

Hex background color behind the icon

Default: #FFF

stringOptional

or

nullOptional

descriptionany ofOptional

Tool description

Default: ""

stringOptional

or

nullOptional

nameany ofOptional

Tool name

stringOptional

or

nullOptional

display_nameany ofOptional

Tool name

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

icon_typeany ofOptional

Source type: 'emoji' or 'url'

string · enumOptionalPossible values:

or

nullOptional

iconany ofOptional

Raw icon value: emoji char, full URL, or gallery key

stringOptional

or

nullOptional

icon_backgroundany ofOptional

Hex background color behind the icon

Default: #FFF

stringOptional

or

nullOptional

descriptionany ofOptional

Tool description

Default: ""

stringOptional

or

nullOptional

idany ofOptional

Tool vendor ID

stringOptional

or

nullOptional

namestringRequired

Tool vendor name

display_nameany ofOptional

Tool vendor display name

stringOptional

or

nullOptional

modestring · enumRequired

Tool type, e.g., builtin, flow

Possible values:

created_byany ofOptional

User ID of creator

stringOptional

or

nullOptional

created_by_nameany ofOptional

User name of creator

stringOptional

or

nullOptional

created_timeany ofOptional

Timestamp of creation

string · date-timeOptional

or

nullOptional

updated_byany ofOptional

User ID of last updater

stringOptional

or

nullOptional

updated_by_nameany ofOptional

User name of updater

stringOptional

or

nullOptional

updated_timeany ofOptional

Timestamp of last update

string · date-timeOptional

or

nullOptional

is_favoriteany ofOptional

Indicates if the item is marked as favorite

booleanOptional

or

nullOptional

icon_urlany ofRead-onlyRequired

stringOptional

or

nullOptional

422

Validation Error

application/json

put

/admin/api/v2/tools/{tool_id}

HTTPcURLJavaScriptPython

PUT /admin/api/v2/tools/{tool_id} HTTP/1.1
Host: api.workfx.ai
Content-Type: application/json
Accept: */*
Content-Length: 113

{
  "icon_type": "emoji",
  "icon": "text",
  "icon_background": "#FFF",
  "description": "",
  "name": "text",
  "display_name": "text"
}

{
  "icon_type": "emoji",
  "icon": "text",
  "icon_background": "#FFF",
  "description": "",
  "id": "text",
  "name": "text",
  "display_name": "text",
  "mode": "flow",
  "created_by": "text",
  "created_by_name": "text",
  "created_time": "2026-04-03T08:02:25.145Z",
  "updated_by": "text",
  "updated_by_name": "text",
  "updated_time": "2026-04-03T08:02:25.145Z",
  "is_favorite": true,
  "icon_url": "text"
}

Delete Tool Vendor

delete

Delete a tool (common metadata) by its ID. No content is returned on success.

Path parameters

tool_idstringRequired

Tool id

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

204

Successful Response

application/json

422

Validation Error

application/json

delete

/admin/api/v2/tools/{tool_id}

HTTPcURLJavaScriptPython

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

{}