Agent Flows

Manage conversational flows for agents. Use these APIs to create, update, retrieve, publish, list, and run draft flows. Ideal for designing, testing, and deploying multi-step agent behaviors.

Create Or Update Draft Flow Tool

post

Path parameters

tool_idstring · uuidRequired

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

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

owner_idany ofOptional

The ID of the flow this definition belongs to

Example: uuid-of-flow

stringOptional

or

nullOptional

owner_typeany ofOptional

Type of flow [flow, tool]

Example: flow

objectOptional

or

nullOptional

modeany ofOptional

Flow mode, e.g., chat or job

Example: job

stringOptional

or

nullOptional

versionany ofOptional

Version of the flow

Example: draft

stringOptional

or

nullOptional

graphobject · GraphOptional

Flow graph

Default: {}Example: {}

featuresany ofOptional

Additional features for the flow

Example: {}

objectOptional

or

nullOptional

flow_variablesany ofOptional

Environment variables for the flow

Example: {}

objectOptional

or

nullOptional

conversation_variablesany ofOptional

Conversation variables for the flow

Example: {}

or

nullOptional

Responses

201

Successful Response

application/json

422

Validation Error

application/json

post

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

HTTPcURLJavaScriptPython

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

{
  "graph": {}
}

{
  "created_by": "user123",
  "updated_by": "user124",
  "created_by_role": "text",
  "updated_by_role": "text",
  "created_time": "2026-04-03T08:02:24.384Z",
  "updated_time": "2026-04-03T08:02:24.384Z",
  "owner_id": "uuid-of-flow",
  "owner_type": "flow",
  "mode": "job",
  "version": "draft",
  "graph": {},
  "features": {},
  "flow_variables": {},
  "conversation_variables": {},
  "id": "uuid-of-definition",
  "tenant_id": "uuid-of-tenant",
  "tenant_unit_id": "tenant-unit-id"
}

Get Draft

get

Get the DRAFT version of a flow

Path parameters

agent_idstring · uuidRequired

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

Full flow model with additional fields used for responses.

created_bystringRequired

ID of the creator

Example: user123

updated_byany ofOptional

ID of the last updater

Example: user124

stringOptional

or

nullOptional

created_by_roleany ofOptional

stringOptional

or

nullOptional

updated_by_roleany ofOptional

stringOptional

or

nullOptional

created_timestring · date-timeOptional

Timestamp of creation

updated_timestring · date-timeOptional

Timestamp of last update

owner_idany ofOptional

The ID of the flow this definition belongs to

Example: uuid-of-flow

stringOptional

or

nullOptional

owner_typeany ofOptional

Type of flow [flow, tool]

Example: flow

string · enumOptionalPossible values:

or

nullOptional

modeany ofOptional

Flow mode, e.g., chat or job

Example: job

stringOptional

or

nullOptional

versionany ofOptional

Version of the flow

Example: draft

stringOptional

or

nullOptional

graphany ofOptional

Flow graph

Example: {}

objectOptional

or

nullOptional

featuresany ofOptional

Additional features for the flow

Example: {}

objectOptional

or

nullOptional

flow_variablesany ofOptional

Environment variables for the flow

Example: {}

objectOptional

or

nullOptional

conversation_variablesany ofOptional

Conversation variables for the flow

Example: {}

or

nullOptional

idstringRequired

The ID of the created FlowDefinitionDO

Example: uuid-of-definition

tenant_idstringRequired

Tenant ID

Example: uuid-of-tenant

tenant_unit_idstringRequired

Tenant Unit ID

Example: tenant-unit-id

422

Validation Error

application/json

get

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

HTTPcURLJavaScriptPython

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

{
  "created_by": "user123",
  "updated_by": "user124",
  "created_by_role": "text",
  "updated_by_role": "text",
  "created_time": "2026-04-03T08:02:24.384Z",
  "updated_time": "2026-04-03T08:02:24.384Z",
  "owner_id": "uuid-of-flow",
  "owner_type": "flow",
  "mode": "job",
  "version": "draft",
  "graph": {},
  "features": {},
  "flow_variables": {},
  "conversation_variables": {},
  "id": "uuid-of-definition",
  "tenant_id": "uuid-of-tenant",
  "tenant_unit_id": "tenant-unit-id"
}

Publish

post

Publish the current DRAFT version as a formal version

Path parameters

agent_idstring · uuidRequired

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

Response model for the created FlowDefinitionDO.

created_bystringRequired

ID of the creator

Example: user123

updated_byany ofOptional

ID of the last updater

Example: user124

stringOptional

or

nullOptional

created_by_roleany ofOptional

stringOptional

or

nullOptional

updated_by_roleany ofOptional

stringOptional

or

nullOptional

created_timestring · date-timeOptional

Timestamp of creation

updated_timestring · date-timeOptional

Timestamp of last update

owner_idany ofOptional

The ID of the flow this definition belongs to

Example: uuid-of-flow

stringOptional

or

nullOptional

owner_typeany ofOptional

Type of flow [flow, tool]

Example: flow

string · enumOptionalPossible values:

or

nullOptional

modeany ofOptional

Flow mode, e.g., chat or job

Example: job

stringOptional

or

nullOptional

versionany ofOptional

Version of the flow

Example: draft

stringOptional

or

nullOptional

graphany ofOptional

Flow graph

Example: {}

objectOptional

or

nullOptional

featuresany ofOptional

Additional features for the flow

Example: {}

objectOptional

or

nullOptional

flow_variablesany ofOptional

Environment variables for the flow

Example: {}

objectOptional

or

nullOptional

conversation_variablesany ofOptional

Conversation variables for the flow

Example: {}

or

nullOptional

idstringRequired

The ID of the created FlowDefinitionDO

Example: uuid-of-definition

tenant_idstringRequired

Tenant ID

Example: uuid-of-tenant

tenant_unit_idstringRequired

Tenant Unit ID

Example: tenant-unit-id

422

Validation Error

application/json

post

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

HTTPcURLJavaScriptPython

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

{
  "created_by": "user123",
  "updated_by": "user124",
  "created_by_role": "text",
  "updated_by_role": "text",
  "created_time": "2026-04-03T08:02:24.384Z",
  "updated_time": "2026-04-03T08:02:24.384Z",
  "owner_id": "uuid-of-flow",
  "owner_type": "flow",
  "mode": "job",
  "version": "draft",
  "graph": {},
  "features": {},
  "flow_variables": {},
  "conversation_variables": {},
  "id": "uuid-of-definition",
  "tenant_id": "uuid-of-tenant",
  "tenant_unit_id": "tenant-unit-id"
}

List Versions

get

Get a list of all versions for a specific flow

Path parameters

agent_idstring · uuidRequired

Agent id

Query parameters

page_numintegerOptional

Current page number

Default: 1

page_sizeintegerOptional

Items per page

Default: 20

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

Response model for the created flowDefinition.

page_numintegerRequired

Current page number

page_sizeintegerRequired

Number of items per page

total_countintegerRequired

Total number of flows

has_next_pagebooleanRequired

Whether there is a next page

dataobject[]Required

List of flow_definitions

422

Validation Error

application/json

get

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

HTTPcURLJavaScriptPython

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

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

Run Draft Workflow

post

Run the draft version of the workflow

Path parameters

agent_idstring · uuidRequiredExample: 22a976a1-4f6d-4357-a167-26684daa60c5

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

or

Responses

200

Successful Response

application/json

stringOptional

422

Validation Error

application/json

post

/admin/api/v2/agents/{agent_id}/flows/draft/runs

HTTPcURLJavaScriptPython

POST /admin/api/v2/agents/{agent_id}/flows/draft/runs 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