Agentic AI · Orchestrate
Agent Workflows
The graphs. What runs is the PUBLISHED SNAPSHOT, not what is on the canvas — so editing a workflow while a run is in flight changes nothing about that run.
/api/agentic/workflowsPublished as /api/v1/workflowsDownload specification (OpenAPI 3.1) Screen: Agent Workflows
Overview
| Package | Agentic AI |
|---|---|
| Authentication | Bearer token: a service account's token (POST /api/auth/service-token) or, for the published path, an API key |
| Authorization | The caller's roles must hold Agentic AI › Agent Workflows on the Roles screen: display for GET, add for POST, change for PUT, delete for DELETE; an action needs the grant of the button that runs it on the screen. |
| Table | agent.workflows · kept per company (and organisational unit where it has one) |
| Record | Created, changed and (where the screen allows) deleted; key id |
| Rules | The same as the screen: validation, numbering, approvals, posting, the company the caller belongs to, and the audit trail. |
API reference
12 operations. Open one for its parameters, bodies, responses and a sample request.
GET/api/agentic/workflowsList agent workflows
Query parameters
| Name | Description | Example |
|---|---|---|
limit | Rows per page (50 by default, at most 200) | limit=100 |
offset | Rows to skip | offset=200 |
q | Free-text search over the search columns | q=acme |
sort | column:asc or column:desc, several separated by commas | sort=created_at:desc |
filter | A JSON condition or group (see the filter language), URL-encoded; any field below can be filtered and sorted | filter={"col":"status","op":"eq","value":"open"} |
<field>=<value> | Shorthand for "field is value" |
Response 200
{
"rows": [
{
"id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"org_unit_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"workflow_no": "WOR-000001",
"code": "COD-000001",
"name": "Example",
"name_local": "Example",
"description": "text",
"description_local": "text",
"module": "agentic",
"category": "text",
"template_code": "TEM-000001",
"orchestration": "text",
"supervisor_agent_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"input_schema": {}
}
],
"count": 1
}Sample request
curl "https://demo.tranxact.ai/api/agentic/workflows?limit=20" \
-H "Authorization: Bearer $TOKEN"GET/api/agentic/workflows/{id}Read one workflows
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Response 200
{
"id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"org_unit_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"workflow_no": "WOR-000001",
"code": "COD-000001",
"name": "Example",
"name_local": "Example",
"description": "text",
"description_local": "text",
"module": "agentic",
"category": "text",
"template_code": "TEM-000001",
"orchestration": "text",
"supervisor_agent_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"input_schema": {}
}404 when no record with that id is visible to the caller.
Sample request
curl "https://demo.tranxact.ai/api/agentic/workflows/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
-H "Authorization: Bearer $TOKEN"POST/api/agentic/workflowsCreate a workflows
Request body
The record as JSON. Fields marked Yes are required.
| Field | Type | Required | Description |
|---|---|---|---|
code | text | Yes | Code |
name | text | Yes | Name |
name_local | text | No | Local name |
description | text | No | What it does |
description_local | text | No | Description local |
module | text | No | Module Allowed: agentic crm scm accounting hrms mfg ats ehr slcm platform |
category | text | No | Kind of work |
template_code | text | No | Template code |
orchestration | text | No | Pattern |
supervisor_agent_id | uuid | No | Supervisor — Only for the supervisor pattern: the agent that decides which of the others runs next. |
input_schema | jsonb | No | Input schema |
output_schema | jsonb | No | Output schema |
max_steps | integer | No | Step limit — The most steps one run of this workflow may take, counting every node it passes through. The run is stopped when it reaches this, rather than left to go round a loop. Whole number from 1 to 2000. |
max_run_seconds | integer | No | Time limit (seconds) — How long one run may take from start to finish, in seconds (e.g. 3600 for an hour), not counting time spent waiting for a person. A run still going when the time is up is stopped. The agent's own time limit applies as well, and the lower one stops the run. Whole number from 1 to 86400 (a day). |
max_cost_per_run | numeric | No | Cost ceiling per run — In the company currency. The most one run of the whole workflow may cost, across all its agents. It is checked before every step, the first one included, and the run is stopped as soon as it has cost this much or more. Each agent's own ceilings and the company guardrails apply as well, and whichever is lower stops the run. Empty: no ceiling of its own. 0 is not "no ceiling": it stops every run before its first step, even on a model that costs nothing (to keep the workflow from running, untick Active instead). |
max_parallel | integer | No | Branches at once — How many fanned-out branches of one run are meant to work at the same time. Today a run takes the branches of a fan-out one after another, in their order, so this number is kept with the workflow but does not change how a run goes. Whole number from 1 to 32. |
on_failure | text | No | When a node fails — What the run is meant to do when a step fails: Stop the run, Carry on, Retry, Undo what was done, or Escalate to a person. Today a failed step follows that step's error connection on the canvas (a connection of kind error) if it has one, and otherwise the run stops as failed, saying which step failed and why, whatever is chosen here. Escalate to a person also tells people: when a run fails, or is stopped part-way by a step limit, time limit or cost ceiling, the people its Ask a person steps name, the person who made the workflow and the person who started the run are sent a message saying why it stopped and what it had already made (kept on What Agents Produced, with no later step having seen it). Carry on, Retry and Undo are kept with the workflow but are not acted on yet. |
retry_limit | integer | No | Retries — How many times a failed step is meant to be tried again before When a node fails applies. Today a failed step is not tried again: it follows its error connection, or the run stops as failed. Whole number from 0 to 10. |
concurrency | text | No | Overlapping runs — What happens when a new run of this workflow is started (by Run it, a trigger or another workflow) while an earlier run of it is still going, or waiting for a person to approve or answer. One at a time: the new run is refused, saying which run is in progress and what it waits for; answer or cancel that run first. Suits a nightly sweep or a weekly review. Side by side: the new run starts at once, beside the other; each run works on its own. Suits an agent that works on one record at a time. Wait in line: meant to start the new run once the earlier one has finished. Today it starts at once, as with Side by side, so choose One at a time where overlapping runs must not happen. Allowed: One at a time Side by side Wait in line |
canvas | jsonb | No | Canvas |
notes | text | No | Notes |
is_active | boolean | No | Active |
Sample body
{
"code": "COD-000001",
"name": "Example",
"name_local": "Example",
"description": "text",
"description_local": "text",
"module": "agentic"
}Response 201
{
"id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"org_unit_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"workflow_no": "WOR-000001",
"code": "COD-000001",
"name": "Example",
"name_local": "Example",
"description": "text",
"description_local": "text",
"module": "agentic",
"category": "text",
"template_code": "TEM-000001",
"orchestration": "text",
"supervisor_agent_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"input_schema": {}
}Sample request
curl -X POST "https://demo.tranxact.ai/api/agentic/workflows" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"code":"COD-000001","name":"Example","name_local":"Example","description":"text","description_local":"text","module":"agentic"}'PUT/api/agentic/workflows/{id}Change a workflows
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Request body
Only the fields to change; fields left out keep their value.
| Field | Type | Required | Description |
|---|---|---|---|
code | text | Yes | Code |
name | text | Yes | Name |
name_local | text | No | Local name |
description | text | No | What it does |
description_local | text | No | Description local |
module | text | No | Module Allowed: agentic crm scm accounting hrms mfg ats ehr slcm platform |
category | text | No | Kind of work |
template_code | text | No | Template code |
orchestration | text | No | Pattern |
supervisor_agent_id | uuid | No | Supervisor — Only for the supervisor pattern: the agent that decides which of the others runs next. |
input_schema | jsonb | No | Input schema |
output_schema | jsonb | No | Output schema |
max_steps | integer | No | Step limit — The most steps one run of this workflow may take, counting every node it passes through. The run is stopped when it reaches this, rather than left to go round a loop. Whole number from 1 to 2000. |
max_run_seconds | integer | No | Time limit (seconds) — How long one run may take from start to finish, in seconds (e.g. 3600 for an hour), not counting time spent waiting for a person. A run still going when the time is up is stopped. The agent's own time limit applies as well, and the lower one stops the run. Whole number from 1 to 86400 (a day). |
max_cost_per_run | numeric | No | Cost ceiling per run — In the company currency. The most one run of the whole workflow may cost, across all its agents. It is checked before every step, the first one included, and the run is stopped as soon as it has cost this much or more. Each agent's own ceilings and the company guardrails apply as well, and whichever is lower stops the run. Empty: no ceiling of its own. 0 is not "no ceiling": it stops every run before its first step, even on a model that costs nothing (to keep the workflow from running, untick Active instead). |
max_parallel | integer | No | Branches at once — How many fanned-out branches of one run are meant to work at the same time. Today a run takes the branches of a fan-out one after another, in their order, so this number is kept with the workflow but does not change how a run goes. Whole number from 1 to 32. |
on_failure | text | No | When a node fails — What the run is meant to do when a step fails: Stop the run, Carry on, Retry, Undo what was done, or Escalate to a person. Today a failed step follows that step's error connection on the canvas (a connection of kind error) if it has one, and otherwise the run stops as failed, saying which step failed and why, whatever is chosen here. Escalate to a person also tells people: when a run fails, or is stopped part-way by a step limit, time limit or cost ceiling, the people its Ask a person steps name, the person who made the workflow and the person who started the run are sent a message saying why it stopped and what it had already made (kept on What Agents Produced, with no later step having seen it). Carry on, Retry and Undo are kept with the workflow but are not acted on yet. |
retry_limit | integer | No | Retries — How many times a failed step is meant to be tried again before When a node fails applies. Today a failed step is not tried again: it follows its error connection, or the run stops as failed. Whole number from 0 to 10. |
concurrency | text | No | Overlapping runs — What happens when a new run of this workflow is started (by Run it, a trigger or another workflow) while an earlier run of it is still going, or waiting for a person to approve or answer. One at a time: the new run is refused, saying which run is in progress and what it waits for; answer or cancel that run first. Suits a nightly sweep or a weekly review. Side by side: the new run starts at once, beside the other; each run works on its own. Suits an agent that works on one record at a time. Wait in line: meant to start the new run once the earlier one has finished. Today it starts at once, as with Side by side, so choose One at a time where overlapping runs must not happen. Allowed: One at a time Side by side Wait in line |
canvas | jsonb | No | Canvas |
notes | text | No | Notes |
is_active | boolean | No | Active |
Sample body
{
"code": "COD-000001",
"name": "Example"
}Response 200
{
"id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"org_unit_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"workflow_no": "WOR-000001",
"code": "COD-000001",
"name": "Example",
"name_local": "Example",
"description": "text",
"description_local": "text",
"module": "agentic",
"category": "text",
"template_code": "TEM-000001",
"orchestration": "text",
"supervisor_agent_id": "3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73",
"input_schema": {}
}Sample request
curl -X PUT "https://demo.tranxact.ai/api/agentic/workflows/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"code":"COD-000001","name":"Example"}'DELETE/api/agentic/workflows/{id}Delete a workflows
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Response 200
{ "deleted": true }Many documents are cancelled or reversed instead; the API refuses a delete the screen would refuse.
Sample request
curl -X DELETE "https://demo.tranxact.ai/api/agentic/workflows/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73" \
-H "Authorization: Bearer $TOKEN"POST/api/agentic/workflows/{id}/copyCopy
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Request body
The keys this action reads (* = required; "one of" lists the only values):
overrides, preview, withLinesResponse
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X POST "https://demo.tranxact.ai/api/agentic/workflows/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/copy" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"overrides":"value","preview":"value","withLines":"value"}'GET/api/agentic/workflows/{id}/graphGraph
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Response
200 with the data as JSON.
Sample request
curl "https://demo.tranxact.ai/api/agentic/workflows/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/graph" \
-H "Authorization: Bearer $TOKEN"PUT/api/agentic/workflows/{id}/graphGraph
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Request body
The keys this action reads (* = required; "one of" lists the only values):
asNewVersion, edges, canvas; nodes: [{ key, label, labelLocal, kind, description, agentId, toolId, subflowId, prompt, arguments, outputKey, condition, loopOver, loopMax, approverRole, approverUserId, slaHours, compensateToolId, compensateArgs, retryLimit, timeoutSeconds, onError, x, y, color, icon }]Response
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X PUT "https://demo.tranxact.ai/api/agentic/workflows/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/graph" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"asNewVersion":"value","edges":"value","canvas;":"value","label":"value","labelLocal":"value","kind":"value"}'POST/api/agentic/workflows/{id}/validateValidate
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
No body is required.
Response
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X POST "https://demo.tranxact.ai/api/agentic/workflows/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/validate" \
-H "Authorization: Bearer $TOKEN"POST/api/agentic/workflows/{id}/publishPublish
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Request body
The keys this action reads (* = required; "one of" lists the only values):
noteResponse
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X POST "https://demo.tranxact.ai/api/agentic/workflows/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/publish" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"note":"value"}'POST/api/agentic/workflows/{id}/runRun
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Request body
The keys this action reads (* = required; "one of" lists the only values):
input, subjectResponse
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X POST "https://demo.tranxact.ai/api/agentic/workflows/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/run" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"input":"value","subject":"value"}'POST/api/agentic/workflows/{id}/duplicateDuplicate
Path parameters
| Name | Type | Description |
|---|---|---|
id | string (uuid) | The record's id, as a list returns it. |
Request body
The keys this action reads (* = required; "one of" lists the only values):
nameResponse
200 or 201 with the record or result as JSON; a refusal is 409 or 422 with a sentence saying why.
Sample request
curl -X POST "https://demo.tranxact.ai/api/agentic/workflows/3f1c2a9e-5b7d-4c1e-9a2f-0d4b8e6c1a73/duplicate" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"value"}'Data model
Every field of a workflows, as the API returns it. Field names are the JSON keys; any of them can be filtered and sorted on a list.
| Field | Type | Access | Description |
|---|---|---|---|
id | uuid | read only | Id |
org_id | uuid | read only | Org id |
org_unit_id | uuid | read only | Org unit id |
workflow_no | text | read only | Workflow no |
code | text | read, write | Code |
name | text | read, write | Name |
name_local | text | read, write | Local name |
description | text | read, write | What it does |
description_local | text | read, write | Description local |
module | text | read, write | Module Allowed: agentic crm scm accounting hrms mfg ats ehr slcm platform |
category | text | read, write | Kind of work |
template_code | text | read, write | Template code |
orchestration | text | read, write | Pattern |
supervisor_agent_id | uuid | read, write | Supervisor — Only for the supervisor pattern: the agent that decides which of the others runs next. |
input_schema | jsonb | read, write | Input schema |
output_schema | jsonb | read, write | Output schema |
max_steps | integer | read, write | Step limit — The most steps one run of this workflow may take, counting every node it passes through. The run is stopped when it reaches this, rather than left to go round a loop. Whole number from 1 to 2000. |
max_run_seconds | integer | read, write | Time limit (seconds) — How long one run may take from start to finish, in seconds (e.g. 3600 for an hour), not counting time spent waiting for a person. A run still going when the time is up is stopped. The agent's own time limit applies as well, and the lower one stops the run. Whole number from 1 to 86400 (a day). |
max_cost_per_run | numeric | read, write | Cost ceiling per run — In the company currency. The most one run of the whole workflow may cost, across all its agents. It is checked before every step, the first one included, and the run is stopped as soon as it has cost this much or more. Each agent's own ceilings and the company guardrails apply as well, and whichever is lower stops the run. Empty: no ceiling of its own. 0 is not "no ceiling": it stops every run before its first step, even on a model that costs nothing (to keep the workflow from running, untick Active instead). |
max_parallel | integer | read, write | Branches at once — How many fanned-out branches of one run are meant to work at the same time. Today a run takes the branches of a fan-out one after another, in their order, so this number is kept with the workflow but does not change how a run goes. Whole number from 1 to 32. |
on_failure | text | read, write | When a node fails — What the run is meant to do when a step fails: Stop the run, Carry on, Retry, Undo what was done, or Escalate to a person. Today a failed step follows that step's error connection on the canvas (a connection of kind error) if it has one, and otherwise the run stops as failed, saying which step failed and why, whatever is chosen here. Escalate to a person also tells people: when a run fails, or is stopped part-way by a step limit, time limit or cost ceiling, the people its Ask a person steps name, the person who made the workflow and the person who started the run are sent a message saying why it stopped and what it had already made (kept on What Agents Produced, with no later step having seen it). Carry on, Retry and Undo are kept with the workflow but are not acted on yet. |
retry_limit | integer | read, write | Retries — How many times a failed step is meant to be tried again before When a node fails applies. Today a failed step is not tried again: it follows its error connection, or the run stops as failed. Whole number from 0 to 10. |
concurrency | text | read, write | Overlapping runs — What happens when a new run of this workflow is started (by Run it, a trigger or another workflow) while an earlier run of it is still going, or waiting for a person to approve or answer. One at a time: the new run is refused, saying which run is in progress and what it waits for; answer or cancel that run first. Suits a nightly sweep or a weekly review. Side by side: the new run starts at once, beside the other; each run works on its own. Suits an agent that works on one record at a time. Wait in line: meant to start the new run once the earlier one has finished. Today it starts at once, as with Side by side, so choose One at a time where overlapping runs must not happen. Allowed: One at a time Side by side Wait in line |
version | integer | read only | Version |
published_version | integer | read only | Published version |
status | text | read only | Status |
canvas | jsonb | read, write | Canvas |
last_run_at | timestamp with time zone | read only | Last run at |
run_count | bigint | read only | Run count |
success_count | bigint | read only | Success count |
failure_count | bigint | read only | Failure count |
avg_seconds | integer | read only | Avg seconds |
total_cost | numeric | read only | Total cost |
notes | text | read, write | Notes |
is_active | boolean | read, write | Active |
created_at | timestamp with time zone | read only | Created at |
created_by | uuid | read only | Created by |
updated_at | timestamp with time zone | read only | Updated at |
updated_by | uuid | read only | Updated by |
xf_text_1 | text | read only | Xf text 1 |
xf_text_2 | text | read only | Xf text 2 |
xf_text_3 | text | read only | Xf text 3 |
xf_text_4 | text | read only | Xf text 4 |
xf_text_5 | text | read only | Xf text 5 |
xf_num_1 | numeric | read only | Xf num 1 |
xf_num_2 | numeric | read only | Xf num 2 |
xf_num_3 | numeric | read only | Xf num 3 |
xf_date_1 | date | read only | Xf date 1 |
xf_date_2 | date | read only | Xf date 2 |
Errors
| Status | Meaning |
|---|---|
| 400 | The request could not be read: a filter that is not JSON, a bad parameter |
| 401 | No credential, or it is wrong, revoked or expired |
| 403 | The caller's roles do not hold Agentic AI › Agent Workflows for this verb, or the address or origin is not allowed |
| 404 | No record with that id is visible to the caller |
| 409 | A conflict: a duplicate number, a document in a state that does not allow it, or a record changed or locked by someone else |
| 422 | Refused by the same validation as the screen; the error names the field and why |
Every error is JSON: {"error": "a sentence saying what was wrong"}, with field where it applies.