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

Filter by favorite status

modestring · enum · nullableOptional

Filter by mode, value is flow, builtin

Possible values:

orderstring · nullableOptional

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

Default: recent

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 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_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

icon_typestring · enum · nullableOptional

Source type: 'emoji' or 'url'

Possible values:

iconstring · nullableOptional

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

icon_backgroundstring · nullableOptional

Hex background color behind the icon

Default: #FFF

descriptionstring · nullableOptional

Tool description

Default: ""

idstring · nullableOptional

Tool vendor ID

namestringRequired

Tool vendor name

display_namestring · nullableOptional

Tool vendor display name

modestring · enumRequired

Tool type, e.g., builtin, flow

Possible values:

created_bystring · nullableOptional

User ID of creator

created_by_namestring · nullableOptional

User name of creator

created_timestring · date-time · nullableOptional

Timestamp of creation

updated_bystring · nullableOptional

User ID of last updater

updated_by_namestring · nullableOptional

User name of updater

updated_timestring · date-time · nullableOptional

Timestamp of last update

is_favoriteboolean · nullableOptional

Indicates if the item is marked as favorite

icon_urlstring · nullableRead-onlyRequired

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-08-09T03:51:51.214Z",
  "updated_by": "text",
  "updated_by_name": "text",
  "updated_time": "2026-08-09T03:51:51.214Z",
  "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_idstring · nullableOptional

Tenant Id

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

tenant_unit_idstring · nullableOptional

Tenant Unit ID

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

Body

application/json

Payload containing fields to update for the tool

icon_typestring · enum · nullableOptional

Source type: 'emoji' or 'url'

Possible values:

iconstring · nullableOptional

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

icon_backgroundstring · nullableOptional

Hex background color behind the icon

Default: #FFF

descriptionstring · nullableOptional

Tool description

Default: ""

namestring · nullableOptional

Tool name

display_namestring · nullableOptional

Tool name

Responses

200

Successful Response

application/json

icon_typestring · enum · nullableOptional

Source type: 'emoji' or 'url'

Possible values:

iconstring · nullableOptional

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

icon_backgroundstring · nullableOptional

Hex background color behind the icon

Default: #FFF

descriptionstring · nullableOptional

Tool description

Default: ""

idstring · nullableOptional

Tool vendor ID

namestringRequired

Tool vendor name

display_namestring · nullableOptional

Tool vendor display name

modestring · enumRequired

Tool type, e.g., builtin, flow

Possible values:

created_bystring · nullableOptional

User ID of creator

created_by_namestring · nullableOptional

User name of creator

created_timestring · date-time · nullableOptional

Timestamp of creation

updated_bystring · nullableOptional

User ID of last updater

updated_by_namestring · nullableOptional

User name of updater

updated_timestring · date-time · nullableOptional

Timestamp of last update

is_favoriteboolean · nullableOptional

Indicates if the item is marked as favorite

icon_urlstring · nullableRead-onlyRequired

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-08-09T03:51:51.214Z",
  "updated_by": "text",
  "updated_by_name": "text",
  "updated_time": "2026-08-09T03:51:51.214Z",
  "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_idstring · nullableOptional

Tenant Id

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

tenant_unit_idstring · nullableOptional

Tenant Unit ID

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

Responses

204

Successful Response

application/json

objectOptional

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: */*

{}