TRANXACT.AI Help

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.

Type REST12 operationsBase path /api/agentic/workflowsPublished as /api/v1/workflows

Download specification (OpenAPI 3.1) Screen: Agent Workflows

Overview

PackageAgentic AI
AuthenticationBearer token: a service account's token (POST /api/auth/service-token) or, for the published path, an API key
AuthorizationThe 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.
Tableagent.workflows · kept per company (and organisational unit where it has one)
RecordCreated, changed and (where the screen allows) deleted; key id
RulesThe 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

NameDescriptionExample
limitRows per page (50 by default, at most 200)limit=100
offsetRows to skipoffset=200
qFree-text search over the search columnsq=acme
sortcolumn:asc or column:desc, several separated by commassort=created_at:desc
filterA JSON condition or group (see the filter language), URL-encoded; any field below can be filtered and sortedfilter={"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

NameTypeDescription
idstring (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.

FieldTypeRequiredDescription
codetextYesCode
nametextYesName
name_localtextNoLocal name
descriptiontextNoWhat it does
description_localtextNoDescription local
moduletextNoModule
Allowed: agentic crm scm accounting hrms mfg ats ehr slcm platform
categorytextNoKind of work
template_codetextNoTemplate code
orchestrationtextNoPattern
supervisor_agent_iduuidNoSupervisor — Only for the supervisor pattern: the agent that decides which of the others runs next.
input_schemajsonbNoInput schema
output_schemajsonbNoOutput schema
max_stepsintegerNoStep 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_secondsintegerNoTime 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_runnumericNoCost 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_parallelintegerNoBranches 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_failuretextNoWhen 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_limitintegerNoRetries — 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.
concurrencytextNoOverlapping 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
canvasjsonbNoCanvas
notestextNoNotes
is_activebooleanNoActive

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

NameTypeDescription
idstring (uuid)The record's id, as a list returns it.

Request body

Only the fields to change; fields left out keep their value.

FieldTypeRequiredDescription
codetextYesCode
nametextYesName
name_localtextNoLocal name
descriptiontextNoWhat it does
description_localtextNoDescription local
moduletextNoModule
Allowed: agentic crm scm accounting hrms mfg ats ehr slcm platform
categorytextNoKind of work
template_codetextNoTemplate code
orchestrationtextNoPattern
supervisor_agent_iduuidNoSupervisor — Only for the supervisor pattern: the agent that decides which of the others runs next.
input_schemajsonbNoInput schema
output_schemajsonbNoOutput schema
max_stepsintegerNoStep 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_secondsintegerNoTime 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_runnumericNoCost 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_parallelintegerNoBranches 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_failuretextNoWhen 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_limitintegerNoRetries — 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.
concurrencytextNoOverlapping 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
canvasjsonbNoCanvas
notestextNoNotes
is_activebooleanNoActive

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

NameTypeDescription
idstring (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

NameTypeDescription
idstring (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, withLines

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/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

NameTypeDescription
idstring (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

NameTypeDescription
idstring (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

NameTypeDescription
idstring (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

NameTypeDescription
idstring (uuid)The record's id, as a list returns it.

Request body

The keys this action reads (* = required; "one of" lists the only values):

note

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/publish" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"note":"value"}'
POST/api/agentic/workflows/{id}/runRun

Path parameters

NameTypeDescription
idstring (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, subject

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/run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":"value","subject":"value"}'
POST/api/agentic/workflows/{id}/duplicateDuplicate

Path parameters

NameTypeDescription
idstring (uuid)The record's id, as a list returns it.

Request body

The keys this action reads (* = required; "one of" lists the only values):

name

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/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.

FieldTypeAccessDescription
iduuidread onlyId
org_iduuidread onlyOrg id
org_unit_iduuidread onlyOrg unit id
workflow_notextread onlyWorkflow no
codetextread, writeCode
nametextread, writeName
name_localtextread, writeLocal name
descriptiontextread, writeWhat it does
description_localtextread, writeDescription local
moduletextread, writeModule
Allowed: agentic crm scm accounting hrms mfg ats ehr slcm platform
categorytextread, writeKind of work
template_codetextread, writeTemplate code
orchestrationtextread, writePattern
supervisor_agent_iduuidread, writeSupervisor — Only for the supervisor pattern: the agent that decides which of the others runs next.
input_schemajsonbread, writeInput schema
output_schemajsonbread, writeOutput schema
max_stepsintegerread, writeStep 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_secondsintegerread, writeTime 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_runnumericread, writeCost 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_parallelintegerread, writeBranches 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_failuretextread, writeWhen 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_limitintegerread, writeRetries — 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.
concurrencytextread, writeOverlapping 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
versionintegerread onlyVersion
published_versionintegerread onlyPublished version
statustextread onlyStatus
canvasjsonbread, writeCanvas
last_run_attimestamp with time zoneread onlyLast run at
run_countbigintread onlyRun count
success_countbigintread onlySuccess count
failure_countbigintread onlyFailure count
avg_secondsintegerread onlyAvg seconds
total_costnumericread onlyTotal cost
notestextread, writeNotes
is_activebooleanread, writeActive
created_attimestamp with time zoneread onlyCreated at
created_byuuidread onlyCreated by
updated_attimestamp with time zoneread onlyUpdated at
updated_byuuidread onlyUpdated by
xf_text_1textread onlyXf text 1
xf_text_2textread onlyXf text 2
xf_text_3textread onlyXf text 3
xf_text_4textread onlyXf text 4
xf_text_5textread onlyXf text 5
xf_num_1numericread onlyXf num 1
xf_num_2numericread onlyXf num 2
xf_num_3numericread onlyXf num 3
xf_date_1dateread onlyXf date 1
xf_date_2dateread onlyXf date 2

Errors

StatusMeaning
400The request could not be read: a filter that is not JSON, a bad parameter
401No credential, or it is wrong, revoked or expired
403The caller's roles do not hold Agentic AI › Agent Workflows for this verb, or the address or origin is not allowed
404No record with that id is visible to the caller
409A conflict: a duplicate number, a document in a state that does not allow it, or a record changed or locked by someone else
422Refused 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.