Workflows | Fous API Reference

The WorkflowSummary object

idstringrequired
wf_ followed by 26 characters.
namestringrequired
descriptionstring
trigger_typestringrequired
manualschedulewebhook
enabledbooleanrequired
Whether its schedule or webhook fires. Every workflow can be run by hand, enabled or not.
step_countintegerrequired
Its steps, those inside loops too.
methodsarray of stringrequired
The slugs of the methods its steps run.
last_runobject or nullrequired
Show child attributesHide child attributes
- idstring
- statusstring
- created_atstring
- started_atstring or null
- finished_atstring or null
costobjectrequired
The price of one run, in credits: the credits field for the method, AI, transform, email and webhook steps outside a For each, and per_item more for each item a For each takes (the most an item costs: a For each inside it counts at its max items). It is the full run: only steps that run and succeed are charged, so a run a filter ends early, or whose steps fail, costs less. per_item is null without a For each.
Show child attributesHide child attributes
- creditsintegerrequired
- per_iteminteger or nullrequired
next_run_atstring or null
An enabled schedule: when it runs next.
created_atstring
updated_atstring

WorkflowSummary

{
  "id": "wf_01m72hccc2f47t2r9qry60m4cq",
  "name": "Import duty lookup",
  "description": "Looks up the US import duty for an HTS code and emails the rates.",
  "trigger_type": "manual",
  "enabled": false,
  "step_count": 3,
  "methods": [
    "hts.usitc.gov/get_import_duty"
  ],
  "cost": {
    "credits": 3,
    "per_item": null
  },
  "last_run": {
    "id": "wfr_01m72hcccgfzqsgbfn5w7q33sv",
    "status": "completed",
    "created_at": "2026-11-10T10:52:08.464Z",
    "started_at": "2026-11-10T10:52:08.465Z",
    "finished_at": "2026-11-10T10:52:15.650Z"
  },
  "next_run_at": null,
  "created_at": "2026-11-10T10:52:08.451Z",
  "updated_at": "2026-11-10T10:52:08.451Z"
}

The Workflow object

Every field of WorkflowSummary, and the fields below, which are new or read differently.

step_countinteger
Its steps, those inside loops too.
methodsarray of string
The slugs of the methods its steps run.
last_runobject or null
Show child attributesHide child attributes
- idstring
- statusstring
- created_atstring
- started_atstring or null
- finished_atstring or null
costobject
The price of one run, in credits: the credits field for the method, AI, transform, email and webhook steps outside a For each, and per_item more for each item a For each takes (the most an item costs: a For each inside it counts at its max items). It is the full run: only steps that run and succeed are charged, so a run a filter ends early, or whose steps fail, costs less. per_item is null without a For each.
Show child attributesHide child attributes
- creditsintegerrequired
- per_iteminteger or nullrequired
definitionobjectrequired
A trigger, then steps. Text in a method’s input, a loop’s over, an email and a webhook may hold templates: {{trigger.<key>}}, {{steps.<key>.<path>}}, {{loop.item}}, {{loop.index}}, {{run.id}}, {{run.started_at}}, {{now}}, {{previous.steps.<key>.<path>}} (the workflow’s last successful run; null on a first run), with filters ({{steps.search.data.results | length}}). A text that is exactly one template keeps the value’s type; a path that leads nowhere is null. A transform’s code reads the same data as data.trigger, data.steps.<key>, data.loop and data.previous.
Show child attributesHide child attributes
- triggerobjectrequired
  Show child attributesHide child attributes
  - typestringrequired
    Every workflow can also be run by hand with POST /v1/workflows/{id}/runs.
    manualschedulewebhook
  - inputsarray of object
    What a run takes, read as {{trigger.<key>}}.
    Show child attributesHide child attributes
    keystringrequired
    labelstring
    typestringrequired
    stringnumberboolean
    requiredboolean
    defaultstring or number or boolean or null
    descriptionstring
  - scheduleobject
    type schedule only.
    Show child attributesHide child attributes
    frequencystringrequired
    minutes: every N minutes; hourly: every N hours; daily, weekly and monthly: at at, every N days, weeks or months; weekdays: Monday to Friday at at.
    minuteshourlydailyweekdaysweeklymonthly
    everyinteger
    N. Not used by weekdays: leave it out or send 1.
    atstring
    HH:MM, daily, weekdays, weekly and monthly.
    dayinteger
    monthly: the day of the month, 1 to 31, or -1 for the last day (default 1). A day a month does not have (31 in April, 30 in February) is its last day.
    weekdayinteger
    weekly: 0 is Sunday.
    timezonestring
    An IANA time zone, like Europe/Prague. Default UTC.
    inputobject
    The input a scheduled run takes.
- stepsarray of objectrequired
  Any number of steps, loops nested as deep as needed; the definition is at most 200 KB.
  Show child attributesHide child attributes
  - keystring
    Unique in the whole workflow; what templates (steps.<key>) and code (data.steps.<key>) read the step’s output by. Left out, it is made from the name (List invoices: list_invoices).
  - namestring
    Plain words a person reads.
  - typestringrequired
    methodaitransformfilterloopdelayemailwebhook
  - methodstring or null
    method: the method’s slug; null while its method is pending.
  - pendingobject
    method: a method your organization does not have yet. The workflow cannot run or be turned on while a step is pending: accept building it with POST /v1/workflows/{id}/steps/{key}/build (status building, then the step runs the new method, its input and the later steps wired to it by AI). failed: reason says why the build did not make it; building again tries again.
    Show child attributesHide child attributes
    needstringrequired
    What the method does, in plain words.
    build_promptstringrequired
    What the builder is asked to make.
    sitestring or null
    The website to build on (a domain or sign-in host). Without one the step cannot be built (409 site_required) and is listed in incomplete; send site to POST /v1/workflows/{id}/steps/{key}/build.
    build_idstring or nullrequired
    Its build, once accepted.
    statusstringrequired
    proposedbuildingfailed
    reasonstring
    failed: why.
  - inputJSON value
    method: its input, an object; any value may be a template. A required input left empty makes the workflow incomplete until it is filled in. ai: more data its prompt is about, a template or an object of them, sent with the prompt; null (default): the prompt alone. Writing the data’s templates in the prompt itself does the same.
  - connectionstring or null
    method: the conn_ id to run with; null for the site’s default.
  - on_errorstring
    method: stop (default) fails the run; continue records the failure and goes on.
    stopcontinue
  - instructionstring
    transform: what the step does, in plain words. Change it and send the code as it was saved (or empty), and the code is written again from it when the workflow is saved; code you changed is kept.
  - codestring
    transform: the body of function (data, stop) that returns the step’s output (JSON). data is {trigger, steps: {<key>: output}, loop?: {item, index}, previous: the workflow’s last successful run before this one as {run_id, finished_at, trigger, steps: {<key>: output}}, or null on its first run, state: the step’s own memory across runs, an object ({} at first) that the next run starts from as this code leaves it once its run completes (top-level transforms; at most 256 KB; the ids already seen, for “only new items”)}; stop(reason) ends the run quietly, successful, like a filter (inside a loop: skips the rest of that item); prefer a filter step for conditions it can test. It runs in an isolated JavaScript sandbox: no network, files or modules, 2 seconds and 64 MB at most. Sent empty with an instruction, Fous writes it with AI when the workflow is saved; code you write is kept as written.
  - promptstring
    ai: what to write or decide, in plain words; templates read the data (a list, an object or a long text a template writes in is sent as the prompt’s data, so the prompt’s own words are never cut). A model answers on every run: it reads about 10,000 tokens (prompt and data; longer data is shortened, and the model is told) and writes up to about 800 words. Output: {text}, or with fields an object with each field’s text. A failed answer (the model declined, ran out of room, or did not answer) fails the step and costs nothing.
  - fieldsarray of string
    ai: answer these fields (short text each) instead of one text, read as {{steps.<key>.<field>}}. Default [].
  - conditionsarray of object
    filter: what must hold for the run to go on. value is a template; op one of exists, not_exists (empty: null, "", [] or {}), equals, not_equals, contains, not_contains (text in any case; a list by its items), gt, gte, lt, lte (numbers, a numeric text too; a list by its length); compare is text or a template, for the operators that compare. When the filter does not pass, its record is filtered with output {passed: false, message: "Stopped: …", skipped: the action steps it skipped}.
    Show child attributesHide child attributes
    valuestringrequired
    opstringrequired
    existsnot_existsequalsnot_equalscontainsnot_containsgtgteltlte
    comparestring
  - matchstring
    filter: all (default) of its conditions, or any one.
    allany
  - overstring
    loop: a template that gives a list (a text is split at commas and new lines).
  - maxinteger
    loop: at most this many items (the rest are left out): any number, each item’s action steps costing credits. Left out: 10, and 5 on Free.
  - stepsarray of object
    loop: its steps.
    Show child attributesHide child attributes
    keystring
    Unique in the whole workflow; what templates (steps.<key>) and code (data.steps.<key>) read the step’s output by. Left out, it is made from the name (List invoices: list_invoices).
    namestring
    Plain words a person reads.
    typestringrequired
    methodaitransformfilterloopdelayemailwebhook
    methodstring or null
    method: the method’s slug; null while its method is pending.
    pendingobject
    method: a method your organization does not have yet. The workflow cannot run or be turned on while a step is pending: accept building it with POST /v1/workflows/{id}/steps/{key}/build (status building, then the step runs the new method, its input and the later steps wired to it by AI). failed: reason says why the build did not make it; building again tries again.
    inputJSON value
    method: its input, an object; any value may be a template. A required input left empty makes the workflow incomplete until it is filled in. ai: more data its prompt is about, a template or an object of them, sent with the prompt; null (default): the prompt alone. Writing the data’s templates in the prompt itself does the same.
    connectionstring or null
    method: the conn_ id to run with; null for the site’s default.
    on_errorstring
    method: stop (default) fails the run; continue records the failure and goes on.
    stopcontinue
    instructionstring
    transform: what the step does, in plain words. Change it and send the code as it was saved (or empty), and the code is written again from it when the workflow is saved; code you changed is kept.
    codestring
    transform: the body of function (data, stop) that returns the step’s output (JSON). data is {trigger, steps: {<key>: output}, loop?: {item, index}, previous: the workflow’s last successful run before this one as {run_id, finished_at, trigger, steps: {<key>: output}}, or null on its first run, state: the step’s own memory across runs, an object ({} at first) that the next run starts from as this code leaves it once its run completes (top-level transforms; at most 256 KB; the ids already seen, for “only new items”)}; stop(reason) ends the run quietly, successful, like a filter (inside a loop: skips the rest of that item); prefer a filter step for conditions it can test. It runs in an isolated JavaScript sandbox: no network, files or modules, 2 seconds and 64 MB at most. Sent empty with an instruction, Fous writes it with AI when the workflow is saved; code you write is kept as written.
    promptstring
    ai: what to write or decide, in plain words; templates read the data (a list, an object or a long text a template writes in is sent as the prompt’s data, so the prompt’s own words are never cut). A model answers on every run: it reads about 10,000 tokens (prompt and data; longer data is shortened, and the model is told) and writes up to about 800 words. Output: {text}, or with fields an object with each field’s text. A failed answer (the model declined, ran out of room, or did not answer) fails the step and costs nothing.
    fieldsarray of string
    ai: answer these fields (short text each) instead of one text, read as {{steps.<key>.<field>}}. Default [].
    conditionsarray of object
    filter: what must hold for the run to go on. value is a template; op one of exists, not_exists (empty: null, "", [] or {}), equals, not_equals, contains, not_contains (text in any case; a list by its items), gt, gte, lt, lte (numbers, a numeric text too; a list by its length); compare is text or a template, for the operators that compare. When the filter does not pass, its record is filtered with output {passed: false, message: "Stopped: …", skipped: the action steps it skipped}.
    matchstring
    filter: all (default) of its conditions, or any one.
    allany
    overstring
    loop: a template that gives a list (a text is split at commas and new lines).
    maxinteger
    loop: at most this many items (the rest are left out): any number, each item’s action steps costing credits. Left out: 10, and 5 on Free.
    stepsarray of object
    loop: its steps.
    secondsinteger
    delay.
    tostring
    email: addresses separated by commas; empty: the workflow is saved incomplete until it is filled in. On Free, Starter and Pro, only people in your organization (their sign-in addresses); on Business and Enterprise, anyone. It comes from "<workflow name> via Fous" <workflows@fous.com>, and replies go to the person who made the workflow.
    subjectstring
    email.
    bodyJSON value
    email: the plain-text body (line breaks kept). webhook: the JSON to send, a template or an object of them; left out, the previous step’s output.
    urlstring
    webhook: a public https address; empty: the workflow is saved incomplete until it is filled in. Each POST carries X-Fous-Workflow, X-Fous-Run, X-Fous-Signature (t=<unix seconds>,v1=<HMAC-SHA256 in hex of "<t>.<body>" with the workflow’s signing_secret>) and an Idempotency-Key that is the same on every attempt of the step (receivers dedupe on it: Fous retries on 5xx, 408, 429 and connection failures, and a run taken up again sends what it recorded under it; one that got no answer in time is not sent again), plus the step’s headers.
    headersarray of object
    webhook: headers sent with each POST, for a receiver that needs a key or a token (Authorization, X-API-Key). Their values are write-only secrets: sent as value to set one (empty text clears it), left out to keep the saved one; answers and run records never hold them, only a masked hint (null: no value yet, and the workflow is incomplete until it has one). Not Host, Content-Type, Content-Length, Idempotency-Key, Connection, Transfer-Encoding or X-Fous-*.
  - secondsinteger
    delay.
  - tostring
    email: addresses separated by commas; empty: the workflow is saved incomplete until it is filled in. On Free, Starter and Pro, only people in your organization (their sign-in addresses); on Business and Enterprise, anyone. It comes from "<workflow name> via Fous" <workflows@fous.com>, and replies go to the person who made the workflow.
  - subjectstring
    email.
  - bodyJSON value
    email: the plain-text body (line breaks kept). webhook: the JSON to send, a template or an object of them; left out, the previous step’s output.
  - urlstring
    webhook: a public https address; empty: the workflow is saved incomplete until it is filled in. Each POST carries X-Fous-Workflow, X-Fous-Run, X-Fous-Signature (t=<unix seconds>,v1=<HMAC-SHA256 in hex of "<t>.<body>" with the workflow’s signing_secret>) and an Idempotency-Key that is the same on every attempt of the step (receivers dedupe on it: Fous retries on 5xx, 408, 429 and connection failures, and a run taken up again sends what it recorded under it; one that got no answer in time is not sent again), plus the step’s headers.
  - headersarray of object
    webhook: headers sent with each POST, for a receiver that needs a key or a token (Authorization, X-API-Key). Their values are write-only secrets: sent as value to set one (empty text clears it), left out to keep the saved one; answers and run records never hold them, only a masked hint (null: no value yet, and the workflow is incomplete until it has one). Not Host, Content-Type, Content-Length, Idempotency-Key, Connection, Transfer-Encoding or X-Fous-*.
    Show child attributesHide child attributes
    namestringrequired
    valuestring
    Sent only: the value to save.
    hintstring or null
    The saved value masked (its last 4 characters when long), or null.
incompletearray of object
Values the workflow still needs before it can run or be turned on: an empty webhook address (field url), an email with no one to send it to (to), a method’s required input left empty (input.<name>). A workflow is saved with them empty.
Show child attributesHide child attributes
- keystringrequired
  The step.
- fieldstringrequired
- messagestringrequired
  What to do, in plain words.
webhook_urlstring or nullrequired
A webhook workflow: where a POST starts a run. The address is the secret; renew it with POST /v1/workflows/{id}/webhook.
signing_secretstring or null
A workflow with webhook steps: what they sign their calls with (X-Fous-Signature), so the address can check the call is from Fous. New one with POST /v1/workflows/{id}/signing-secret.

Workflow

{
  "id": "wf_01m72hccc2f47t2r9qry60m4cq",
  "name": "Import duty lookup",
  "description": "Looks up the US import duty for an HTS code and emails the rates.",
  "trigger_type": "manual",
  "enabled": false,
  "step_count": 3,
  "methods": [
    "hts.usitc.gov/get_import_duty"
  ],
  "cost": {
    "credits": 3,
    "per_item": null
  },
  "last_run": {
    "id": "wfr_01m72hcccgfzqsgbfn5w7q33sv",
    "status": "completed",
    "created_at": "2026-11-10T10:52:08.464Z",
    "started_at": "2026-11-10T10:52:08.465Z",
    "finished_at": "2026-11-10T10:52:15.650Z"
  },
  "next_run_at": null,
  "created_at": "2026-11-10T10:52:08.451Z",
  "updated_at": "2026-11-10T10:52:08.451Z",
  "definition": {
    "trigger": {
      "type": "manual",
      "inputs": [
        {
          "key": "hts_code",
          "label": "HTS code",
          "type": "string",
          "required": true,
          "default": "6109.10.0012",
          "description": ""
        }
      ]
    },
    "steps": [
      {
        "key": "duty",
        "name": "Look up the import duty",
        "type": "method",
        "method": "hts.usitc.gov/get_import_duty",
        "input": {
          "hts_code": "{{trigger.hts_code}}"
        },
        "connection": null,
        "on_error": "stop"
      },
      {
        "key": "note",
        "name": "Write the rates as a note",
        "type": "transform",
        "instruction": "Write the general, special and column 2 rates as a short plain-text note; stop when the code has no rate.",
        "code": "const duty = data.steps.duty.data;\nif (!duty || !duty.general_rate) stop('This code has no rate.');\nreturn [\n  `HTS ${duty.hts_code} (${duty.release})`,\n  `General rate: ${duty.general_rate}`,\n  `Special rates: ${duty.special_rates || 'none'}`,\n  `Column 2 rate: ${duty.column_2_rate}`,\n  duty.source_url,\n].join('\\n');"
      },
      {
        "key": "send",
        "name": "Email the note",
        "type": "email",
        "to": "ada@example.com",
        "subject": "Import duty for {{trigger.hts_code}}",
        "body": "{{steps.note}}"
      }
    ]
  },
  "webhook_url": null,
  "signing_secret": null,
  "incomplete": []
}

The WorkflowRun object

idstringrequired
wfr_ followed by 26 characters.
workflow_idstringrequired
statusstringrequired
waiting: until resume_at, on a delay, to try a step again, for a method’s repair, or (a scheduled run) for someone to sign an account in again (the step’s waiting says which). A run a filter (or stop()) ended early completed: that step is recorded filtered, saying why. skipped: its schedule came due while the last run had not finished; error says which (code previous_run_open, run_id). canceled: by a person, or the workflow was turned off (its schedule’s and webhook’s runs that had not started, or were waiting to retry a step or for a repair).
queuedrunningwaitingcompletedfailedcanceledskipped
triggerstringrequired
manualschedulewebhookapi
inputobject
What it was given, checked against the trigger’s inputs.
errorobject or null
A failed run: the failed step’s error, with step and path.
creditsintegerrequired
What the run cost, in credits: 1 for each method, AI, transform, email and webhook step that ran and completed (those in a For each once per item). Steps a filter skipped, failed attempts and failed steps cost nothing. A step the organization cannot pay for fails with error.code insufficient_credits, and the run stops there.
created_atstring
started_atstring or null
finished_atstring or null
resume_atstring or null
outputJSON value
With steps, once the run completed: what the last step that did something gave (a method’s data, any other step’s output). Null before it completed.
stepsarray of object
Each step as it ran, in the order it started.
Show child attributesHide child attributes
- seqintegerrequired
- keystringrequired
- pathstringrequired
  Where it ran: "send" at the top, "loop.send[2]" in a loop’s third item.
- typestringrequired
  methodaitransformfilterloopdelayemailwebhook
- namestring
- statusstringrequired
  waiting: to be tried again, for its method’s repair, or for someone to sign its account in again (waiting says which and until when). filtered: a filter that did not pass, or a transform that called stop(); what came after it in its block did not run.
  runningwaitingcompletedfailedfiltered
- inputJSON value
  What it was given, its templates resolved (dropped with the run’s data when it expires: 24 hours or the plan’s run history; the workflow’s latest completed run keeps it). ai: {prompt (as sent, up to 20,000 characters), shortened?: true when long texts or lists in its data were shortened to fit, left_out?: items of its data not shown (the model is told how many)}; filter: {conditions} with the values compared.
- attemptsarray of object
  Its failed attempts, in order: {attempt, at, error: {code, message}, run_id? (a method step’s run)}.
- waitingobject or null
  While it waits (status waiting): reason retry (until: the next try; attempt and of: "attempt 2 of 5"), repair (until: the next look; method; repair_until: when its repair is due, null when not known yet) or connection (a scheduled run whose account needs signing in: it goes on as soon as someone signs in; until: the next look, a day at most; site, connection_id and connect_url say where); since: when it began waiting; message, in plain words.
- outputJSON value
  method: {status, data, run_id, error}; ai: {text}, or its fields; transform: what its code returned ({stopped: true, message: "Stopped: …", skipped} when it called stop()); filter: {passed: true}, or {passed: false, message: "Stopped: …", skipped: how many action steps it skipped, which cost nothing}; loop: {count, items: [{status: done or filtered}]} (each item’s outputs are its steps’ records); delay: {seconds}; email: {sent}; webhook: {status, body} (body up to 64 KB).
- errorobject or null
- method_run_idstring or null
  method: its run, also in GET /v1/runs.
- started_atstring or null
- finished_atstring or null

WorkflowRun

{
  "id": "wfr_01m72hcccgfzqsgbfn5w7q33sv",
  "workflow_id": "wf_01m72hccc2f47t2r9qry60m4cq",
  "status": "completed",
  "trigger": "manual",
  "input": {
    "hts_code": "6109.10.0012"
  },
  "error": null,
  "credits": 3,
  "created_at": "2026-11-10T10:52:08.464Z",
  "started_at": "2026-11-10T10:52:08.465Z",
  "finished_at": "2026-11-10T10:52:15.650Z",
  "resume_at": null
}

List workflows

Your organization’s workflows, the latest change first, each with its trigger, the methods its steps run and its last run. Free.

Returns

200The workflows.

The answer has these fields:

workflowsarray of WorkflowSummaryrequired

curl 'https://api.fous.com/v1/workflows' \
  -H "Authorization: Bearer $FOUS_API_KEY"

// Save as fous.mts, then run: npx tsx fous.mts
const response = await fetch('https://api.fous.com/v1/workflows', {
  headers: {
    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,
  },
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

import os
import requests

response = requests.get(
    "https://api.fous.com/v1/workflows",
    headers={
        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",
    },
    timeout=180,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

Sent with your key, kept for this tab only. Get an API key.

Response 200

{
  "workflows": [
    {
      "id": "wf_01m72hccc2f47t2r9qry60m4cq",
      "name": "Import duty lookup",
      "description": "Looks up the US import duty for an HTS code and emails the rates.",
      "trigger_type": "manual",
      "enabled": false,
      "step_count": 3,
      "methods": [
        "hts.usitc.gov/get_import_duty"
      ],
      "cost": {
        "credits": 3,
        "per_item": null
      },
      "last_run": {
        "id": "wfr_01m72hcccgfzqsgbfn5w7q33sv",
        "status": "completed",
        "created_at": "2026-11-10T10:52:08.464Z",
        "started_at": "2026-11-10T10:52:08.465Z",
        "finished_at": "2026-11-10T10:52:15.650Z"
      },
      "next_run_at": null,
      "created_at": "2026-11-10T10:52:08.451Z",
      "updated_at": "2026-11-10T10:52:08.451Z"
    }
  ]
}

Saves a workflow, from a prompt or from a definition. With {prompt}, AI reads your methods (their inputs and outputs), picks the ones the request needs, wires their inputs, writes the code of its transforms and saves the workflow turned off; ai.summary says what it built. What the request needs that none of your methods can do becomes a pending method step (method null, pending {need, build_prompt}) and is listed in ai.missing: accept building it with POST /v1/workflows/{id}/steps/{key}/build. A value the AI cannot know (a webhook address, an email address, an ID of your own) is left empty and listed in incomplete; the AI builds with sensible defaults rather than asking, and its summary says what is left to fill in. A prompt that asks for no automation ("hi", "what can you do?") saves nothing: the answer is 200 {workflow: null, ai} with ai.reply. When a step needs a website or account the AI cannot know ("our supplier portal", "our bank"), it asks instead: 200 {workflow: null, ai} with ai.question; send the conversation again as messages with the person's answer last. timezone (optional) is the person's, for times like "9am". With {name, definition}, the definition is checked against your methods: every problem answers at once in errors, each at its place (steps[2].input.query); a transform with an instruction and empty code gets its code written. Each method step is an ordinary run. A run costs 1 credit for each step that runs (methods, AI, transforms, emails and webhooks; steps inside For each once per item). The number shown before you run (cost) is the full run; a run a filter ends early costs less. Triggers, For each, filters and delays are free; failed steps cost nothing. A step whose failure can pass (the site or Fous failing for a moment, a rate limit) is tried again after 20 s, 2 min, 10 min and 30 min, 5 attempts in all; a method step whose method Fous is repairing waits for the repair. enabled (default false) turns on a schedule or a webhook, which need a paid plan. With Accept: text/event-stream the answer is Server-Sent Events while the AI writes, each event: <name> with data: <JSON>: status {text} (a short phase line); reply {text} (the next piece of a reply: append the pieces); question {text, options: [{label, value}], placeholder, allow_other} (the reply asks the person to choose, such as which site; show it as a card, and send the choice as the next message); workflow {name, description}, trigger {trigger} and step {index, step} (emitted as each top-level step is completed, in order; loops are emitted with all nested steps included; keys may still be missing) while it builds or changes the workflow; reset {} (the initial draft failed validation and the AI is restarting: discard earlier streamed events); then done with the same body the JSON answer has (the workflow and ai), or error with the error object. The stream’s HTTP status is 200 like the JSON answer’s.

Request body

Required, JSON. One of:

From a prompt

promptstringOptional
messagesarray of objectOptional
Show child attributesHide child attributes
- rolestringrequired
  userassistant
- textstringrequired
timezonestringOptional
An IANA time zone, like Europe/Prague. Default UTC.

From a definition

namestringrequired
descriptionstringOptional
definitionobjectrequired
A trigger, then steps. Text in a method’s input, a loop’s over, an email and a webhook may hold templates: {{trigger.<key>}}, {{steps.<key>.<path>}}, {{loop.item}}, {{loop.index}}, {{run.id}}, {{run.started_at}}, {{now}}, {{previous.steps.<key>.<path>}} (the workflow’s last successful run; null on a first run), with filters ({{steps.search.data.results | length}}). A text that is exactly one template keeps the value’s type; a path that leads nowhere is null. A transform’s code reads the same data as data.trigger, data.steps.<key>, data.loop and data.previous.
Show child attributesHide child attributes
- triggerobjectrequired
  Show child attributesHide child attributes
  - typestringrequired
    Every workflow can also be run by hand with POST /v1/workflows/{id}/runs.
    manualschedulewebhook
  - inputsarray of object
    What a run takes, read as {{trigger.<key>}}.
    Show child attributesHide child attributes
    keystringrequired
    labelstring
    typestringrequired
    stringnumberboolean
    requiredboolean
    defaultstring or number or boolean or null
    descriptionstring
  - scheduleobject
    type schedule only.
    Show child attributesHide child attributes
    frequencystringrequired
    minutes: every N minutes; hourly: every N hours; daily, weekly and monthly: at at, every N days, weeks or months; weekdays: Monday to Friday at at.
    minuteshourlydailyweekdaysweeklymonthly
    everyinteger
    N. Not used by weekdays: leave it out or send 1.
    atstring
    HH:MM, daily, weekdays, weekly and monthly.
    dayinteger
    monthly: the day of the month, 1 to 31, or -1 for the last day (default 1). A day a month does not have (31 in April, 30 in February) is its last day.
    weekdayinteger
    weekly: 0 is Sunday.
    timezonestring
    An IANA time zone, like Europe/Prague. Default UTC.
    inputobject
    The input a scheduled run takes.
- stepsarray of objectrequired
  Any number of steps, loops nested as deep as needed; the definition is at most 200 KB.
  Show child attributesHide child attributes
  - keystring
    Unique in the whole workflow; what templates (steps.<key>) and code (data.steps.<key>) read the step’s output by. Left out, it is made from the name (List invoices: list_invoices).
  - namestring
    Plain words a person reads.
  - typestringrequired
    methodaitransformfilterloopdelayemailwebhook
  - methodstring or null
    method: the method’s slug; null while its method is pending.
  - pendingobject
    method: a method your organization does not have yet. The workflow cannot run or be turned on while a step is pending: accept building it with POST /v1/workflows/{id}/steps/{key}/build (status building, then the step runs the new method, its input and the later steps wired to it by AI). failed: reason says why the build did not make it; building again tries again.
    Show child attributesHide child attributes
    needstringrequired
    What the method does, in plain words.
    build_promptstringrequired
    What the builder is asked to make.
    sitestring or null
    The website to build on (a domain or sign-in host). Without one the step cannot be built (409 site_required) and is listed in incomplete; send site to POST /v1/workflows/{id}/steps/{key}/build.
    build_idstring or nullrequired
    Its build, once accepted.
    statusstringrequired
    proposedbuildingfailed
    reasonstring
    failed: why.
  - inputJSON value
    method: its input, an object; any value may be a template. A required input left empty makes the workflow incomplete until it is filled in. ai: more data its prompt is about, a template or an object of them, sent with the prompt; null (default): the prompt alone. Writing the data’s templates in the prompt itself does the same.
  - connectionstring or null
    method: the conn_ id to run with; null for the site’s default.
  - on_errorstring
    method: stop (default) fails the run; continue records the failure and goes on.
    stopcontinue
  - instructionstring
    transform: what the step does, in plain words. Change it and send the code as it was saved (or empty), and the code is written again from it when the workflow is saved; code you changed is kept.
  - codestring
    transform: the body of function (data, stop) that returns the step’s output (JSON). data is {trigger, steps: {<key>: output}, loop?: {item, index}, previous: the workflow’s last successful run before this one as {run_id, finished_at, trigger, steps: {<key>: output}}, or null on its first run, state: the step’s own memory across runs, an object ({} at first) that the next run starts from as this code leaves it once its run completes (top-level transforms; at most 256 KB; the ids already seen, for “only new items”)}; stop(reason) ends the run quietly, successful, like a filter (inside a loop: skips the rest of that item); prefer a filter step for conditions it can test. It runs in an isolated JavaScript sandbox: no network, files or modules, 2 seconds and 64 MB at most. Sent empty with an instruction, Fous writes it with AI when the workflow is saved; code you write is kept as written.
  - promptstring
    ai: what to write or decide, in plain words; templates read the data (a list, an object or a long text a template writes in is sent as the prompt’s data, so the prompt’s own words are never cut). A model answers on every run: it reads about 10,000 tokens (prompt and data; longer data is shortened, and the model is told) and writes up to about 800 words. Output: {text}, or with fields an object with each field’s text. A failed answer (the model declined, ran out of room, or did not answer) fails the step and costs nothing.
  - fieldsarray of string
    ai: answer these fields (short text each) instead of one text, read as {{steps.<key>.<field>}}. Default [].
  - conditionsarray of object
    filter: what must hold for the run to go on. value is a template; op one of exists, not_exists (empty: null, "", [] or {}), equals, not_equals, contains, not_contains (text in any case; a list by its items), gt, gte, lt, lte (numbers, a numeric text too; a list by its length); compare is text or a template, for the operators that compare. When the filter does not pass, its record is filtered with output {passed: false, message: "Stopped: …", skipped: the action steps it skipped}.
    Show child attributesHide child attributes
    valuestringrequired
    opstringrequired
    existsnot_existsequalsnot_equalscontainsnot_containsgtgteltlte
    comparestring
  - matchstring
    filter: all (default) of its conditions, or any one.
    allany
  - overstring
    loop: a template that gives a list (a text is split at commas and new lines).
  - maxinteger
    loop: at most this many items (the rest are left out): any number, each item’s action steps costing credits. Left out: 10, and 5 on Free.
  - stepsarray of object
    loop: its steps.
    Show child attributesHide child attributes
    keystring
    Unique in the whole workflow; what templates (steps.<key>) and code (data.steps.<key>) read the step’s output by. Left out, it is made from the name (List invoices: list_invoices).
    namestring
    Plain words a person reads.
    typestringrequired
    methodaitransformfilterloopdelayemailwebhook
    methodstring or null
    method: the method’s slug; null while its method is pending.
    pendingobject
    method: a method your organization does not have yet. The workflow cannot run or be turned on while a step is pending: accept building it with POST /v1/workflows/{id}/steps/{key}/build (status building, then the step runs the new method, its input and the later steps wired to it by AI). failed: reason says why the build did not make it; building again tries again.
    inputJSON value
    method: its input, an object; any value may be a template. A required input left empty makes the workflow incomplete until it is filled in. ai: more data its prompt is about, a template or an object of them, sent with the prompt; null (default): the prompt alone. Writing the data’s templates in the prompt itself does the same.
    connectionstring or null
    method: the conn_ id to run with; null for the site’s default.
    on_errorstring
    method: stop (default) fails the run; continue records the failure and goes on.
    stopcontinue
    instructionstring
    transform: what the step does, in plain words. Change it and send the code as it was saved (or empty), and the code is written again from it when the workflow is saved; code you changed is kept.
    codestring
    transform: the body of function (data, stop) that returns the step’s output (JSON). data is {trigger, steps: {<key>: output}, loop?: {item, index}, previous: the workflow’s last successful run before this one as {run_id, finished_at, trigger, steps: {<key>: output}}, or null on its first run, state: the step’s own memory across runs, an object ({} at first) that the next run starts from as this code leaves it once its run completes (top-level transforms; at most 256 KB; the ids already seen, for “only new items”)}; stop(reason) ends the run quietly, successful, like a filter (inside a loop: skips the rest of that item); prefer a filter step for conditions it can test. It runs in an isolated JavaScript sandbox: no network, files or modules, 2 seconds and 64 MB at most. Sent empty with an instruction, Fous writes it with AI when the workflow is saved; code you write is kept as written.
    promptstring
    ai: what to write or decide, in plain words; templates read the data (a list, an object or a long text a template writes in is sent as the prompt’s data, so the prompt’s own words are never cut). A model answers on every run: it reads about 10,000 tokens (prompt and data; longer data is shortened, and the model is told) and writes up to about 800 words. Output: {text}, or with fields an object with each field’s text. A failed answer (the model declined, ran out of room, or did not answer) fails the step and costs nothing.
    fieldsarray of string
    ai: answer these fields (short text each) instead of one text, read as {{steps.<key>.<field>}}. Default [].
    conditionsarray of object
    filter: what must hold for the run to go on. value is a template; op one of exists, not_exists (empty: null, "", [] or {}), equals, not_equals, contains, not_contains (text in any case; a list by its items), gt, gte, lt, lte (numbers, a numeric text too; a list by its length); compare is text or a template, for the operators that compare. When the filter does not pass, its record is filtered with output {passed: false, message: "Stopped: …", skipped: the action steps it skipped}.
    matchstring
    filter: all (default) of its conditions, or any one.
    allany
    overstring
    loop: a template that gives a list (a text is split at commas and new lines).
    maxinteger
    loop: at most this many items (the rest are left out): any number, each item’s action steps costing credits. Left out: 10, and 5 on Free.
    stepsarray of object
    loop: its steps.
    secondsinteger
    delay.
    tostring
    email: addresses separated by commas; empty: the workflow is saved incomplete until it is filled in. On Free, Starter and Pro, only people in your organization (their sign-in addresses); on Business and Enterprise, anyone. It comes from "<workflow name> via Fous" <workflows@fous.com>, and replies go to the person who made the workflow.
    subjectstring
    email.
    bodyJSON value
    email: the plain-text body (line breaks kept). webhook: the JSON to send, a template or an object of them; left out, the previous step’s output.
    urlstring
    webhook: a public https address; empty: the workflow is saved incomplete until it is filled in. Each POST carries X-Fous-Workflow, X-Fous-Run, X-Fous-Signature (t=<unix seconds>,v1=<HMAC-SHA256 in hex of "<t>.<body>" with the workflow’s signing_secret>) and an Idempotency-Key that is the same on every attempt of the step (receivers dedupe on it: Fous retries on 5xx, 408, 429 and connection failures, and a run taken up again sends what it recorded under it; one that got no answer in time is not sent again), plus the step’s headers.
    headersarray of object
    webhook: headers sent with each POST, for a receiver that needs a key or a token (Authorization, X-API-Key). Their values are write-only secrets: sent as value to set one (empty text clears it), left out to keep the saved one; answers and run records never hold them, only a masked hint (null: no value yet, and the workflow is incomplete until it has one). Not Host, Content-Type, Content-Length, Idempotency-Key, Connection, Transfer-Encoding or X-Fous-*.
  - secondsinteger
    delay.
  - tostring
    email: addresses separated by commas; empty: the workflow is saved incomplete until it is filled in. On Free, Starter and Pro, only people in your organization (their sign-in addresses); on Business and Enterprise, anyone. It comes from "<workflow name> via Fous" <workflows@fous.com>, and replies go to the person who made the workflow.
  - subjectstring
    email.
  - bodyJSON value
    email: the plain-text body (line breaks kept). webhook: the JSON to send, a template or an object of them; left out, the previous step’s output.
  - urlstring
    webhook: a public https address; empty: the workflow is saved incomplete until it is filled in. Each POST carries X-Fous-Workflow, X-Fous-Run, X-Fous-Signature (t=<unix seconds>,v1=<HMAC-SHA256 in hex of "<t>.<body>" with the workflow’s signing_secret>) and an Idempotency-Key that is the same on every attempt of the step (receivers dedupe on it: Fous retries on 5xx, 408, 429 and connection failures, and a run taken up again sends what it recorded under it; one that got no answer in time is not sent again), plus the step’s headers.
  - headersarray of object
    webhook: headers sent with each POST, for a receiver that needs a key or a token (Authorization, X-API-Key). Their values are write-only secrets: sent as value to set one (empty text clears it), left out to keep the saved one; answers and run records never hold them, only a masked hint (null: no value yet, and the workflow is incomplete until it has one). Not Host, Content-Type, Content-Length, Idempotency-Key, Connection, Transfer-Encoding or X-Fous-*.
    Show child attributesHide child attributes
    namestringrequired
    valuestring
    Sent only: the value to save.
    hintstring or null
    The saved value masked (its last 4 characters when long), or null.
enabledbooleandefault falseOptional
Whether its schedule or webhook fires.

Returns

200From a prompt, JSON or the event stream: the saved workflow with ai (it is saved turned off), or {workflow: null, ai} when it asks for no automation or the AI asks back; nothing was saved then.
201Saved from a definition.

Errors

Status	Code	When
400	`invalid_request`	The definition (or the body) does not hold: errors lists each problem at its place
402	`insufficient_credits`	No credits left, and no extra credits on (or capped, or failing to charge); nothing starts
403	`plan_limit`	Schedules and webhooks come with a paid plan (limit.kind api); from a prompt, also the plan’s AI messages used (limit.kind chat_messages)
409	`conflict`	reason workflow_incomplete: a value is still to fill in (incomplete) or a step’s method still to build (steps), so the workflow cannot run or be turned on
422	`invalid_input`	reason ai_failed: the AI’s draft did not hold twice
429	`rate_limited`	Too many AI messages this minute (limit.kind chat_per_minute)
503	`service_unavailable`	The AI is unavailable: nothing was saved or changed

From a prompt

curl 'https://api.fous.com/v1/workflows' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Accept: text/event-stream' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "Look up the US import duty for an HTS code I enter on hts.usitc.gov and email me the rates"
  }'

// Save as fous.mts, then run: npx tsx fous.mts
const response = await fetch('https://api.fous.com/v1/workflows', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,
    Accept: 'text/event-stream',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: 'Look up the US import duty for an HTS code I enter on hts.usitc.gov and email me the rates'
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

import os
import requests

response = requests.post(
    "https://api.fous.com/v1/workflows",
    headers={
        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",
        "Accept": "text/event-stream",
    },
    json={
        "prompt": "Look up the US import duty for an HTS code I enter on hts.usitc.gov and email me the rates"
    },
    timeout=180,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

Sent with your key, kept for this tab only. Get an API key.

From a definition

curl 'https://api.fous.com/v1/workflows' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Accept: text/event-stream' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Import duty lookup",
    "definition": {
      "trigger": {
        "type": "manual",
        "inputs": [
          {
            "key": "hts_code",
            "label": "HTS code",
            "type": "string",
            "required": true,
            "default": "6109.10.0012",
            "description": ""
          }
        ]
      },
      "steps": [
        {
          "key": "duty",
          "name": "Look up the import duty",
          "type": "method",
          "method": "hts.usitc.gov/get_import_duty",
          "input": {
            "hts_code": "{{trigger.hts_code}}"
          },
          "connection": null,
          "on_error": "stop"
        },
        {
          "key": "note",
          "name": "Write the rates as a note",
          "type": "transform",
          "instruction": "Write the general, special and column 2 rates as a short plain-text note; stop when the code has no rate.",
          "code": "const duty = data.steps.duty.data;\nif (!duty || !duty.general_rate) stop('\''This code has no rate.'\'');\nreturn [\n  `HTS ${duty.hts_code} (${duty.release})`,\n  `General rate: ${duty.general_rate}`,\n  `Special rates: ${duty.special_rates || '\''none'\''}`,\n  `Column 2 rate: ${duty.column_2_rate}`,\n  duty.source_url,\n].join('\''\\n'\'');"
        },
        {
          "key": "send",
          "name": "Email the note",
          "type": "email",
          "to": "ada@example.com",
          "subject": "Import duty for {{trigger.hts_code}}",
          "body": "{{steps.note}}"
        }
      ]
    }
  }'

// Save as fous.mts, then run: npx tsx fous.mts
const response = await fetch('https://api.fous.com/v1/workflows', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,
    Accept: 'text/event-stream',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Import duty lookup',
    definition: {
      trigger: {
        type: 'manual',
        inputs: [
          {
            key: 'hts_code',
            label: 'HTS code',
            type: 'string',
            required: true,
            default: '6109.10.0012',
            description: ''
          }
        ]
      },
      steps: [
        {
          key: 'duty',
          name: 'Look up the import duty',
          type: 'method',
          method: 'hts.usitc.gov/get_import_duty',
          input: {
            hts_code: '{{trigger.hts_code}}'
          },
          connection: null,
          on_error: 'stop'
        },
        {
          key: 'note',
          name: 'Write the rates as a note',
          type: 'transform',
          instruction: 'Write the general, special and column 2 rates as a short plain-text note; stop when the code has no rate.',
          code: "const duty = data.steps.duty.data;\nif (!duty || !duty.general_rate) stop('This code has no rate.');\nreturn [\n  `HTS ${duty.hts_code} (${duty.release})`,\n  `General rate: ${duty.general_rate}`,\n  `Special rates: ${duty.special_rates || 'none'}`,\n  `Column 2 rate: ${duty.column_2_rate}`,\n  duty.source_url,\n].join('\\n');'
        },
        {
          key: 'send',
          name: 'Email the note',
          type: 'email',
          to: 'ada@example.com',
          subject: 'Import duty for {{trigger.hts_code}}',
          body: '{{steps.note}}"
        }
      ]
    }
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

import os
import requests

response = requests.post(
    "https://api.fous.com/v1/workflows",
    headers={
        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",
        "Accept": "text/event-stream",
    },
    json={
        "name": "Import duty lookup",
        "definition": {
            "trigger": {
                "type": "manual",
                "inputs": [
                    {
                        "key": "hts_code",
                        "label": "HTS code",
                        "type": "string",
                        "required": True,
                        "default": "6109.10.0012",
                        "description": ""
                    }
                ]
            },
            "steps": [
                {
                    "key": "duty",
                    "name": "Look up the import duty",
                    "type": "method",
                    "method": "hts.usitc.gov/get_import_duty",
                    "input": {
                        "hts_code": "{{trigger.hts_code}}"
                    },
                    "connection": None,
                    "on_error": "stop"
                },
                {
                    "key": "note",
                    "name": "Write the rates as a note",
                    "type": "transform",
                    "instruction": "Write the general, special and column 2 rates as a short plain-text note; stop when the code has no rate.",
                    "code": "const duty = data.steps.duty.data;\nif (!duty || !duty.general_rate) stop('This code has no rate.');\nreturn [\n  `HTS ${duty.hts_code} (${duty.release})`,\n  `General rate: ${duty.general_rate}`,\n  `Special rates: ${duty.special_rates || 'none'}`,\n  `Column 2 rate: ${duty.column_2_rate}`,\n  duty.source_url,\n].join('\\n');"
                },
                {
                    "key": "send",
                    "name": "Email the note",
                    "type": "email",
                    "to": "ada@example.com",
                    "subject": "Import duty for {{trigger.hts_code}}",
                    "body": "{{steps.note}}"
                }
            ]
        }
    },
    timeout=180,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

Sent with your key, kept for this tab only. Get an API key.

{
  "id": "wf_01m72hccc2f47t2r9qry60m4cq",
  "name": "Import duty lookup",
  "description": "Looks up the US import duty for an HTS code and emails the rates.",
  "trigger_type": "manual",
  "enabled": false,
  "step_count": 3,
  "methods": [
    "hts.usitc.gov/get_import_duty"
  ],
  "cost": {
    "credits": 3,
    "per_item": null
  },
  "last_run": {
    "id": "wfr_01m72hcccgfzqsgbfn5w7q33sv",
    "status": "completed",
    "created_at": "2026-11-10T10:52:08.464Z",
    "started_at": "2026-11-10T10:52:08.465Z",
    "finished_at": "2026-11-10T10:52:15.650Z"
  },
  "next_run_at": null,
  "created_at": "2026-11-10T10:52:08.451Z",
  "updated_at": "2026-11-10T10:52:08.451Z",
  "definition": {
    "trigger": {
      "type": "manual",
      "inputs": [
        {
          "key": "hts_code",
          "label": "HTS code",
          "type": "string",
          "required": true,
          "default": "6109.10.0012",
          "description": ""
        }
      ]
    },
    "steps": [
      {
        "key": "duty",
        "name": "Look up the import duty",
        "type": "method",
        "method": "hts.usitc.gov/get_import_duty",
        "input": {
          "hts_code": "{{trigger.hts_code}}"
        },
        "connection": null,
        "on_error": "stop"
      },
      {
        "key": "note",
        "name": "Write the rates as a note",
        "type": "transform",
        "instruction": "Write the general, special and column 2 rates as a short plain-text note; stop when the code has no rate.",
        "code": "const duty = data.steps.duty.data;\nif (!duty || !duty.general_rate) stop('This code has no rate.');\nreturn [\n  `HTS ${duty.hts_code} (${duty.release})`,\n  `General rate: ${duty.general_rate}`,\n  `Special rates: ${duty.special_rates || 'none'}`,\n  `Column 2 rate: ${duty.column_2_rate}`,\n  duty.source_url,\n].join('\\n');"
      },
      {
        "key": "send",
        "name": "Email the note",
        "type": "email",
        "to": "ada@example.com",
        "subject": "Import duty for {{trigger.hts_code}}",
        "body": "{{steps.note}}"
      }
    ]
  },
  "webhook_url": null,
  "signing_secret": null,
  "incomplete": []
}

{
  "workflow": null,
  "ai": {
    "summary": null,
    "missing": [],
    "reply": "I can build this: each day it collects new invoices from your supplier portal, summarizes them and emails finance. Which supplier portal do you use?",
    "question": {
      "text": "Which supplier portal do you use?",
      "options": [
        {
          "label": "SAP Ariba",
          "value": "service.ariba.com"
        },
        {
          "label": "Coupa",
          "value": "supplier.coupahost.com"
        },
        {
          "label": "Basware",
          "value": "portal.basware.com"
        }
      ],
      "placeholder": "Portal address, e.g. portal.example.com",
      "allow_other": true
    }
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "2 problems, first steps[0].input.country: Not an input of hts.usitc.gov/get_import_duty. It takes: hts_code.",
    "next_step": "Fix the request as the message says, then send it again.",
    "errors": [
      {
        "path": "steps[0].input.country",
        "message": "Not an input of hts.usitc.gov/get_import_duty. It takes: hts_code."
      },
      {
        "path": "steps[1].code",
        "message": "The code reads step \"send\", which has not run yet here: only steps before this one can be read."
      }
    ],
    "doc_url": "https://docs.fous.com/guides/errors#invalid_request",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}

Write a transform’s code

AI writes the JavaScript of one transform from its instruction, given the definition it is in (sent as it is, saved or not): it reads the step’s place, the trigger, the steps before it and their methods’ output schemas. Nothing is saved; saving a definition whose transform has an instruction and empty code does the same.

Request body

Required, JSON.

instructionstringrequired
definitionobjectrequired
The workflow’s definition.
step_keystringrequired
The transform’s key in it.

Returns

200The code.

The answer has these fields:

codestringrequired

Errors

Status	Code	When
400	`invalid_request`	The body does not hold, or the definition has no such step
402	`insufficient_credits`	No credits left, and no extra credits on (or capped, or failing to charge); nothing starts
403	`plan_limit`	The plan’s AI messages are used (limit.kind chat_messages; window: day or period): Free includes 40 in all and 15 a day, the paid plans more each month
422	`invalid_input`	The AI’s code did not hold twice
429	`rate_limited`	Too many AI messages this minute (limit.kind chat_per_minute)
503	`service_unavailable`	The AI is unavailable: nothing was saved or changed

curl 'https://api.fous.com/v1/workflows/ai-code' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "instruction": "Write the general, special and column 2 rates as a short plain-text note",
    "definition": {
      "trigger": {
        "type": "manual",
        "inputs": [
          {
            "key": "hts_code",
            "label": "HTS code",
            "type": "string",
            "required": true,
            "default": "6109.10.0012",
            "description": ""
          }
        ]
      },
      "steps": [
        {
          "key": "duty",
          "name": "Look up the import duty",
          "type": "method",
          "method": "hts.usitc.gov/get_import_duty",
          "input": {
            "hts_code": "{{trigger.hts_code}}"
          },
          "connection": null,
          "on_error": "stop"
        },
        {
          "key": "note",
          "name": "Write the rates as a note",
          "type": "transform",
          "instruction": "Write the general, special and column 2 rates as a short plain-text note; stop when the code has no rate.",
          "code": "const duty = data.steps.duty.data;\nif (!duty || !duty.general_rate) stop('\''This code has no rate.'\'');\nreturn [\n  `HTS ${duty.hts_code} (${duty.release})`,\n  `General rate: ${duty.general_rate}`,\n  `Special rates: ${duty.special_rates || '\''none'\''}`,\n  `Column 2 rate: ${duty.column_2_rate}`,\n  duty.source_url,\n].join('\''\\n'\'');"
        },
        {
          "key": "send",
          "name": "Email the note",
          "type": "email",
          "to": "ada@example.com",
          "subject": "Import duty for {{trigger.hts_code}}",
          "body": "{{steps.note}}"
        }
      ]
    },
    "step_key": "note"
  }'

// Save as fous.mts, then run: npx tsx fous.mts
const response = await fetch('https://api.fous.com/v1/workflows/ai-code', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    instruction: 'Write the general, special and column 2 rates as a short plain-text note',
    definition: {
      trigger: {
        type: 'manual',
        inputs: [
          {
            key: 'hts_code',
            label: 'HTS code',
            type: 'string',
            required: true,
            default: '6109.10.0012',
            description: ''
          }
        ]
      },
      steps: [
        {
          key: 'duty',
          name: 'Look up the import duty',
          type: 'method',
          method: 'hts.usitc.gov/get_import_duty',
          input: {
            hts_code: '{{trigger.hts_code}}'
          },
          connection: null,
          on_error: 'stop'
        },
        {
          key: 'note',
          name: 'Write the rates as a note',
          type: 'transform',
          instruction: 'Write the general, special and column 2 rates as a short plain-text note; stop when the code has no rate.',
          code: "const duty = data.steps.duty.data;\nif (!duty || !duty.general_rate) stop('This code has no rate.');\nreturn [\n  `HTS ${duty.hts_code} (${duty.release})`,\n  `General rate: ${duty.general_rate}`,\n  `Special rates: ${duty.special_rates || 'none'}`,\n  `Column 2 rate: ${duty.column_2_rate}`,\n  duty.source_url,\n].join('\\n');'
        },
        {
          key: 'send',
          name: 'Email the note',
          type: 'email',
          to: 'ada@example.com',
          subject: 'Import duty for {{trigger.hts_code}}',
          body: '{{steps.note}}'
        }
      ]
    },
    step_key: 'note"
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

import os
import requests

response = requests.post(
    "https://api.fous.com/v1/workflows/ai-code",
    headers={
        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",
    },
    json={
        "instruction": "Write the general, special and column 2 rates as a short plain-text note",
        "definition": {
            "trigger": {
                "type": "manual",
                "inputs": [
                    {
                        "key": "hts_code",
                        "label": "HTS code",
                        "type": "string",
                        "required": True,
                        "default": "6109.10.0012",
                        "description": ""
                    }
                ]
            },
            "steps": [
                {
                    "key": "duty",
                    "name": "Look up the import duty",
                    "type": "method",
                    "method": "hts.usitc.gov/get_import_duty",
                    "input": {
                        "hts_code": "{{trigger.hts_code}}"
                    },
                    "connection": None,
                    "on_error": "stop"
                },
                {
                    "key": "note",
                    "name": "Write the rates as a note",
                    "type": "transform",
                    "instruction": "Write the general, special and column 2 rates as a short plain-text note; stop when the code has no rate.",
                    "code": "const duty = data.steps.duty.data;\nif (!duty || !duty.general_rate) stop('This code has no rate.');\nreturn [\n  `HTS ${duty.hts_code} (${duty.release})`,\n  `General rate: ${duty.general_rate}`,\n  `Special rates: ${duty.special_rates || 'none'}`,\n  `Column 2 rate: ${duty.column_2_rate}`,\n  duty.source_url,\n].join('\\n');"
                },
                {
                    "key": "send",
                    "name": "Email the note",
                    "type": "email",
                    "to": "ada@example.com",
                    "subject": "Import duty for {{trigger.hts_code}}",
                    "body": "{{steps.note}}"
                }
            ]
        },
        "step_key": "note"
    },
    timeout=180,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

Sent with your key, kept for this tab only. Get an API key.

{
  "code": "const duty = data.steps.duty.data;\nif (!duty || !duty.general_rate) stop('This code has no rate.');\nreturn [\n  `HTS ${duty.hts_code} (${duty.release})`,\n  `General rate: ${duty.general_rate}`,\n  `Special rates: ${duty.special_rates || 'none'}`,\n  `Column 2 rate: ${duty.column_2_rate}`,\n  duty.source_url,\n].join('\\n');"
}

{
  "error": {
    "code": "invalid_request",
    "message": "step_key: The definition has no step \"note\".",
    "errors": [
      {
        "path": "step_key",
        "message": "The definition has no step \"note\"."
      }
    ],
    "doc_url": "https://docs.fous.com/guides/errors#invalid_request",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}

Get a workflow

The workflow with its definition, its webhook’s address, and incomplete: the values still to fill in before it can run. Free. While a step’s method is building (pending.status building), read it again every few seconds: once the build ends, the step runs the new method, or its pending.status is failed with the reason.

Path parameters

idstringrequired

Returns

A Workflow object.

200The workflow.

Errors

Status	Code	When
404	`not_found`	No such workflow

curl 'https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq' \
  -H "Authorization: Bearer $FOUS_API_KEY"

// Save as fous.mts, then run: npx tsx fous.mts
const response = await fetch('https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq', {
  headers: {
    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,
  },
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

import os
import requests

response = requests.get(
    "https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq",
    headers={
        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",
    },
    timeout=180,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

Sent with your key, kept for this tab only. Get an API key.

{
  "id": "wf_01m72hccc2f47t2r9qry60m4cq",
  "name": "Import duty lookup",
  "description": "Looks up the US import duty for an HTS code and emails the rates.",
  "trigger_type": "manual",
  "enabled": false,
  "step_count": 3,
  "methods": [
    "hts.usitc.gov/get_import_duty"
  ],
  "cost": {
    "credits": 3,
    "per_item": null
  },
  "last_run": {
    "id": "wfr_01m72hcccgfzqsgbfn5w7q33sv",
    "status": "completed",
    "created_at": "2026-11-10T10:52:08.464Z",
    "started_at": "2026-11-10T10:52:08.465Z",
    "finished_at": "2026-11-10T10:52:15.650Z"
  },
  "next_run_at": null,
  "created_at": "2026-11-10T10:52:08.451Z",
  "updated_at": "2026-11-10T10:52:08.451Z",
  "definition": {
    "trigger": {
      "type": "manual",
      "inputs": [
        {
          "key": "hts_code",
          "label": "HTS code",
          "type": "string",
          "required": true,
          "default": "6109.10.0012",
          "description": ""
        }
      ]
    },
    "steps": [
      {
        "key": "duty",
        "name": "Look up the import duty",
        "type": "method",
        "method": "hts.usitc.gov/get_import_duty",
        "input": {
          "hts_code": "{{trigger.hts_code}}"
        },
        "connection": null,
        "on_error": "stop"
      },
      {
        "key": "note",
        "name": "Write the rates as a note",
        "type": "transform",
        "instruction": "Write the general, special and column 2 rates as a short plain-text note; stop when the code has no rate.",
        "code": "const duty = data.steps.duty.data;\nif (!duty || !duty.general_rate) stop('This code has no rate.');\nreturn [\n  `HTS ${duty.hts_code} (${duty.release})`,\n  `General rate: ${duty.general_rate}`,\n  `Special rates: ${duty.special_rates || 'none'}`,\n  `Column 2 rate: ${duty.column_2_rate}`,\n  duty.source_url,\n].join('\\n');"
      },
      {
        "key": "send",
        "name": "Email the note",
        "type": "email",
        "to": "ada@example.com",
        "subject": "Import duty for {{trigger.hts_code}}",
        "body": "{{steps.note}}"
      }
    ]
  },
  "webhook_url": null,
  "signing_secret": null,
  "incomplete": []
}

{
  "error": {
    "code": "not_found",
    "message": "No such workflow.",
    "doc_url": "https://docs.fous.com/guides/errors#not_found",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}

Update a workflow

Changes any of name, description, definition and enabled, or asks the AI to change it: send {prompt} or {messages} (the conversation so far, newest last), with timezone if the workflow names a time. A new definition is checked as on create, and a transform with an instruction and empty code gets its code written, as does one whose instruction changed while its code is still the saved one; a run already going keeps the definition it started with. The AI’s change is saved the same way. With preview: true it is answered but not saved (a name and definition sent with it are the draft it reads); the AI that only answers (a question, or asking one back) changes nothing, and its words are in ai. With Accept: text/event-stream the answer streams while the AI writes (same 200, same body in done).

Path parameters

idstringrequired

Request body

Required, JSON.

namestringOptional
descriptionstringOptional
definitionobjectOptional
A trigger, then steps. Text in a method’s input, a loop’s over, an email and a webhook may hold templates: {{trigger.<key>}}, {{steps.<key>.<path>}}, {{loop.item}}, {{loop.index}}, {{run.id}}, {{run.started_at}}, {{now}}, {{previous.steps.<key>.<path>}} (the workflow’s last successful run; null on a first run), with filters ({{steps.search.data.results | length}}). A text that is exactly one template keeps the value’s type; a path that leads nowhere is null. A transform’s code reads the same data as data.trigger, data.steps.<key>, data.loop and data.previous.
Show child attributesHide child attributes
- triggerobjectrequired
  Show child attributesHide child attributes
  - typestringrequired
    Every workflow can also be run by hand with POST /v1/workflows/{id}/runs.
    manualschedulewebhook
  - inputsarray of object
    What a run takes, read as {{trigger.<key>}}.
    Show child attributesHide child attributes
    keystringrequired
    labelstring
    typestringrequired
    stringnumberboolean
    requiredboolean
    defaultstring or number or boolean or null
    descriptionstring
  - scheduleobject
    type schedule only.
    Show child attributesHide child attributes
    frequencystringrequired
    minutes: every N minutes; hourly: every N hours; daily, weekly and monthly: at at, every N days, weeks or months; weekdays: Monday to Friday at at.
    minuteshourlydailyweekdaysweeklymonthly
    everyinteger
    N. Not used by weekdays: leave it out or send 1.
    atstring
    HH:MM, daily, weekdays, weekly and monthly.
    dayinteger
    monthly: the day of the month, 1 to 31, or -1 for the last day (default 1). A day a month does not have (31 in April, 30 in February) is its last day.
    weekdayinteger
    weekly: 0 is Sunday.
    timezonestring
    An IANA time zone, like Europe/Prague. Default UTC.
    inputobject
    The input a scheduled run takes.
- stepsarray of objectrequired
  Any number of steps, loops nested as deep as needed; the definition is at most 200 KB.
  Show child attributesHide child attributes
  - keystring
    Unique in the whole workflow; what templates (steps.<key>) and code (data.steps.<key>) read the step’s output by. Left out, it is made from the name (List invoices: list_invoices).
  - namestring
    Plain words a person reads.
  - typestringrequired
    methodaitransformfilterloopdelayemailwebhook
  - methodstring or null
    method: the method’s slug; null while its method is pending.
  - pendingobject
    method: a method your organization does not have yet. The workflow cannot run or be turned on while a step is pending: accept building it with POST /v1/workflows/{id}/steps/{key}/build (status building, then the step runs the new method, its input and the later steps wired to it by AI). failed: reason says why the build did not make it; building again tries again.
    Show child attributesHide child attributes
    needstringrequired
    What the method does, in plain words.
    build_promptstringrequired
    What the builder is asked to make.
    sitestring or null
    The website to build on (a domain or sign-in host). Without one the step cannot be built (409 site_required) and is listed in incomplete; send site to POST /v1/workflows/{id}/steps/{key}/build.
    build_idstring or nullrequired
    Its build, once accepted.
    statusstringrequired
    proposedbuildingfailed
    reasonstring
    failed: why.
  - inputJSON value
    method: its input, an object; any value may be a template. A required input left empty makes the workflow incomplete until it is filled in. ai: more data its prompt is about, a template or an object of them, sent with the prompt; null (default): the prompt alone. Writing the data’s templates in the prompt itself does the same.
  - connectionstring or null
    method: the conn_ id to run with; null for the site’s default.
  - on_errorstring
    method: stop (default) fails the run; continue records the failure and goes on.
    stopcontinue
  - instructionstring
    transform: what the step does, in plain words. Change it and send the code as it was saved (or empty), and the code is written again from it when the workflow is saved; code you changed is kept.
  - codestring
    transform: the body of function (data, stop) that returns the step’s output (JSON). data is {trigger, steps: {<key>: output}, loop?: {item, index}, previous: the workflow’s last successful run before this one as {run_id, finished_at, trigger, steps: {<key>: output}}, or null on its first run, state: the step’s own memory across runs, an object ({} at first) that the next run starts from as this code leaves it once its run completes (top-level transforms; at most 256 KB; the ids already seen, for “only new items”)}; stop(reason) ends the run quietly, successful, like a filter (inside a loop: skips the rest of that item); prefer a filter step for conditions it can test. It runs in an isolated JavaScript sandbox: no network, files or modules, 2 seconds and 64 MB at most. Sent empty with an instruction, Fous writes it with AI when the workflow is saved; code you write is kept as written.
  - promptstring
    ai: what to write or decide, in plain words; templates read the data (a list, an object or a long text a template writes in is sent as the prompt’s data, so the prompt’s own words are never cut). A model answers on every run: it reads about 10,000 tokens (prompt and data; longer data is shortened, and the model is told) and writes up to about 800 words. Output: {text}, or with fields an object with each field’s text. A failed answer (the model declined, ran out of room, or did not answer) fails the step and costs nothing.
  - fieldsarray of string
    ai: answer these fields (short text each) instead of one text, read as {{steps.<key>.<field>}}. Default [].
  - conditionsarray of object
    filter: what must hold for the run to go on. value is a template; op one of exists, not_exists (empty: null, "", [] or {}), equals, not_equals, contains, not_contains (text in any case; a list by its items), gt, gte, lt, lte (numbers, a numeric text too; a list by its length); compare is text or a template, for the operators that compare. When the filter does not pass, its record is filtered with output {passed: false, message: "Stopped: …", skipped: the action steps it skipped}.
    Show child attributesHide child attributes
    valuestringrequired
    opstringrequired
    existsnot_existsequalsnot_equalscontainsnot_containsgtgteltlte
    comparestring
  - matchstring
    filter: all (default) of its conditions, or any one.
    allany
  - overstring
    loop: a template that gives a list (a text is split at commas and new lines).
  - maxinteger
    loop: at most this many items (the rest are left out): any number, each item’s action steps costing credits. Left out: 10, and 5 on Free.
  - stepsarray of object
    loop: its steps.
    Show child attributesHide child attributes
    keystring
    Unique in the whole workflow; what templates (steps.<key>) and code (data.steps.<key>) read the step’s output by. Left out, it is made from the name (List invoices: list_invoices).
    namestring
    Plain words a person reads.
    typestringrequired
    methodaitransformfilterloopdelayemailwebhook
    methodstring or null
    method: the method’s slug; null while its method is pending.
    pendingobject
    method: a method your organization does not have yet. The workflow cannot run or be turned on while a step is pending: accept building it with POST /v1/workflows/{id}/steps/{key}/build (status building, then the step runs the new method, its input and the later steps wired to it by AI). failed: reason says why the build did not make it; building again tries again.
    inputJSON value
    method: its input, an object; any value may be a template. A required input left empty makes the workflow incomplete until it is filled in. ai: more data its prompt is about, a template or an object of them, sent with the prompt; null (default): the prompt alone. Writing the data’s templates in the prompt itself does the same.
    connectionstring or null
    method: the conn_ id to run with; null for the site’s default.
    on_errorstring
    method: stop (default) fails the run; continue records the failure and goes on.
    stopcontinue
    instructionstring
    transform: what the step does, in plain words. Change it and send the code as it was saved (or empty), and the code is written again from it when the workflow is saved; code you changed is kept.
    codestring
    transform: the body of function (data, stop) that returns the step’s output (JSON). data is {trigger, steps: {<key>: output}, loop?: {item, index}, previous: the workflow’s last successful run before this one as {run_id, finished_at, trigger, steps: {<key>: output}}, or null on its first run, state: the step’s own memory across runs, an object ({} at first) that the next run starts from as this code leaves it once its run completes (top-level transforms; at most 256 KB; the ids already seen, for “only new items”)}; stop(reason) ends the run quietly, successful, like a filter (inside a loop: skips the rest of that item); prefer a filter step for conditions it can test. It runs in an isolated JavaScript sandbox: no network, files or modules, 2 seconds and 64 MB at most. Sent empty with an instruction, Fous writes it with AI when the workflow is saved; code you write is kept as written.
    promptstring
    ai: what to write or decide, in plain words; templates read the data (a list, an object or a long text a template writes in is sent as the prompt’s data, so the prompt’s own words are never cut). A model answers on every run: it reads about 10,000 tokens (prompt and data; longer data is shortened, and the model is told) and writes up to about 800 words. Output: {text}, or with fields an object with each field’s text. A failed answer (the model declined, ran out of room, or did not answer) fails the step and costs nothing.
    fieldsarray of string
    ai: answer these fields (short text each) instead of one text, read as {{steps.<key>.<field>}}. Default [].
    conditionsarray of object
    filter: what must hold for the run to go on. value is a template; op one of exists, not_exists (empty: null, "", [] or {}), equals, not_equals, contains, not_contains (text in any case; a list by its items), gt, gte, lt, lte (numbers, a numeric text too; a list by its length); compare is text or a template, for the operators that compare. When the filter does not pass, its record is filtered with output {passed: false, message: "Stopped: …", skipped: the action steps it skipped}.
    matchstring
    filter: all (default) of its conditions, or any one.
    allany
    overstring
    loop: a template that gives a list (a text is split at commas and new lines).
    maxinteger
    loop: at most this many items (the rest are left out): any number, each item’s action steps costing credits. Left out: 10, and 5 on Free.
    stepsarray of object
    loop: its steps.
    secondsinteger
    delay.
    tostring
    email: addresses separated by commas; empty: the workflow is saved incomplete until it is filled in. On Free, Starter and Pro, only people in your organization (their sign-in addresses); on Business and Enterprise, anyone. It comes from "<workflow name> via Fous" <workflows@fous.com>, and replies go to the person who made the workflow.
    subjectstring
    email.
    bodyJSON value
    email: the plain-text body (line breaks kept). webhook: the JSON to send, a template or an object of them; left out, the previous step’s output.
    urlstring
    webhook: a public https address; empty: the workflow is saved incomplete until it is filled in. Each POST carries X-Fous-Workflow, X-Fous-Run, X-Fous-Signature (t=<unix seconds>,v1=<HMAC-SHA256 in hex of "<t>.<body>" with the workflow’s signing_secret>) and an Idempotency-Key that is the same on every attempt of the step (receivers dedupe on it: Fous retries on 5xx, 408, 429 and connection failures, and a run taken up again sends what it recorded under it; one that got no answer in time is not sent again), plus the step’s headers.
    headersarray of object
    webhook: headers sent with each POST, for a receiver that needs a key or a token (Authorization, X-API-Key). Their values are write-only secrets: sent as value to set one (empty text clears it), left out to keep the saved one; answers and run records never hold them, only a masked hint (null: no value yet, and the workflow is incomplete until it has one). Not Host, Content-Type, Content-Length, Idempotency-Key, Connection, Transfer-Encoding or X-Fous-*.
  - secondsinteger
    delay.
  - tostring
    email: addresses separated by commas; empty: the workflow is saved incomplete until it is filled in. On Free, Starter and Pro, only people in your organization (their sign-in addresses); on Business and Enterprise, anyone. It comes from "<workflow name> via Fous" <workflows@fous.com>, and replies go to the person who made the workflow.
  - subjectstring
    email.
  - bodyJSON value
    email: the plain-text body (line breaks kept). webhook: the JSON to send, a template or an object of them; left out, the previous step’s output.
  - urlstring
    webhook: a public https address; empty: the workflow is saved incomplete until it is filled in. Each POST carries X-Fous-Workflow, X-Fous-Run, X-Fous-Signature (t=<unix seconds>,v1=<HMAC-SHA256 in hex of "<t>.<body>" with the workflow’s signing_secret>) and an Idempotency-Key that is the same on every attempt of the step (receivers dedupe on it: Fous retries on 5xx, 408, 429 and connection failures, and a run taken up again sends what it recorded under it; one that got no answer in time is not sent again), plus the step’s headers.
  - headersarray of object
    webhook: headers sent with each POST, for a receiver that needs a key or a token (Authorization, X-API-Key). Their values are write-only secrets: sent as value to set one (empty text clears it), left out to keep the saved one; answers and run records never hold them, only a masked hint (null: no value yet, and the workflow is incomplete until it has one). Not Host, Content-Type, Content-Length, Idempotency-Key, Connection, Transfer-Encoding or X-Fous-*.
    Show child attributesHide child attributes
    namestringrequired
    valuestring
    Sent only: the value to save.
    hintstring or null
    The saved value masked (its last 4 characters when long), or null.
enabledbooleanOptional
promptstringOptional
A change in plain words, for the AI.
messagesarray of objectOptional
The conversation so far, newest last, ending with the person’s.
Show child attributesHide child attributes
- rolestringrequired
  userassistant
- textstringrequired
timezonestringOptional
An IANA time zone. Default UTC.
previewbooleanOptional
With a message to the AI: answer the change without saving it.

Returns

200Saved; a change the AI made is the saved workflow with ai (with preview, the workflow as it would be; when the AI only answered, the workflow as it is).

Errors

Status	Code	When
400	`invalid_request`	The definition (or the body) does not hold: errors lists each problem at its place
402	`insufficient_credits`	No credits left, and no extra credits on (or capped, or failing to charge); nothing starts
403	`plan_limit`	Schedules and webhooks come with a paid plan (limit.kind api)
404	`not_found`	No such workflow
409	`conflict`	reason workflow_incomplete: a value is still to fill in (incomplete) or a step’s method still to build (steps), so the workflow cannot run or be turned on
422	`invalid_input`	reason ai_failed: the AI’s draft did not hold twice
429	`rate_limited`	Too many AI messages this minute (limit.kind chat_per_minute)
503	`service_unavailable`	The AI is unavailable: nothing was saved or changed

curl 'https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq' \
  -X PATCH \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Accept: text/event-stream' \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": true
  }'

// Save as fous.mts, then run: npx tsx fous.mts
const response = await fetch('https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,
    Accept: 'text/event-stream',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    enabled: true
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

import os
import requests

response = requests.patch(
    "https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq",
    headers={
        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",
        "Accept": "text/event-stream",
    },
    json={
        "enabled": True
    },
    timeout=180,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

Sent with your key, kept for this tab only. Get an API key.

{
  "id": "wf_01m72hccc2f47t2r9qry60m4cq",
  "name": "Import duty lookup",
  "description": "Looks up the US import duty for an HTS code and emails the rates.",
  "trigger_type": "manual",
  "enabled": false,
  "step_count": 3,
  "methods": [
    "hts.usitc.gov/get_import_duty"
  ],
  "cost": {
    "credits": 3,
    "per_item": null
  },
  "last_run": {
    "id": "wfr_01m72hcccgfzqsgbfn5w7q33sv",
    "status": "completed",
    "created_at": "2026-11-10T10:52:08.464Z",
    "started_at": "2026-11-10T10:52:08.465Z",
    "finished_at": "2026-11-10T10:52:15.650Z"
  },
  "next_run_at": null,
  "created_at": "2026-11-10T10:52:08.451Z",
  "updated_at": "2026-11-10T10:52:08.451Z",
  "definition": {
    "trigger": {
      "type": "manual",
      "inputs": [
        {
          "key": "hts_code",
          "label": "HTS code",
          "type": "string",
          "required": true,
          "default": "6109.10.0012",
          "description": ""
        }
      ]
    },
    "steps": [
      {
        "key": "duty",
        "name": "Look up the import duty",
        "type": "method",
        "method": "hts.usitc.gov/get_import_duty",
        "input": {
          "hts_code": "{{trigger.hts_code}}"
        },
        "connection": null,
        "on_error": "stop"
      },
      {
        "key": "note",
        "name": "Write the rates as a note",
        "type": "transform",
        "instruction": "Write the general, special and column 2 rates as a short plain-text note; stop when the code has no rate.",
        "code": "const duty = data.steps.duty.data;\nif (!duty || !duty.general_rate) stop('This code has no rate.');\nreturn [\n  `HTS ${duty.hts_code} (${duty.release})`,\n  `General rate: ${duty.general_rate}`,\n  `Special rates: ${duty.special_rates || 'none'}`,\n  `Column 2 rate: ${duty.column_2_rate}`,\n  duty.source_url,\n].join('\\n');"
      },
      {
        "key": "send",
        "name": "Email the note",
        "type": "email",
        "to": "ada@example.com",
        "subject": "Import duty for {{trigger.hts_code}}",
        "body": "{{steps.note}}"
      }
    ]
  },
  "webhook_url": null,
  "signing_secret": null,
  "incomplete": [],
  "ai": {
    "summary": "The note now also lists the units of quantity, after the column 2 rate.",
    "missing": [],
    "reply": null,
    "question": null
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "2 problems, first steps[0].input.country: Not an input of hts.usitc.gov/get_import_duty. It takes: hts_code.",
    "next_step": "Fix the request as the message says, then send it again.",
    "errors": [
      {
        "path": "steps[0].input.country",
        "message": "Not an input of hts.usitc.gov/get_import_duty. It takes: hts_code."
      },
      {
        "path": "steps[1].code",
        "message": "The code reads step \"send\", which has not run yet here: only steps before this one can be read."
      }
    ],
    "doc_url": "https://docs.fous.com/guides/errors#invalid_request",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}

Delete a workflow

Deletes the workflow: its schedule and webhook stop, and runs still going are canceled. Its runs stay readable.

Path parameters

idstringrequired

Returns

200Deleted.

The answer has these fields:

idstring
deletedboolean

Errors

Status	Code	When
404	`not_found`	No such workflow

curl 'https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq' \
  -X DELETE \
  -H "Authorization: Bearer $FOUS_API_KEY"

// Save as fous.mts, then run: npx tsx fous.mts
const response = await fetch('https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,
  },
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

import os
import requests

response = requests.delete(
    "https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq",
    headers={
        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",
    },
    timeout=180,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

Sent with your key, kept for this tab only. Get an API key.

{
  "id": "wf_01m72hccc2f47t2r9qry60m4cq",
  "deleted": true
}

{
  "error": {
    "code": "not_found",
    "message": "No such workflow.",
    "doc_url": "https://docs.fous.com/guides/errors#not_found",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}

Build a pending step’s method

Starts a build of the method a pending step needs, from the step’s build_prompt, as POST /v1/builds starts one (same plan rules and errors). The step’s pending becomes {build_id, status: building}. When the build ends, the step runs the new method with its input and later steps’ references wired by AI, or pending.status is failed with the reason; calling this again retries. Poll GET /v1/workflows/{id} to follow it. site (optional) sets the step’s site and starts the build in one call, saved only when the build starts. A step already building returns its build; sending a different site for it returns 409.

Path parameters

idstringrequired
keystringrequired

Request body

Optional, JSON.

sitestringOptional
Optional: the website to build on, like portal.example.com. Replaces the step’s site when the build starts. Required when the step has none (reason site_required).
connectionsarray of stringOptional
Optional: the connected accounts (conn_…) the build may use, as in POST /v1/builds.

Returns

202Building.

The answer has these fields:

build_idstringrequired
Also in GET /v1/builds/{id}.

Errors

Status	Code	When
400	`invalid_request`	The definition (or the body) does not hold: errors lists each problem at its place
403	`plan_limit`	A plan limit (plan_limit): the plan’s sites all have methods (kind sites), or Free’s 3 builds are used (kind builds); or the caller is a reader (forbidden)
404	`not_found`	No such workflow, or no step with that key waiting for a method
409	`conflict`	reason site_required: no site was sent and the step has none. Or code conflict: the step is already building on a different site
422	`not_buildablerequest_refused`	No website, app, account or API is involved (not_buildable), or the request check turned it away (request_refused, with its verdict as reason)
429	`rate_limited`	Another build of the organization is running (limit.kind concurrent_builds)

curl 'https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/steps/rates/build' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "site": "portal.example.com",
    "connections": [
      "conn_01m5kyvsdxea78rpr2j3qzzd1z"
    ]
  }'

// Save as fous.mts, then run: npx tsx fous.mts
const response = await fetch('https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/steps/rates/build', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    site: 'portal.example.com',
    connections: [
      'conn_01m5kyvsdxea78rpr2j3qzzd1z'
    ]
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

import os
import requests

response = requests.post(
    "https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/steps/rates/build",
    headers={
        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",
    },
    json={
        "site": "portal.example.com",
        "connections": [
            "conn_01m5kyvsdxea78rpr2j3qzzd1z"
        ]
    },
    timeout=180,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

Sent with your key, kept for this tab only. Get an API key.

{
  "build_id": "bld_01m6vqpmggfbbv1166jvvvmsp7"
}

{
  "error": {
    "code": "invalid_request",
    "message": "2 problems, first steps[0].input.country: Not an input of hts.usitc.gov/get_import_duty. It takes: hts_code.",
    "next_step": "Fix the request as the message says, then send it again.",
    "errors": [
      {
        "path": "steps[0].input.country",
        "message": "Not an input of hts.usitc.gov/get_import_duty. It takes: hts_code."
      },
      {
        "path": "steps[1].code",
        "message": "The code reads step \"send\", which has not run yet here: only steps before this one can be read."
      }
    ],
    "doc_url": "https://docs.fous.com/guides/errors#invalid_request",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}

Remove a step

Removes a step, a pending one included, and what is inside it. Whatever read its output reads nothing: templates are emptied, an emptied required text is left to fill in (incomplete), a filter drops conditions about it, and a transform whose code read it gets new code (a transform with code and no instruction is left as it is and the removal answers 400 naming it: change its code first). Saved like any change: an enabled workflow left with a value to fill in is refused (reason workflow_incomplete).

Path parameters

idstringrequired
keystringrequired

Returns

A Workflow object.

200Removed.

Errors

Status	Code	When
400	`invalid_request`	The definition (or the body) does not hold: errors lists each problem at its place
404	`not_found`	No such workflow or step
409	`conflict`	reason workflow_incomplete: a value is still to fill in (incomplete) or a step’s method still to build (steps), so the workflow cannot run or be turned on

curl 'https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/steps/rates' \
  -X DELETE \
  -H "Authorization: Bearer $FOUS_API_KEY"

// Save as fous.mts, then run: npx tsx fous.mts
const response = await fetch('https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/steps/rates', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,
  },
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

import os
import requests

response = requests.delete(
    "https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/steps/rates",
    headers={
        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",
    },
    timeout=180,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

Sent with your key, kept for this tab only. Get an API key.

{
  "id": "wf_01m72hccc2f47t2r9qry60m4cq",
  "name": "Import duty lookup",
  "description": "Looks up the US import duty for an HTS code and emails the rates.",
  "trigger_type": "manual",
  "enabled": false,
  "step_count": 3,
  "methods": [
    "hts.usitc.gov/get_import_duty"
  ],
  "cost": {
    "credits": 3,
    "per_item": null
  },
  "last_run": {
    "id": "wfr_01m72hcccgfzqsgbfn5w7q33sv",
    "status": "completed",
    "created_at": "2026-11-10T10:52:08.464Z",
    "started_at": "2026-11-10T10:52:08.465Z",
    "finished_at": "2026-11-10T10:52:15.650Z"
  },
  "next_run_at": null,
  "created_at": "2026-11-10T10:52:08.451Z",
  "updated_at": "2026-11-10T10:52:08.451Z",
  "definition": {
    "trigger": {
      "type": "manual",
      "inputs": [
        {
          "key": "hts_code",
          "label": "HTS code",
          "type": "string",
          "required": true,
          "default": "6109.10.0012",
          "description": ""
        }
      ]
    },
    "steps": [
      {
        "key": "duty",
        "name": "Look up the import duty",
        "type": "method",
        "method": "hts.usitc.gov/get_import_duty",
        "input": {
          "hts_code": "{{trigger.hts_code}}"
        },
        "connection": null,
        "on_error": "stop"
      },
      {
        "key": "note",
        "name": "Write the rates as a note",
        "type": "transform",
        "instruction": "Write the general, special and column 2 rates as a short plain-text note; stop when the code has no rate.",
        "code": "const duty = data.steps.duty.data;\nif (!duty || !duty.general_rate) stop('This code has no rate.');\nreturn [\n  `HTS ${duty.hts_code} (${duty.release})`,\n  `General rate: ${duty.general_rate}`,\n  `Special rates: ${duty.special_rates || 'none'}`,\n  `Column 2 rate: ${duty.column_2_rate}`,\n  duty.source_url,\n].join('\\n');"
      },
      {
        "key": "send",
        "name": "Email the note",
        "type": "email",
        "to": "ada@example.com",
        "subject": "Import duty for {{trigger.hts_code}}",
        "body": "{{steps.note}}"
      }
    ]
  },
  "webhook_url": null,
  "signing_secret": null,
  "incomplete": []
}

{
  "error": {
    "code": "invalid_request",
    "message": "2 problems, first steps[0].input.country: Not an input of hts.usitc.gov/get_import_duty. It takes: hts_code.",
    "next_step": "Fix the request as the message says, then send it again.",
    "errors": [
      {
        "path": "steps[0].input.country",
        "message": "Not an input of hts.usitc.gov/get_import_duty. It takes: hts_code."
      },
      {
        "path": "steps[1].code",
        "message": "The code reads step \"send\", which has not run yet here: only steps before this one can be read."
      }
    ],
    "doc_url": "https://docs.fous.com/guides/errors#invalid_request",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}

List a workflow’s runs

The workflow’s runs, newest first, without their steps. Free.

Path parameters

idstringrequired

Query parameters

limitintegerdefault 20Optional
beforestringOptional
The id of the last run you read (wfr_…), or an ISO time: the page after it. Keep reading while has_more is true.

Returns

200The runs.

The answer has these fields:

runsarray of WorkflowRunrequired
has_morebooleanrequired
Whether older runs follow.

Errors

Status	Code	When
404	`not_found`	No such workflow

curl 'https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/runs' \
  -H "Authorization: Bearer $FOUS_API_KEY"

// Save as fous.mts, then run: npx tsx fous.mts
const response = await fetch('https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/runs', {
  headers: {
    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,
  },
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

import os
import requests

response = requests.get(
    "https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/runs",
    headers={
        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",
    },
    timeout=180,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

Sent with your key, kept for this tab only. Get an API key.

{
  "runs": [
    {
      "id": "wfr_01m72hcccgfzqsgbfn5w7q33sv",
      "workflow_id": "wf_01m72hccc2f47t2r9qry60m4cq",
      "status": "completed",
      "trigger": "manual",
      "input": {
        "hts_code": "6109.10.0012"
      },
      "error": null,
      "credits": 3,
      "created_at": "2026-11-10T10:52:08.464Z",
      "started_at": "2026-11-10T10:52:08.465Z",
      "finished_at": "2026-11-10T10:52:15.650Z",
      "resume_at": null
    }
  ],
  "has_more": false
}

{
  "error": {
    "code": "not_found",
    "message": "No such workflow.",
    "doc_url": "https://docs.fous.com/guides/errors#not_found",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}

Run a workflow

Starts a run by hand, enabled or not, with input for the trigger’s inputs (defaults filled in, numbers and booleans read from text). With wait (0 to 60 seconds, default 0) the answer is held until the run ends: 200 once it ended, else 202 while it goes on; read it with GET /v1/workflows/{id}/runs/{run_id}. Each method step is a run of its own, in GET /v1/runs too. A run costs 1 credit for each step that runs (methods, AI, transforms, emails and webhooks; steps inside For each once per item). The number shown before you run (cost) is the full run; a run a filter ends early costs less. Triggers, For each, filters and delays are free; failed steps cost nothing. A step whose failure can pass (the site or Fous failing for a moment, a rate limit) is tried again after 20 s, 2 min, 10 min and 30 min, 5 attempts in all; a method step whose method Fous is repairing waits for the repair. A step the organization cannot pay for fails with error.code insufficient_credits, and the run stops there.

Path parameters

idstringrequired

Request body

Optional, JSON.

inputobjectOptional
Values for the trigger’s inputs.
waitintegerdefault 0Optional

Returns

A WorkflowRun object.

200The run ended within wait.
202Queued or still going. The same WorkflowRun, with status "queued".

Errors

Status	Code	When
400	`invalid_request`	The body does not hold, or the input does not fit the trigger’s inputs
404	`not_found`	No such workflow
409	`conflict`	reason workflow_incomplete: a value is still to fill in (incomplete) or a step’s method still to build (steps), so the workflow cannot run or be turned on

curl 'https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/runs' \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "input": {
      "hts_code": "6109.10.0012"
    },
    "wait": 30
  }'

// Save as fous.mts, then run: npx tsx fous.mts
const response = await fetch('https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/runs', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    input: {
      hts_code: '6109.10.0012'
    },
    wait: 30
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

import os
import requests

response = requests.post(
    "https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/runs",
    headers={
        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",
    },
    json={
        "input": {
            "hts_code": "6109.10.0012"
        },
        "wait": 30
    },
    timeout=180,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

Sent with your key, kept for this tab only. A run uses credits like any call. Get an API key.

{
  "id": "wfr_01m72hcccgfzqsgbfn5w7q33sv",
  "workflow_id": "wf_01m72hccc2f47t2r9qry60m4cq",
  "status": "completed",
  "trigger": "manual",
  "input": {
    "hts_code": "6109.10.0012"
  },
  "error": null,
  "credits": 3,
  "output": {
    "sent": 1
  },
  "created_at": "2026-11-10T10:52:08.464Z",
  "started_at": "2026-11-10T10:52:08.465Z",
  "finished_at": "2026-11-10T10:52:15.650Z",
  "resume_at": null,
  "steps": [
    {
      "seq": 1,
      "key": "duty",
      "path": "duty",
      "type": "method",
      "name": "Look up the import duty",
      "status": "completed",
      "input": {
        "hts_code": "6109.10.0012"
      },
      "output": {
        "status": "completed",
        "data": {
          "release": "2026 HTS Revision 22",
          "hts_code": "6109.10.00.12",
          "description": "Men's (338)",
          "description_path": [
            "T-shirts, singlets, tank tops and similar garments, knitted or crocheted:",
            "Of cotton",
            "Men's or boys':",
            "Other T-shirts:",
            "Men's (338)"
          ],
          "general_rate": "16.5%",
          "special_rates": "Free (AU,BH,CL,CO,IL,JO,KR,MA,OM,P,PA,PE,S,SG)",
          "column_2_rate": "90%",
          "rate_source_code": "6109.10.00",
          "source_url": "https://hts.usitc.gov/search?query=6109100012",
          "units": [
            "doz.",
            "kg"
          ],
          "footnotes": [],
          "note": "Rates are those shown in the current HTS schedule; additional duties and eligibility conditions may apply."
        },
        "run_id": "run_01m72hcccpfjaatbegf499rgk8",
        "error": null
      },
      "error": null,
      "method_run_id": "run_01m72hcccpfjaatbegf499rgk8",
      "attempts": [],
      "waiting": null,
      "started_at": "2026-11-10T10:52:08.470Z",
      "finished_at": "2026-11-10T10:52:15.291Z"
    },
    {
      "seq": 2,
      "key": "note",
      "path": "note",
      "type": "transform",
      "name": "Write the rates as a note",
      "status": "completed",
      "input": null,
      "output": "HTS 6109.10.00.12 (2026 HTS Revision 22)\nGeneral rate: 16.5%\nSpecial rates: Free (AU,BH,CL,CO,IL,JO,KR,MA,OM,P,PA,PE,S,SG)\nColumn 2 rate: 90%\nhttps://hts.usitc.gov/search?query=6109100012",
      "error": null,
      "method_run_id": null,
      "attempts": [],
      "waiting": null,
      "started_at": "2026-11-10T10:52:15.293Z",
      "finished_at": "2026-11-10T10:52:15.307Z"
    },
    {
      "seq": 3,
      "key": "send",
      "path": "send",
      "type": "email",
      "name": "Email the note",
      "status": "completed",
      "input": {
        "to": [
          "ada@example.com"
        ],
        "subject": "Import duty for 6109.10.0012",
        "body": "HTS 6109.10.00.12 (2026 HTS Revision 22)\nGeneral rate: 16.5%\nSpecial rates: Free (AU,BH,CL,CO,IL,JO,KR,MA,OM,P,PA,PE,S,SG)\nColumn 2 rate: 90%\nhttps://hts.usitc.gov/search?query=6109100012"
      },
      "output": {
        "sent": 1
      },
      "error": null,
      "method_run_id": null,
      "attempts": [],
      "waiting": null,
      "started_at": "2026-11-10T10:52:15.310Z",
      "finished_at": "2026-11-10T10:52:15.648Z"
    }
  ]
}

{
  "id": "wfr_01m72hcccgfzqsgbfn5w7q33sv",
  "workflow_id": "wf_01m72hccc2f47t2r9qry60m4cq",
  "status": "queued",
  "trigger": "manual",
  "input": {
    "hts_code": "6109.10.0012"
  },
  "error": null,
  "credits": 0,
  "output": {
    "sent": 1
  },
  "created_at": "2026-11-10T10:52:08.464Z",
  "started_at": null,
  "finished_at": null,
  "resume_at": null,
  "steps": []
}

{
  "error": {
    "code": "invalid_request",
    "message": "body: Unrecognized key: \"hts_code\"",
    "errors": [
      {
        "path": "body",
        "message": "Unrecognized key: \"hts_code\""
      }
    ],
    "doc_url": "https://docs.fous.com/guides/errors#invalid_request",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}

Get a workflow run

The run with each step as it ran: its status, resolved input, output and error. A step that takes time (a method, a loop, a delay) shows running until it ends. With wait (0 to 60 seconds, default 0) the answer is held until the run ends. Free.

Path parameters

idstringrequired
run_idstringrequired

Query parameters

waitintegerdefault 0Optional
Seconds to hold the answer while it is still running, 0 to 60.

Returns

A WorkflowRun object.

200The run has ended.
202Still going (queued, running or waiting). The same WorkflowRun, with status "running".

Errors

Status	Code	When
400	`invalid_request`	wait is not a whole number from 0 to 60
404	`not_found`	No such workflow run

curl 'https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/runs/wfr_01m72hcccgfzqsgbfn5w7q33sv' \
  -H "Authorization: Bearer $FOUS_API_KEY"

// Save as fous.mts, then run: npx tsx fous.mts
const response = await fetch('https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/runs/wfr_01m72hcccgfzqsgbfn5w7q33sv', {
  headers: {
    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,
  },
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

import os
import requests

response = requests.get(
    "https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/runs/wfr_01m72hcccgfzqsgbfn5w7q33sv",
    headers={
        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",
    },
    timeout=180,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

Sent with your key, kept for this tab only. Get an API key.

{
  "id": "wfr_01m72hcccgfzqsgbfn5w7q33sv",
  "workflow_id": "wf_01m72hccc2f47t2r9qry60m4cq",
  "status": "completed",
  "trigger": "manual",
  "input": {
    "hts_code": "6109.10.0012"
  },
  "error": null,
  "credits": 3,
  "output": {
    "sent": 1
  },
  "created_at": "2026-11-10T10:52:08.464Z",
  "started_at": "2026-11-10T10:52:08.465Z",
  "finished_at": "2026-11-10T10:52:15.650Z",
  "resume_at": null,
  "steps": [
    {
      "seq": 1,
      "key": "duty",
      "path": "duty",
      "type": "method",
      "name": "Look up the import duty",
      "status": "completed",
      "input": {
        "hts_code": "6109.10.0012"
      },
      "output": {
        "status": "completed",
        "data": {
          "release": "2026 HTS Revision 22",
          "hts_code": "6109.10.00.12",
          "description": "Men's (338)",
          "description_path": [
            "T-shirts, singlets, tank tops and similar garments, knitted or crocheted:",
            "Of cotton",
            "Men's or boys':",
            "Other T-shirts:",
            "Men's (338)"
          ],
          "general_rate": "16.5%",
          "special_rates": "Free (AU,BH,CL,CO,IL,JO,KR,MA,OM,P,PA,PE,S,SG)",
          "column_2_rate": "90%",
          "rate_source_code": "6109.10.00",
          "source_url": "https://hts.usitc.gov/search?query=6109100012",
          "units": [
            "doz.",
            "kg"
          ],
          "footnotes": [],
          "note": "Rates are those shown in the current HTS schedule; additional duties and eligibility conditions may apply."
        },
        "run_id": "run_01m72hcccpfjaatbegf499rgk8",
        "error": null
      },
      "error": null,
      "method_run_id": "run_01m72hcccpfjaatbegf499rgk8",
      "attempts": [],
      "waiting": null,
      "started_at": "2026-11-10T10:52:08.470Z",
      "finished_at": "2026-11-10T10:52:15.291Z"
    },
    {
      "seq": 2,
      "key": "note",
      "path": "note",
      "type": "transform",
      "name": "Write the rates as a note",
      "status": "completed",
      "input": null,
      "output": "HTS 6109.10.00.12 (2026 HTS Revision 22)\nGeneral rate: 16.5%\nSpecial rates: Free (AU,BH,CL,CO,IL,JO,KR,MA,OM,P,PA,PE,S,SG)\nColumn 2 rate: 90%\nhttps://hts.usitc.gov/search?query=6109100012",
      "error": null,
      "method_run_id": null,
      "attempts": [],
      "waiting": null,
      "started_at": "2026-11-10T10:52:15.293Z",
      "finished_at": "2026-11-10T10:52:15.307Z"
    },
    {
      "seq": 3,
      "key": "send",
      "path": "send",
      "type": "email",
      "name": "Email the note",
      "status": "completed",
      "input": {
        "to": [
          "ada@example.com"
        ],
        "subject": "Import duty for 6109.10.0012",
        "body": "HTS 6109.10.00.12 (2026 HTS Revision 22)\nGeneral rate: 16.5%\nSpecial rates: Free (AU,BH,CL,CO,IL,JO,KR,MA,OM,P,PA,PE,S,SG)\nColumn 2 rate: 90%\nhttps://hts.usitc.gov/search?query=6109100012"
      },
      "output": {
        "sent": 1
      },
      "error": null,
      "method_run_id": null,
      "attempts": [],
      "waiting": null,
      "started_at": "2026-11-10T10:52:15.310Z",
      "finished_at": "2026-11-10T10:52:15.648Z"
    }
  ]
}

{
  "id": "wfr_01m72hcccgfzqsgbfn5w7q33sv",
  "workflow_id": "wf_01m72hccc2f47t2r9qry60m4cq",
  "status": "running",
  "trigger": "manual",
  "input": {
    "hts_code": "6109.10.0012"
  },
  "error": null,
  "credits": 2,
  "output": null,
  "created_at": "2026-11-10T10:52:08.464Z",
  "started_at": "2026-11-10T10:52:08.465Z",
  "finished_at": null,
  "resume_at": null,
  "steps": [
    {
      "seq": 1,
      "key": "duty",
      "path": "duty",
      "type": "method",
      "name": "Look up the import duty",
      "status": "completed",
      "input": {
        "hts_code": "6109.10.0012"
      },
      "output": {
        "status": "completed",
        "data": {
          "release": "2026 HTS Revision 22",
          "hts_code": "6109.10.00.12",
          "description": "Men's (338)",
          "description_path": [
            "T-shirts, singlets, tank tops and similar garments, knitted or crocheted:",
            "Of cotton",
            "Men's or boys':",
            "Other T-shirts:",
            "Men's (338)"
          ],
          "general_rate": "16.5%",
          "special_rates": "Free (AU,BH,CL,CO,IL,JO,KR,MA,OM,P,PA,PE,S,SG)",
          "column_2_rate": "90%",
          "rate_source_code": "6109.10.00",
          "source_url": "https://hts.usitc.gov/search?query=6109100012",
          "units": [
            "doz.",
            "kg"
          ],
          "footnotes": [],
          "note": "Rates are those shown in the current HTS schedule; additional duties and eligibility conditions may apply."
        },
        "run_id": "run_01m72hcccpfjaatbegf499rgk8",
        "error": null
      },
      "error": null,
      "method_run_id": "run_01m72hcccpfjaatbegf499rgk8",
      "attempts": [],
      "waiting": null,
      "started_at": "2026-11-10T10:52:08.470Z",
      "finished_at": "2026-11-10T10:52:15.291Z"
    },
    {
      "seq": 2,
      "key": "note",
      "path": "note",
      "type": "transform",
      "name": "Write the rates as a note",
      "status": "completed",
      "input": null,
      "output": "HTS 6109.10.00.12 (2026 HTS Revision 22)\nGeneral rate: 16.5%\nSpecial rates: Free (AU,BH,CL,CO,IL,JO,KR,MA,OM,P,PA,PE,S,SG)\nColumn 2 rate: 90%\nhttps://hts.usitc.gov/search?query=6109100012",
      "error": null,
      "method_run_id": null,
      "attempts": [],
      "waiting": null,
      "started_at": "2026-11-10T10:52:15.293Z",
      "finished_at": "2026-11-10T10:52:15.307Z"
    },
    {
      "seq": 3,
      "key": "send",
      "path": "send",
      "type": "email",
      "name": "Email the note",
      "status": "running",
      "input": {
        "to": [
          "ada@example.com"
        ],
        "subject": "Import duty for 6109.10.0012",
        "body": "HTS 6109.10.00.12 (2026 HTS Revision 22)\nGeneral rate: 16.5%\nSpecial rates: Free (AU,BH,CL,CO,IL,JO,KR,MA,OM,P,PA,PE,S,SG)\nColumn 2 rate: 90%\nhttps://hts.usitc.gov/search?query=6109100012"
      },
      "output": null,
      "error": null,
      "method_run_id": null,
      "attempts": [],
      "waiting": null,
      "started_at": "2026-11-10T10:52:15.310Z",
      "finished_at": null
    }
  ]
}

{
  "error": {
    "code": "invalid_request",
    "message": "wait is a whole number of seconds from 0 to 60.",
    "doc_url": "https://docs.fous.com/guides/errors#invalid_request",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}

Cancel a workflow run

Cancels a run that is queued, running or waiting: it does not go on, and a method run its step had going is stopped and free. The steps already finished stay charged (credits on the answer).

Path parameters

idstringrequired
run_idstringrequired

Returns

A WorkflowRun object.

200Canceled.

Errors

Status	Code	When
404	`not_found`	No such workflow run
409	`conflict`	Already ended

curl 'https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/runs/wfr_01m72hcccgfzqsgbfn5w7q33sv/cancel' \
  -X POST \
  -H "Authorization: Bearer $FOUS_API_KEY"

// Save as fous.mts, then run: npx tsx fous.mts
const response = await fetch('https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/runs/wfr_01m72hcccgfzqsgbfn5w7q33sv/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,
  },
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

import os
import requests

response = requests.post(
    "https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/runs/wfr_01m72hcccgfzqsgbfn5w7q33sv/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",
    },
    timeout=180,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

Sent with your key, kept for this tab only. Get an API key.

{
  "id": "wfr_01m72hcccgfzqsgbfn5w7q33sv",
  "workflow_id": "wf_01m72hccc2f47t2r9qry60m4cq",
  "status": "canceled",
  "trigger": "manual",
  "input": {
    "hts_code": "6109.10.0012"
  },
  "error": {
    "code": "canceled",
    "message": "The run was canceled."
  },
  "credits": 3,
  "output": {
    "sent": 1
  },
  "created_at": "2026-11-10T10:52:08.464Z",
  "started_at": "2026-11-10T10:52:08.465Z",
  "finished_at": "2026-11-10T10:52:15.650Z",
  "resume_at": null,
  "steps": []
}

{
  "error": {
    "code": "not_found",
    "message": "No such workflow run.",
    "doc_url": "https://docs.fous.com/guides/errors#not_found",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}

Renew a webhook address

Gives a webhook workflow a new address; the old one stops working at once. A webhook workflow gets its first address when it is saved.

Path parameters

idstringrequired

Returns

200The new address.

The answer has these fields:

webhook_urlstringrequired

Errors

Status	Code	When
404	`not_found`	No such workflow
409	`conflict`	Not a webhook workflow

curl 'https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/webhook' \
  -X POST \
  -H "Authorization: Bearer $FOUS_API_KEY"

// Save as fous.mts, then run: npx tsx fous.mts
const response = await fetch('https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/webhook', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,
  },
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

import os
import requests

response = requests.post(
    "https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/webhook",
    headers={
        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",
    },
    timeout=180,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

Sent with your key, kept for this tab only. Get an API key.

{
  "webhook_url": "https://api.fous.com/v1/hooks/whk_3q9ZxK0cLm2vT8yR5nB1wJ7dF4hG6sPa"
}

{
  "error": {
    "code": "not_found",
    "message": "No such workflow.",
    "doc_url": "https://docs.fous.com/guides/errors#not_found",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}

Renew the signing secret

Gives the workflow a new secret for signing its webhook steps’ calls (X-Fous-Signature); the old one stops signing at once.

Path parameters

idstringrequired

Returns

200The new secret.

The answer has these fields:

signing_secretstringrequired

Errors

Status	Code	When
404	`not_found`	No such workflow

curl 'https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/signing-secret' \
  -X POST \
  -H "Authorization: Bearer $FOUS_API_KEY"

// Save as fous.mts, then run: npx tsx fous.mts
const response = await fetch('https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/signing-secret', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FOUS_API_KEY}`,
  },
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

import os
import requests

response = requests.post(
    "https://api.fous.com/v1/workflows/wf_01m72hccc2f47t2r9qry60m4cq/signing-secret",
    headers={
        "Authorization": f"Bearer {os.environ['FOUS_API_KEY']}",
    },
    timeout=180,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

Sent with your key, kept for this tab only. Get an API key.

{
  "signing_secret": "whsec_3q9ZxK0cLm2vT8yR5nB1wJ7dF4hG6sPa"
}

{
  "error": {
    "code": "not_found",
    "message": "No such workflow.",
    "doc_url": "https://docs.fous.com/guides/errors#not_found",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}

Start a run from a webhook

A webhook workflow’s address (webhook_url): another service POSTs JSON here and its fields are the run’s input, checked against the trigger’s inputs. No API key: the address is the secret. The workflow must be enabled. At most 60 calls a minute per workflow, and 100 of its runs waiting to start. With an Idempotency-Key header (or a sender’s delivery id: webhook-id, svix-id, X-GitHub-Delivery, X-Shopify-Webhook-Id), a call that repeats one within 24 hours answers the run the first started (repeated: true) instead of starting another.

No key needed.

Path parameters

tokenstringrequired

Headers

Idempotency-Keystring
The sender’s own id for the call, up to 255 characters. Without it, a sender’s delivery id is used the same way: webhook-id (Standard Webhooks), svix-id, X-GitHub-Delivery or X-Shopify-Webhook-Id.

Request body

Optional, JSON.

Returns

202Queued.

The answer has these fields:

run_idstringrequired
workflow_idstringrequired
repeatedboolean
The Idempotency-Key was sent within 24 hours: its run.

Errors

Status	Code	When
400	`invalid_request`	The body does not fit the trigger’s inputs
403	`plan_limit`	Schedules and webhooks come with a paid plan (limit.kind api)
404	`not_found`	No workflow at this address
409	`conflict`	The workflow is turned off
429	`rate_limited`	Too many calls this minute, or 100 runs waiting to start

curl 'https://api.fous.com/v1/hooks/whk_3q9ZxK0cLm2vT8yR5nB1wJ7dF4hG6sPa' \
  -H "Idempotency-Key: $FOUS_IDEMPOTENCY_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "order_id": 1042,
    "customer": {
      "name": "Ada"
    }
  }'

// Save as fous.mts, then run: npx tsx fous.mts
const response = await fetch('https://api.fous.com/v1/hooks/whk_3q9ZxK0cLm2vT8yR5nB1wJ7dF4hG6sPa', {
  method: 'POST',
  headers: {
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    order_id: 1042,
    customer: {
      name: 'Ada'
    }
  }),
});
const result = await response.json();
if (!response.ok) throw new Error(`${result.error.code}: ${result.error.message}`);
console.log(result);

import requests
import uuid

response = requests.post(
    "https://api.fous.com/v1/hooks/whk_3q9ZxK0cLm2vT8yR5nB1wJ7dF4hG6sPa",
    headers={
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "order_id": 1042,
        "customer": {
            "name": "Ada"
        }
    },
    timeout=180,
)
result = response.json()
if not response.ok:
    raise RuntimeError(f"{result['error']['code']}: {result['error']['message']}")
print(result)

A run uses credits like any call.

{
  "run_id": "wfr_01m72hcccgfzqsgbfn5w7q33sv",
  "workflow_id": "wf_01m72hccc2f47t2r9qry60m4cq"
}

{
  "error": {
    "code": "invalid_request",
    "message": "input.order_id: Required.",
    "errors": [
      {
        "path": "input.order_id",
        "message": "Required."
      }
    ],
    "doc_url": "https://docs.fous.com/guides/errors#invalid_request",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}