Agent Operations

Manageand operate agents. These endpoints allow you to create, retrieve, update, delete, and interact with agents through chats and background tasks.

Create Agent

post

API Layer: Create a new Agent

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

Request model for creating a workflow. Only includes fields that should be provided by the frontend.

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

created_byany ofOptional

stringOptional

or

nullOptional

updated_byany ofOptional

stringOptional

or

nullOptional

created_by_roleany ofOptional

stringOptional

or

nullOptional

updated_by_roleany ofOptional

stringOptional

or

nullOptional

created_timeany ofOptional

string · date-timeOptional

or

nullOptional

updated_timeany ofOptional

string · date-timeOptional

or

nullOptional

modestring · enumRequired

Workflow mode, e.g., chat or job

Example: jobPossible values:

typestring · enumRequired

Agent type (single-agent, multi-agent) - legacy types (flow, instruction, tool) are deprecated

Example: single-agentPossible values:

namestringRequired

Workflow name

Example: test_workflow_name

descriptionany ofOptional

Workflow description

Default: ""Example: test_description

stringOptional

or

nullOptional

tagsstring[]Optional

List of tags

Default: []Example: test_tag

is_favoritebooleanOptional

Indicates if the item is marked as favorite

Default: false

extend_propertiesany ofOptional

Extend properties

Example: {}

objectOptional

or

nullOptional

Responses

201

Successful Response

application/json

Response model for created workflow, which includes all fields of AgentItem.

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

created_byany ofOptional

stringOptional

or

nullOptional

updated_byany ofOptional

stringOptional

or

nullOptional

created_by_roleany ofOptional

stringOptional

or

nullOptional

updated_by_roleany ofOptional

stringOptional

or

nullOptional

created_timeany ofOptional

string · date-timeOptional

or

nullOptional

updated_timeany ofOptional

string · date-timeOptional

or

nullOptional

modestring · enumRequired

Workflow mode, e.g., chat or job

Example: jobPossible values:

typestringRequired

Agent type (single-agent, multi-agent) - legacy types (flow, instruction, tool) are deprecated

Example: single-agent

namestringRequired

Workflow name

Example: test_workflow_name

descriptionany ofOptional

Workflow description

Default: ""Example: test_description

stringOptional

or

nullOptional

tagsstring[]Optional

List of tags

Default: []Example: test_tag

is_favoritebooleanOptional

Indicates if the item is marked as favorite

Default: false

extend_propertiesany ofOptional

Extend properties

Example: {}

objectOptional

or

nullOptional

idany ofOptional

Workflow ID

Example: 22a976a1-4f6d-4357-a167-26684daa60c5

stringOptional

or

nullOptional

tenant_idstringRequired

Tenant ID of creator

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

tenant_unit_idstringRequired

Tenant Unit ID of creator

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

statusstringOptional

Workflow status

Default: ACTIVEExample: ACTIVE

codeany ofOptional

Workflow status

stringOptional

or

nullOptional

definition_idany ofOptional

Definition id

stringOptional

or

nullOptional

definition_typeany ofOptional

definition_type

string · enumOptionalPossible values:

or

nullOptional

ab_test_idany ofOptional

AB test config ID

stringOptional

or

nullOptional

ab_test_enabledany ofOptional

Indicates if AB testing is enabled

Default: false

booleanOptional

or

nullOptional

usage_guideany ofOptional

Usage guide

stringOptional

or

nullOptional

visibilityany ofOptional

Resource visibility

objectOptional

or

nullOptional

agent_definition_entityany ofOptional

Agent definition entity

objectOptional

or

or

nullOptional

variablesany ofOptional

Variables

object[]Optional

or

nullOptional

icon_urlany ofRead-onlyRequired

stringOptional

or

nullOptional

422

Validation Error

application/json

post

/admin/api/v2/agents

HTTPcURLJavaScriptPython

POST /admin/api/v2/agents HTTP/1.1
Host: api.workfx.ai
Content-Type: application/json
Accept: */*
Content-Length: 260

{
  "description": "A standard chat flow agent for general purposes",
  "icon": "🤖",
  "icon_background": "#EFF1F5",
  "icon_type": "emoji",
  "is_favorite": false,
  "mode": "flow-chat",
  "name": "Standard Chat Flow Agent",
  "tags": [
    "flow",
    "chat",
    "single-agent"
  ],
  "type": "single-agent"
}

{
  "icon_type": "emoji",
  "icon": "text",
  "icon_background": "#FFF",
  "created_by": "text",
  "updated_by": "text",
  "created_by_role": "text",
  "updated_by_role": "text",
  "created_time": "2026-04-03T08:02:25.220Z",
  "updated_time": "2026-04-03T08:02:25.220Z",
  "mode": "job",
  "type": "single-agent",
  "name": "test_workflow_name",
  "description": "test_description",
  "abilities": {
    "file_upload": {
      "enabled": true
    }
  },
  "tags": "test_tag",
  "is_favorite": false,
  "extend_properties": {},
  "id": "22a976a1-4f6d-4357-a167-26684daa60c5",
  "tenant_id": "40d39c4b-9585-4123-8fd4-f1cc23a1184c",
  "tenant_unit_id": "da114de3-d7e6-4161-bc55-0ce85dbee589",
  "status": "ACTIVE",
  "code": "text",
  "definition_id": "text",
  "definition_type": "flow",
  "ab_test_id": "text",
  "ab_test_enabled": false,
  "usage_guide": "text",
  "visibility": {},
  "agent_definition_entity": {},
  "variables": [
    {}
  ],
  "icon_url": "text"
}

List Agents

get

API Layer: Retrieve a list of Agents with pagination and filtering.

Query parameters

page_numintegerOptional

Current page number

Default: 1

page_sizeintegerOptional

Items per page

Default: 20

is_favoriteany ofOptional

Filter by favorite status

booleanOptional

or

nullOptional

tagsany ofOptional

Filter by tags

string[]Optional

or

nullOptional

modeany ofOptional

Filter by mode (flow-chat | flow-job | instruction-chat | multi-agent-flow-chat | multi-agent-flow-job | multi-agent-instruction-chat)

stringOptional

or

nullOptional

nameany ofOptional

Filter by name (fuzzy match)

stringOptional

or

nullOptional

orderany ofOptional

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

Default: recent

stringOptional

or

nullOptional

exclude_draftany ofOptional

Exclude draft agents

Default: false

booleanOptional

or

nullOptional

agent_idsany ofOptional

Filter by agent ids

string[]Optional

or

nullOptional

typeany ofOptional

Filter by agent type ('single-agent' | 'multi-agent')

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

422

Validation Error

application/json

get

/admin/api/v2/agents

HTTPcURLJavaScriptPython

GET /admin/api/v2/agents 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": [
    {
      "icon_type": "emoji",
      "icon": "text",
      "icon_background": "#FFF",
      "created_by": "text",
      "updated_by": "text",
      "created_by_role": "text",
      "updated_by_role": "text",
      "created_time": "2026-04-03T08:02:25.220Z",
      "updated_time": "2026-04-03T08:02:25.220Z",
      "mode": "job",
      "type": "single-agent",
      "name": "test_workflow_name",
      "description": "test_description",
      "abilities": {
        "file_upload": {
          "enabled": true
        }
      },
      "tags": "test_tag",
      "is_favorite": false,
      "extend_properties": {},
      "id": "22a976a1-4f6d-4357-a167-26684daa60c5",
      "tenant_id": "40d39c4b-9585-4123-8fd4-f1cc23a1184c",
      "tenant_unit_id": "da114de3-d7e6-4161-bc55-0ce85dbee589",
      "status": "ACTIVE",
      "code": "text",
      "definition_id": "text",
      "definition_type": "flow",
      "ab_test_id": "text",
      "ab_test_enabled": false,
      "usage_guide": "text",
      "visibility": {},
      "agent_definition_entity": {},
      "variables": [
        {}
      ],
      "icon_url": "text"
    }
  ]
}

Get Agent

get

API Layer: Retrieve a Agent by ID

Path parameters

agent_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/agents/{agent_id}

HTTPcURLJavaScriptPython

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

{
  "icon_type": "emoji",
  "icon": "text",
  "icon_background": "#FFF",
  "created_by": "text",
  "updated_by": "text",
  "created_by_role": "text",
  "updated_by_role": "text",
  "created_time": "2026-04-03T08:02:25.220Z",
  "updated_time": "2026-04-03T08:02:25.220Z",
  "mode": "job",
  "type": "single-agent",
  "name": "test_workflow_name",
  "description": "test_description",
  "abilities": {
    "file_upload": {
      "enabled": true
    }
  },
  "tags": "test_tag",
  "is_favorite": false,
  "extend_properties": {},
  "id": "22a976a1-4f6d-4357-a167-26684daa60c5",
  "tenant_id": "40d39c4b-9585-4123-8fd4-f1cc23a1184c",
  "tenant_unit_id": "da114de3-d7e6-4161-bc55-0ce85dbee589",
  "status": "ACTIVE",
  "code": "text",
  "definition_id": "text",
  "definition_type": "flow",
  "ab_test_id": "text",
  "ab_test_enabled": false,
  "usage_guide": "text",
  "visibility": {},
  "agent_definition_entity": {},
  "variables": [
    {}
  ],
  "icon_url": "text"
}

Get Agent By Code

get

API Layer: Retrieve a Agent by code

Path parameters

agent_codestringRequired

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

/admin/api/v2/agents/code/{agent_code}

HTTPcURLJavaScriptPython

GET /admin/api/v2/agents/code/{agent_code} HTTP/1.1
Host: api.workfx.ai
Accept: */*

{
  "icon_type": "emoji",
  "icon": "text",
  "icon_background": "#FFF",
  "created_by": "text",
  "updated_by": "text",
  "created_by_role": "text",
  "updated_by_role": "text",
  "created_time": "2026-04-03T08:02:25.220Z",
  "updated_time": "2026-04-03T08:02:25.220Z",
  "mode": "job",
  "type": "single-agent",
  "name": "test_workflow_name",
  "description": "test_description",
  "abilities": {
    "file_upload": {
      "enabled": true
    }
  },
  "tags": "test_tag",
  "is_favorite": false,
  "extend_properties": {},
  "id": "22a976a1-4f6d-4357-a167-26684daa60c5",
  "tenant_id": "40d39c4b-9585-4123-8fd4-f1cc23a1184c",
  "tenant_unit_id": "da114de3-d7e6-4161-bc55-0ce85dbee589",
  "status": "ACTIVE",
  "code": "text",
  "definition_id": "text",
  "definition_type": "flow",
  "ab_test_id": "text",
  "ab_test_enabled": false,
  "usage_guide": "text",
  "visibility": {},
  "agent_definition_entity": {},
  "variables": [
    {}
  ],
  "icon_url": "text"
}

Update Agent

put

API Layer: Update an existing Agent

Path parameters

agent_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

icon_typeany ofOptional

Type of icon used

Example: emoji

stringOptional

or

nullOptional

iconany ofOptional

Icon representation

Example: 🤖

stringOptional

or

nullOptional

icon_backgroundany ofOptional

Background color of the icon

Example: #EFF1F5

stringOptional

or

nullOptional

nameany ofOptional

Workflow name

Example: test_workflow_name

stringOptional

or

nullOptional

descriptionany ofOptional

Workflow description

Example: test_description

stringOptional

or

nullOptional

tagsany ofOptional

List of tags

Example: test_tag

string[]Optional

or

nullOptional

is_favoriteany ofOptional

Indicates if the item is marked as favorite

booleanOptional

or

nullOptional

statusany ofOptional

Workflow status

Example: ACTIVE

stringOptional

or

nullOptional

ab_test_idany ofOptional

AB test config ID

string · uuidOptional

or

nullOptional

ab_test_enabledany ofOptional

Indicates if AB testing is enabled

booleanOptional

or

nullOptional

extend_propertiesany ofOptional

Extend properties

Example: {}

objectOptional

or

nullOptional

usage_guideany ofOptional

Usage guide

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

put

/admin/api/v2/agents/{agent_id}

HTTPcURLJavaScriptPython

PUT /admin/api/v2/agents/{agent_id} HTTP/1.1
Host: api.workfx.ai
Content-Type: application/json
Accept: */*
Content-Length: 300

{
  "icon_type": "emoji",
  "icon": "🤖",
  "icon_background": "#EFF1F5",
  "name": "test_workflow_name",
  "description": "test_description",
  "tags": "test_tag",
  "is_favorite": false,
  "status": "ACTIVE",
  "ab_test_id": "123e4567-e89b-12d3-a456-426614174000",
  "ab_test_enabled": false,
  "extend_properties": {},
  "usage_guide": "text"
}

{
  "icon_type": "emoji",
  "icon": "text",
  "icon_background": "#FFF",
  "created_by": "text",
  "updated_by": "text",
  "created_by_role": "text",
  "updated_by_role": "text",
  "created_time": "2026-04-03T08:02:25.220Z",
  "updated_time": "2026-04-03T08:02:25.220Z",
  "mode": "job",
  "type": "single-agent",
  "name": "test_workflow_name",
  "description": "test_description",
  "abilities": {
    "file_upload": {
      "enabled": true
    }
  },
  "tags": "test_tag",
  "is_favorite": false,
  "extend_properties": {},
  "id": "22a976a1-4f6d-4357-a167-26684daa60c5",
  "tenant_id": "40d39c4b-9585-4123-8fd4-f1cc23a1184c",
  "tenant_unit_id": "da114de3-d7e6-4161-bc55-0ce85dbee589",
  "status": "ACTIVE",
  "code": "text",
  "definition_id": "text",
  "definition_type": "flow",
  "ab_test_id": "text",
  "ab_test_enabled": false,
  "usage_guide": "text",
  "visibility": {},
  "agent_definition_entity": {},
  "variables": [
    {}
  ],
  "icon_url": "text"
}

Delete Agent

delete

API Layer: Delete a Agent by ID

Path parameters

agent_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

204

Successful Response

application/json

422

Validation Error

application/json

delete

/admin/api/v2/agents/{agent_id}

HTTPcURLJavaScriptPython

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

{}

Invoke Agent Chat

post

API Layer: Invoke a Agent

Path parameters

agent_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

queryany ofOptionalDefault: ""

stringOptional

or

nullOptional

inputsany ofOptional

Input variables

Example: {"var1":"1","var2":2}

objectOptional

or

nullOptional

streamingbooleanOptionalDefault: false

filesany ofOptionalDefault: []

string[]Optional

or

nullOptional

response_typeany ofOptionalDefault: wfx

stringOptional

or

nullOptional

wfx_contextany ofOptionalDefault: {}

objectOptional

or

nullOptional

conversation_idany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

/admin/api/v2/agents/{agent_id}/chat

HTTPcURLJavaScriptPython

POST /admin/api/v2/agents/{agent_id}/chat HTTP/1.1
Host: api.workfx.ai
Content-Type: application/json
Accept: */*
Content-Length: 142

{
  "query": "",
  "inputs": {
    "var1": "1",
    "var2": 2
  },
  "streaming": false,
  "files": [
    "text"
  ],
  "response_type": "wfx",
  "wfx_context": {},
  "conversation_id": "text"
}

text

Resume Invoke Agent Chat

post

API Layer: Resume Invoke a Agent

Path parameters

agent_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

queryany ofOptionalDefault: ""

stringOptional

or

nullOptional

inputsany ofOptional

Input variables

Example: {"var1":"1","var2":2}

objectOptional

or

nullOptional

streamingbooleanOptionalDefault: false

filesany ofOptionalDefault: []

string[]Optional

or

nullOptional

response_typeany ofOptionalDefault: wfx

stringOptional

or

nullOptional

wfx_contextany ofOptionalDefault: {}

objectOptional

or

nullOptional

conversation_idany ofOptional

stringOptional

or

nullOptional

interrupt_inputsobject · Interrupt InputsRequired

is_interruptedbooleanRequired

flow_run_idstringRequired

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

/admin/api/v2/agents/{agent_id}/chat/resume

HTTPcURLJavaScriptPython

POST /admin/api/v2/agents/{agent_id}/chat/resume HTTP/1.1
Host: api.workfx.ai
Content-Type: application/json
Accept: */*
Content-Length: 207

{
  "query": "",
  "inputs": {
    "var1": "1",
    "var2": 2
  },
  "streaming": false,
  "files": [
    "text"
  ],
  "response_type": "wfx",
  "wfx_context": {},
  "conversation_id": "text",
  "interrupt_inputs": {},
  "is_interrupted": true,
  "flow_run_id": "text"
}

text

Invoke Agent Job

post

API Layer: Invoke a Agent

Path parameters

agent_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

queryany ofOptionalDefault: ""

stringOptional

or

nullOptional

inputsany ofOptional

Input variables

Example: {"var1":"1","var2":2}

objectOptional

or

nullOptional

streamingbooleanOptionalDefault: false

filesany ofOptionalDefault: []

string[]Optional

or

nullOptional

response_typeany ofOptionalDefault: wfx

stringOptional

or

nullOptional

wfx_contextany ofOptionalDefault: {}

objectOptional

or

nullOptional

conversation_idany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

post

/admin/api/v2/agents/{agent_id}/job

HTTPcURLJavaScriptPython

POST /admin/api/v2/agents/{agent_id}/job HTTP/1.1
Host: api.workfx.ai
Content-Type: application/json
Accept: */*
Content-Length: 142

{
  "query": "",
  "inputs": {
    "var1": "1",
    "var2": 2
  },
  "streaming": false,
  "files": [
    "text"
  ],
  "response_type": "wfx",
  "wfx_context": {},
  "conversation_id": "text"
}

text