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

Tenant Id

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

tenant_unit_idstring · nullableOptional

Tenant Unit ID

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

Body

created_bystring · nullableOptional

updated_bystring · nullableOptional

created_by_rolestring · nullableOptional

updated_by_rolestring · nullableOptional

created_timestring · date-time · nullableOptional

updated_timestring · date-time · nullableOptional

owner_idstring · nullableOptional

The ID of the flow this definition belongs to

Example: uuid-of-flow

owner_typeobject · nullableOptional

Type of flow [flow, tool]

Example: flow

modestring · nullableOptional

Flow mode, e.g., chat or job

Example: job

versionstring · nullableOptional

Version of the flow

Example: draft

graphobject · GraphOptional

Flow graph

Default: {}Example: {}

featuresobject · Features · nullableOptional

Additional features for the flow

Example: {}

flow_variablesobject · Flow Variables · nullableOptional

Environment variables for the flow

Example: {}

Responses

201

Successful Response

application/json

Full flow model with additional fields used for responses.

created_bystringRequired

ID of the creator

Example: user123

updated_bystring · nullableOptional

ID of the last updater

Example: user124

created_by_rolestring · nullableOptional

updated_by_rolestring · nullableOptional

created_timestring · date-timeOptional

Timestamp of creation

updated_timestring · date-timeOptional

Timestamp of last update

owner_idstring · nullableOptional

The ID of the flow this definition belongs to

Example: uuid-of-flow

owner_typestring · enum · nullableOptional

Type of flow [flow, tool]

Example: flowPossible values:

modestring · nullableOptional

Flow mode, e.g., chat or job

Example: job

versionstring · nullableOptional

Version of the flow

Example: draft

graphobject · Graph · nullableOptional

Flow graph

Example: {}

featuresobject · Features · nullableOptional

Additional features for the flow

Example: {}

flow_variablesobject · Flow Variables · nullableOptional

Environment variables for the flow

Example: {}

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/tools/{tool_id}/flows

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-07-16T06:48:55.153Z",
  "updated_time": "2026-07-16T06:48:55.153Z",
  "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_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

Full flow model with additional fields used for responses.

created_bystringRequired

ID of the creator

Example: user123

updated_bystring · nullableOptional

ID of the last updater

Example: user124

created_by_rolestring · nullableOptional

updated_by_rolestring · nullableOptional

created_timestring · date-timeOptional

Timestamp of creation

updated_timestring · date-timeOptional

Timestamp of last update

owner_idstring · nullableOptional

The ID of the flow this definition belongs to

Example: uuid-of-flow

owner_typestring · enum · nullableOptional

Type of flow [flow, tool]

Example: flowPossible values:

modestring · nullableOptional

Flow mode, e.g., chat or job

Example: job

versionstring · nullableOptional

Version of the flow

Example: draft

graphobject · Graph · nullableOptional

Flow graph

Example: {}

featuresobject · Features · nullableOptional

Additional features for the flow

Example: {}

flow_variablesobject · Flow Variables · nullableOptional

Environment variables for the flow

Example: {}

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

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-07-16T06:48:55.153Z",
  "updated_time": "2026-07-16T06:48:55.153Z",
  "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_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

Response model for the created FlowDefinitionDO.

created_bystringRequired

ID of the creator

Example: user123

updated_bystring · nullableOptional

ID of the last updater

Example: user124

created_by_rolestring · nullableOptional

updated_by_rolestring · nullableOptional

created_timestring · date-timeOptional

Timestamp of creation

updated_timestring · date-timeOptional

Timestamp of last update

owner_idstring · nullableOptional

The ID of the flow this definition belongs to

Example: uuid-of-flow

owner_typestring · enum · nullableOptional

Type of flow [flow, tool]

Example: flowPossible values:

modestring · nullableOptional

Flow mode, e.g., chat or job

Example: job

versionstring · nullableOptional

Version of the flow

Example: draft

graphobject · Graph · nullableOptional

Flow graph

Example: {}

featuresobject · Features · nullableOptional

Additional features for the flow

Example: {}

flow_variablesobject · Flow Variables · nullableOptional

Environment variables for the flow

Example: {}

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

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-07-16T06:48:55.153Z",
  "updated_time": "2026-07-16T06:48:55.153Z",
  "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_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

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

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

Tenant Id

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

tenant_unit_idstring · nullableOptional

Tenant Unit ID

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

Body

Responses

200

Successful Response

application/json

stringOptional

422

Validation Error

application/json

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

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

PreviousAgent NextAgent Operations

Last updated 1 year ago

Was this helpful?