Workflows

A workflow chains several apps into one flow: a trigger, then the apps that run one after another, with conditions that branch on what the previous app answered. The API is the authoring surface — you create the flow, draw or describe its steps, read back whether it can actually run, activate it and publish it. It is the same object the workspace draws on its canvas, so a flow written here opens in the flow editor and a flow drawn there is readable here.

Endpoints

<workflow_id> is a workflow identifier, prefixed wkfl_.

Important — There is no endpoint that launches a workflow. A run is advanced by the workspace, one step per page load, so a run created from outside it would stay at queued and never move. Launch a flow from its page in the workspace. To run a single app from the API, use Runs instead.

The workflow object

The graph

The drawing is a set of nodes joined by edges.

A flow is ready to run when it has exactly one trigger, at least one app, every app step names an activated app of this project with a usable model, every required field is fed, no condition sits first in the chain, no arrow closes a loop, and every node is reachable from the trigger. When a rule is broken, issues names it — a node-scoped rule reads Step 'n2': ….

A drawing holds at most 60 nodes and 7200 edges.

Note — Anything the canvas would not draw is dropped, not refused: an unknown node type, a coordinate off the grid, an arrow to a node that does not exist, an arrow from a node to itself, a duplicated arrow. The graph in the response is the drawing as it was stored, so read it back to see exactly what was kept.

Pinning a step's fields

By default an app step is fed by the step above it. config.fields overrides that, one entry per field, keyed by the field's name or by its madi_ identifier.

A bare value is shorthand for static: "tone": "formal" is the same as "tone": { "source": "static", "value": "formal" }. An empty object takes the default — previous for text, input for a file.

Create a workflow

POST /v1/workflow/create takes either a drawing or an ordered list of steps.

Send graph when you already have a drawing, steps when you just want the apps to run in order. Each step is { "app": "mapp_… or a name", "fields": {…} } or { "condition": { "operator": "contains", "value": "urgent" } }. Steps are wired to each other in the order you send them, a trigger is minted in front, and a condition passes to the next step on its true branch. Add "on_false" to a condition, naming another step by its number, to wire the other branch.

curl -X POST https://api.thinkhx.com/v1/workflow/create \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Triage then answer",
    "description": "Sort the incoming message, then draft the reply.",
    "steps": [
      { "app": "mapp_0ceacb46e5b3a99e91b6" },
      { "condition": { "operator": "contains", "value": "urgent" } },
      { "app": "mapp_7d3f81b0c25e94a6f01d" }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "wkfl_4a91c7e0d25b83f6a1cd",
    "object": "workflow",
    "name": "Triage then answer",
    "description": "Sort the incoming message, then draft the reply.",
    "type": "private",
    "status": "activated",
    "trigger": "manual",
    "counts": { "app": 2, "condition": 1 },
    "apps": [
      { "id": "mapp_0ceacb46e5b3a99e91b6", "name": "Message triage" },
      { "id": "mapp_7d3f81b0c25e94a6f01d", "name": "Reply drafter" }
    ],
    "graph": {
      "nodes": [
        { "key": "n1", "type": "trigger", "x": 60, "y": 220, "config": {} },
        { "key": "n2", "type": "app", "x": 360, "y": 220, "config": { "app_ident": "mapp_0ceacb46e5b3a99e91b6" } },
        { "key": "n3", "type": "condition", "x": 660, "y": 220, "config": { "operator": "contains", "value": "urgent" } },
        { "key": "n4", "type": "app", "x": 960, "y": 220, "config": { "app_ident": "mapp_7d3f81b0c25e94a6f01d" } }
      ],
      "edges": [
        { "from": "n1", "to": "n2", "branch": "" },
        { "from": "n2", "to": "n3", "branch": "" },
        { "from": "n3", "to": "n4", "branch": "true" }
      ]
    },
    "ready": true,
    "note": null,
    "created_at": 1754209200
  }
}

Creation is the one place an invalid flow is refused: the drawing does not exist yet, so there is nothing to lose by asking for it again.

Sending both graph and steps is not an error: the drawing wins, and the response says so in note: Both 'graph' and 'steps' were provided: 'graph' was used and 'steps' ignored.

Note — A step can only name an app of your own project, even a published one of another project: the flow editor cannot draw a step over an app it does not own, so the step would be wiped the first time the flow is opened. Copy the app into your project first.

List your workflows

GET /v1/workflow/list returns the project's flows, newest first. Deleted flows are excluded.

curl "https://api.thinkhx.com/v1/workflow/list?limit=2" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "data": [
      {
        "id": "wkfl_4a91c7e0d25b83f6a1cd",
        "object": "workflow",
        "name": "Triage then answer",
        "description": "Sort the incoming message, then draft the reply.",
        "type": "private",
        "status": "activated",
        "trigger": "manual",
        "counts": { "app": 2, "condition": 1 },
        "apps": [
          { "id": "mapp_0ceacb46e5b3a99e91b6", "name": "Message triage" },
          { "id": "mapp_7d3f81b0c25e94a6f01d", "name": "Reply drafter" }
        ],
        "runs": { "total": 12, "private": 12, "public": 0 },
        "created_at": 1754209200,
        "updated_at": 1754212800
      }
    ],
    "total": 7
  }
}

A listed row carries no graph, no ready and no issues: a page of drawings is a large answer, and validity costs a handful of queries per flow. Read one flow to get all three.

Read one workflow

GET /v1/workflow/detail/<workflow_id> returns the whole flow, drawing included.

curl https://api.thinkhx.com/v1/workflow/detail/wkfl_4a91c7e0d25b83f6a1cd \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

The graph you read back is the normalised drawing — what the canvas and the engine actually read, with anything unrecognised already dropped. A flow of another project gives 404 and Workflow not found., whether it exists or not.

Edit a workflow

PATCH /v1/workflow/detail/<workflow_id> changes only the fields present in the body.

curl -X PATCH https://api.thinkhx.com/v1/workflow/detail/wkfl_4a91c7e0d25b83f6a1cd \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Triage, then answer" }'

Important — A PATCH carrying a graph always saves the drawing, even when the flow does not validate. It is not refused: the flow is put back to draft in the same write and the answer is still 200, with "ready": false, the failing rules under issues, and note reading The graph was saved but does not validate, so the workflow was set back to draft. This is what the canvas does — a half-drawn flow is saved so you can come back to it. So after a PATCH, read ready and issues, never the HTTP status, to know whether the flow can run.

Activating and publishing are the gates. "status": "activated" and "type": "public" are both refused when the final drawing does not validate, and publishing a flow also requires that it is activated and that every app it chains is itself published.

A field mapping that names no field of its app is a 422 when you send it through steps, but inside a hand-drawn graph it is dropped and reported in note — the drawing is kept either way.

Delete a workflow

DELETE /v1/workflow/detail/<workflow_id> removes the flow from the listings, from the catalogue if it was published, and from the workspace.

curl -X DELETE https://api.thinkhx.com/v1/workflow/detail/wkfl_4a91c7e0d25b83f6a1cd \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": { "deleted": true, "id": "wkfl_4a91c7e0d25b83f6a1cd" }
}

The delete is a soft one: the runs the flow already produced are kept and stay readable. Deleting a flow that is already gone answers 404 and Workflow not found.