Home PageLogin

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

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
post
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": "2025-07-16T16:58:58.331Z",
  "updated_time": "2025-07-16T16:58:58.331Z",
  "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
get
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": "2025-07-16T16:58:58.331Z",
      "updated_time": "2025-07-16T16:58:58.331Z",
      "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
get
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": "2025-07-16T16:58:58.331Z",
  "updated_time": "2025-07-16T16:58:58.331Z",
  "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
get
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": "2025-07-16T16:58:58.331Z",
  "updated_time": "2025-07-16T16:58:58.331Z",
  "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
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
put
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": "2025-07-16T16:58:58.331Z",
  "updated_time": "2025-07-16T16:58:58.331Z",
  "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
Responseobject
delete
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
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
Responsestring
post
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
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 · InterruptInputsRequired
is_interruptedbooleanRequired
flow_run_idstringRequired
Responses
200
Successful Response
application/json
Responsestring
post
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
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
Responsestring
post
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
PreviousAgent FlowsNextAgent Instructions

Last updated

Was this helpful?