Agents

Workflows

Several agents in a fixed order, the designs and the runs

On this page(8 sections)

Saved workflows and their runs
Create or replace a workflow
Delete a workflow
Start a workflow
Every workflow run
Stop a run now
Take a finished run off the board
Bring an archived run back

A workflow is a design: run these conversations, in this order, each handing its result to the next. These routes hold the saved designs and the run history, start a run, stop one in flight, and archive the ones you are done reading.

8 calls. Pick one to open it, or use the list on the right.

GET/workflowsSaved workflows and their runs

Every workflow somebody has designed, each with its own run history, newest first. One answer rather than two, because a workflow that has never been run is the interesting case rather than a mistake.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`workflows`Every saved design with its own…	object[]
`id`The workflow's id	string
`name`What to call it	string
`description`What it is for	string
`steps`The steps, each with what it…	object[]
`id`This step's own name, which other…	string
`title`What to call it on screen	string
`goal`What done means for this step,…	string
`prompt`What the step is told to…	string
`needs`Which steps must finish first	string[]
`handoff`How it meets what came before:…	"fresh" \| "continue"
`output`What it has to produce for…	object
`kind`It produces nothing but its work	"none"
`checks`What has to pass before it…	object[]
`kind`Run something and see if it…	"command"
`command`The command to run in the…	string
`context`How the step's own repeats meet…	"fresh" \| "continue"
`maxSpendUsd`A ceiling on what this step…	number
`agent`Which provider runs it	string
`harness`Which agentic loop runs it	"native" \| "claude-code"
`account`Which account pays for it	string
`model`Which model runs it	string
`actsAs`Which persona it acts as	string
`gate`Present means a machine can run…	object
`step`Which step's answer carries the decision	string
`field`Which of that step's declared answers…	string
`pass`Which values mean ship it	string[]
`token`The credential the calling pipeline presents	string
`dailyMax`How many runs a day, across…	integer
`maxParallel`How many steps may run at…	integer
`runs`Its runs, newest first	object[]
`runId`This run's id	string
`workflow`The design as it stood when…	object
`id`The workflow's id	string
`name`What to call it	string
`description`What it is for	string
`steps`The steps, each with what it…	object[]
`gate`Present means a machine can run…	object
`maxParallel`How many steps may run at…	integer
`repos`The workspace as this run began,…	object[]
`repo`	string
`base`	string
`request`What this run was asked to…	string
`state`How the run is going	"running" \| "done" \| "failed" \| "stopped" … (6)
`startedAt`When it began, in milliseconds	number
`endedAt`When it ended, in milliseconds	number
`resumed`How many times the sandbox restarted…	integer
`detail`What went wrong, when something did	string
`steps`One entry per step, in the…	object[]
`stepId`Which step this is	string
`state`How it went	"pending" \| "running" \| "done" \| "failed" … (6)
`conversationId`The conversation it ran on, and…	string
`startedAt`When it began, in milliseconds	number
`endedAt`When it ended, in milliseconds	number
`iterations`How many rounds it took	integer
`costUsd`What it cost, in dollars	number
`loopState`How its repeating ended	"running" \| "done" \| "exhausted" \| "stalled" … (7)
`detail`What went wrong, when something did	string
`document`What it produced, once it has…	object
`report`The start of its closing words	string
`reportPath`Where the whole answer is, as…	string
`archivedAt`When it was put away, in…	number

Try itanswered in this tab

curl

curl "$SANDBOX/workflows" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.workflows.list();

POST/workflowsCreate or replace a workflow

Writes a workflow design. Say which of the two you mean, so an id that happens to collide cannot silently overwrite somebody's work. A design that could never run is refused, in the same words the editor shows while you type: a loop in the steps, a step waiting on one that is not there, a step with no way of knowing it is finished.

What you send

Field	Type	Where
`workflow`requiredThe design to write	object	body
`id`requiredThe workflow's id	string	body
`name`requiredWhat to call it	string	body
`description`What it is for	string	body
`steps`requiredThe steps, each with what it…	object[]	body
`id`requiredThis step's own name, which other…	string	body
`title`requiredWhat to call it on screen	string	body
`goal`What done means for this step,…	string	body
`prompt`What the step is told to…	string	body
`needs`requiredWhich steps must finish first	string[]	body
`handoff`requiredHow it meets what came before:…	"fresh" \| "continue"	body
`output`requiredWhat it has to produce for…	object	body
`kind`requiredIt produces nothing but its work	"none"	body
`checks`requiredWhat has to pass before it…	object[]	body
`kind`requiredRun something and see if it…	"command"	body
`command`requiredThe command to run in the…	string	body
`context`requiredHow the step's own repeats meet…	"fresh" \| "continue"	body
`maxSpendUsd`A ceiling on what this step…	number	body
`agent`Which provider runs it	string	body
`harness`Which agentic loop runs it	"native" \| "claude-code"	body
`account`Which account pays for it	string	body
`model`Which model runs it	string	body
`actsAs`Which persona it acts as	string	body
`gate`Present means a machine can run…	object	body
`step`requiredWhich step's answer carries the decision	string	body
`field`requiredWhich of that step's declared answers…	string	body
`pass`requiredWhich values mean ship it	string[]	body
`token`The credential the calling pipeline presents	string	body
`dailyMax`How many runs a day, across…	integer	body
`maxParallel`requiredHow many steps may run at…	integer	body
`create`requiredWhether you mean to make a…	boolean	body

What comes back

Field	Type
`id`The workflow's id	string
`name`What to call it	string
`description`What it is for	string
`steps`The steps, each with what it…	object[]
`id`This step's own name, which other…	string
`title`What to call it on screen	string
`goal`What done means for this step,…	string
`prompt`What the step is told to…	string
`needs`Which steps must finish first	string[]
`handoff`How it meets what came before:…	"fresh" \| "continue"
`output`What it has to produce for…	object
`when kind is "none"`	shape
`when kind is "claim"`	shape
`when kind is "json"`	shape
`fields`The shape that answer has to…	object[]
`checks`What has to pass before it…	object[]
`when kind is "command"`	shape
`command`The command to run in the…	string
`when kind is "judge"`	shape
`rubric`What that judge is asked	string
`model`Which model judges	string
`context`How the step's own repeats meet…	"fresh" \| "continue"
`maxSpendUsd`A ceiling on what this step…	number
`agent`Which provider runs it	string
`harness`Which agentic loop runs it	"native" \| "claude-code"
`account`Which account pays for it	string
`model`Which model runs it	string
`actsAs`Which persona it acts as	string
`gate`Present means a machine can run…	object
`step`Which step's answer carries the decision	string
`field`Which of that step's declared answers…	string
`pass`Which values mean ship it	string[]
`token`The credential the calling pipeline presents	string
`dailyMax`How many runs a day, across…	integer
`maxParallel`How many steps may run at…	integer

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/workflows" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"workflow":{"id":"a1b2c3d4","name":"nightly changelog","description":"Runs every night and opens a pull request when anything changed.","steps":[{"id":"a1b2c3d4","title":"Update the changelog","goal":"…","prompt":"Update the changelog for the last five commits.","needs":["…","…"],"handoff":"fresh","output":{},"checks":[],"context":"fresh","maxSpendUsd":1,"agent":"…","harness":"native","account":"work","model":"claude-sonnet-4-6","actsAs":"…"},{"id":"e5f6a7b8","title":"Draft the release notes","goal":"…","prompt":"Update the changelog for the last five commits.","needs":["…","…"],"handoff":"continue","output":{},"checks":[],"context":"continue","maxSpendUsd":1,"agent":"…","harness":"claude-code","account":"work","model":"claude-haiku-4-6","actsAs":"…"}],"gate":{"step":"…","field":"…","pass":["…","…"],"token":"ict_9wQ4rTz8kLmN3pXbV7hJ","dailyMax":1},"maxParallel":1},"create":true}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.workflows.save({
  "workflow": {
    "id": "a1b2c3d4",
    "name": "nightly changelog",
    "description": "Runs every night and opens a pull request when anything changed.",
    "steps": [
      {
        "id": "a1b2c3d4",
        "title": "Update the changelog",
        "goal": "…",
        "prompt": "Update the changelog for the last five commits.",
        "needs": [
          "…",
          "…"
        ],
        "handoff": "fresh",
        "output": {},
        "checks": [],
        "context": "fresh",
        "maxSpendUsd": 1,
        "agent": "…",
        "harness": "native",
        "account": "work",
        "model": "claude-sonnet-4-6",
        "actsAs": "…"
      },
      {
        "id": "e5f6a7b8",
        "title": "Draft the release notes",
        "goal": "…",
        "prompt": "Update the changelog for the last five commits.",
        "needs": [
          "…",
          "…"
        ],
        "handoff": "continue",
        "output": {},
        "checks": [],
        "context": "continue",
        "maxSpendUsd": 1,
        "agent": "…",
        "harness": "claude-code",
        "account": "work",
        "model": "claude-haiku-4-6",
        "actsAs": "…"
      }
    ],
    "gate": {
      "step": "…",
      "field": "…",
      "pass": [
        "…",
        "…"
      ],
      "token": "ict_9wQ4rTz8kLmN3pXbV7hJ",
      "dailyMax": 1
    },
    "maxParallel": 1
  },
  "create": true
});

DELETE/workflows/{id}Delete a workflow

Removes the design. A run of it that is already going keeps going and stays readable and stoppable, because a run takes its own copy of the design when it starts.

What you send

Field	Type	Where
`id`requiredWhich workflow	string	address

What comes back

Field	Type
`ok`Always true	true

Try itanswered in this tab

curl

curl -X DELETE "$SANDBOX/workflows/a1b2c3d4" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.workflows.remove({
  "id": "a1b2c3d4"
});

POST/workflows/{id}/runStart a workflow

Kicks a workflow off and answers immediately with the run as recorded; the work carries on without you. Point it at a question and every step gets that on top of its own instructions. Every step is written down as waiting up front, so the picture is complete from the first frame. Several runs of one design can be in flight at once without colliding.

What you send

Field	Type	Where
`id`requiredWhich workflow	string	address
`request`What to point it at	string	body

What comes back

Field	Type
`runId`This run's id	string
`workflow`The design as it stood when…	object
`id`The workflow's id	string
`name`What to call it	string
`description`What it is for	string
`steps`The steps, each with what it…	object[]
`id`This step's own name, which other…	string
`title`What to call it on screen	string
`goal`What done means for this step,…	string
`prompt`What the step is told to…	string
`needs`Which steps must finish first	string[]
`handoff`How it meets what came before:…	"fresh" \| "continue"
`output`What it has to produce for…	object
`kind`It produces nothing but its work	"none"
`checks`What has to pass before it…	object[]
`kind`Run something and see if it…	"command"
`command`The command to run in the…	string
`context`How the step's own repeats meet…	"fresh" \| "continue"
`maxSpendUsd`A ceiling on what this step…	number
`agent`Which provider runs it	string
`harness`Which agentic loop runs it	"native" \| "claude-code"
`account`Which account pays for it	string
`model`Which model runs it	string
`actsAs`Which persona it acts as	string
`gate`Present means a machine can run…	object
`step`Which step's answer carries the decision	string
`field`Which of that step's declared answers…	string
`pass`Which values mean ship it	string[]
`token`The credential the calling pipeline presents	string
`dailyMax`How many runs a day, across…	integer
`maxParallel`How many steps may run at…	integer
`repos`The workspace as this run began,…	object[]
`repo`	string
`base`	string
`request`What this run was asked to…	string
`state`How the run is going	"running" \| "done" \| "failed" \| "stopped" … (6)
`startedAt`When it began, in milliseconds	number
`endedAt`When it ended, in milliseconds	number
`resumed`How many times the sandbox restarted…	integer
`detail`What went wrong, when something did	string
`steps`One entry per step, in the…	object[]
`stepId`Which step this is	string
`state`How it went	"pending" \| "running" \| "done" \| "failed" … (6)
`conversationId`The conversation it ran on, and…	string
`startedAt`When it began, in milliseconds	number
`endedAt`When it ended, in milliseconds	number
`iterations`How many rounds it took	integer
`costUsd`What it cost, in dollars	number
`loopState`How its repeating ended	"running" \| "done" \| "exhausted" \| "stalled" … (7)
`detail`What went wrong, when something did	string
`document`What it produced, once it has…	object
`done`Whether the goal is met	boolean
`reason`Why, in one line	string
`evidence`What was checked to know that	string
`data`The declared answer, for a loop…	object
`report`The start of its closing words	string
`reportPath`Where the whole answer is, as…	string
`archivedAt`When it was put away, in…	number

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/workflows/a1b2c3d4/run" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"request":"…"}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.workflows.run({
  "id": "a1b2c3d4",
  "request": "…"
});

GET/workflows/runsEvery workflow run

All runs across all workflows, newest first. This is also the only place the runs of a deleted workflow are still reachable.

What you send

Nothing. Call it as it is.

What comes back

Field	Type
`runs`Every run across every workflow, newest…	object[]
`runId`This run's id	string
`workflow`The design as it stood when…	object
`id`The workflow's id	string
`name`What to call it	string
`description`What it is for	string
`steps`The steps, each with what it…	object[]
`id`This step's own name, which other…	string
`title`What to call it on screen	string
`goal`What done means for this step,…	string
`prompt`What the step is told to…	string
`needs`Which steps must finish first	string[]
`handoff`How it meets what came before:…	"fresh" \| "continue"
`output`What it has to produce for…	object
`checks`What has to pass before it…	object[]
`context`How the step's own repeats meet…	"fresh" \| "continue"
`maxSpendUsd`A ceiling on what this step…	number
`agent`Which provider runs it	string
`harness`Which agentic loop runs it	"native" \| "claude-code"
`account`Which account pays for it	string
`model`Which model runs it	string
`actsAs`Which persona it acts as	string
`gate`Present means a machine can run…	object
`step`Which step's answer carries the decision	string
`field`Which of that step's declared answers…	string
`pass`Which values mean ship it	string[]
`token`The credential the calling pipeline presents	string
`dailyMax`How many runs a day, across…	integer
`maxParallel`How many steps may run at…	integer
`repos`The workspace as this run began,…	object[]
`repo`	string
`base`	string
`request`What this run was asked to…	string
`state`How the run is going	"running" \| "done" \| "failed" \| "stopped" … (6)
`startedAt`When it began, in milliseconds	number
`endedAt`When it ended, in milliseconds	number
`resumed`How many times the sandbox restarted…	integer
`detail`What went wrong, when something did	string
`steps`One entry per step, in the…	object[]
`stepId`Which step this is	string
`state`How it went	"pending" \| "running" \| "done" \| "failed" … (6)
`conversationId`The conversation it ran on, and…	string
`startedAt`When it began, in milliseconds	number
`endedAt`When it ended, in milliseconds	number
`iterations`How many rounds it took	integer
`costUsd`What it cost, in dollars	number
`loopState`How its repeating ended	"running" \| "done" \| "exhausted" \| "stalled" … (7)
`detail`What went wrong, when something did	string
`document`What it produced, once it has…	object
`done`Whether the goal is met	boolean
`reason`Why, in one line	string
`evidence`What was checked to know that	string
`data`The declared answer, for a loop…	object
`report`The start of its closing words	string
`reportPath`Where the whole answer is, as…	string
`archivedAt`When it was put away, in…	number

Try itanswered in this tab

curl

curl "$SANDBOX/workflows/runs" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.workflows.runs();

POST/workflows/runs/{runId}/stopStop a run now

Nothing further starts, and the steps already going are cut off where they stand. Whatever they had written stays on their branches. Deliberately abrupt rather than letting the current step finish: a step is a whole agent turn, and a stop that kept spending for minutes afterwards is indistinguishable from a button that does nothing. It always ends the run, including one left stranded by a daemon that was replaced mid-flight.

What you send

Field	Type	Where
`runId`requiredWhich run	string	address

What comes back

Field	Type
`ok`Always true	true

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/workflows/runs/run_8c2f41d9/stop" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.workflows.stopRun({
  "runId": "run_8c2f41d9"
});

POST/workflows/runs/{runId}/archiveTake a finished run off the board

Nothing is lost and the working copies are reclaimed. Every conversation the run started is put away with it, which is what makes this an archive rather than a dismissal: a step has no card of its own, so merely dropping the run would spill its conversations onto the board at the moment somebody said they were done. Refused while the run is still going.

What you send

Field	Type	Where
`runId`requiredWhich run	string	address

What comes back

Field	Type
`ok`Always true	true

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/workflows/runs/run_8c2f41d9/archive" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.workflows.archiveRun({
  "runId": "run_8c2f41d9"
});

POST/workflows/runs/{runId}/unarchiveBring an archived run back

Puts a run and every conversation it started back on the board.

What you send

Field	Type	Where
`runId`requiredWhich run	string	address

What comes back

Field	Type
`ok`Always true	true

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/workflows/runs/run_8c2f41d9/unarchive" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.workflows.unarchiveRun({
  "runId": "run_8c2f41d9"
});