Workflows

A workflow is an automated process made of steps: a trigger starts a run, and the steps after it call tools, run assistants, branch, loop, send HTTP requests, wait for a person's approval and set the result. The workflow API lets your application list workflows, run them with live progress, read past runs, decide approvals, edit and publish workflows, and start published workflows from a public webhook URL.

Every call runs as the user who owns the API key, with that user's permissions, organizations and credits. Runs started through the API execute the workflow draft (the current definition); published versions are run by schedules, webhooks and booster record triggers.

Scopes and access #

The scopes do not include each other: a key that both reads and edits workflows needs both. A key without the required scope gets 401 with API key is invalid; see authentication.

On top of the scope, each workflow checks who may do what:

A workflow that belongs to an organization runs in that organization (its credits and storage), so the user must be a member with write access there.

Concepts #

Definition #

The definition of a workflow is a directed acyclic graph: a list of nodes and a list of edges.

{
  "nodes": [
    {
      "id": "start",
      "type": "trigger.manual",
      "name": "Start",
      "params": {
        "input_schema": {
          "type": "object",
          "properties": {"customer": {"type": "string"}, "question": {"type": "string"}},
          "required": ["question"]
        }
      },
      "position": {"x": 0, "y": 0}
    },
    {
      "id": "answer",
      "type": "assistant.run",
      "name": "Draft an answer",
      "params": {
        "assistant_id": "3f6c1a2e-8b4d-4e7a-9c1f-2d5e6a7b8c90",
        "prompt": "Answer {{ input.customer }}: {{ input.question }}"
      },
      "position": {"x": 0, "y": 160}
    },
    {
      "id": "result",
      "type": "output",
      "name": "Result",
      "params": {"value": {"answer": "{{ steps.answer.output.text }}"}},
      "position": {"x": 0, "y": 320}
    }
  ],
  "edges": [
    {"source": "start", "target": "answer", "source_handle": null},
    {"source": "answer", "target": "result", "source_handle": null}
  ]
}

A definition has at most 200 nodes, at least one trigger, no cycles and no edges into a trigger. Use validate to check it.

String parameters are templates (Jinja syntax, evaluated in a sandbox). They can read:

A parameter that is a single {{ expression }} keeps the native type of the value (an object stays an object); an undefined variable is an error of the step.

Node types #

The full list, with the JSON schema of every node's parameters and the tools a tool.call step can use, comes from the catalog. An overview:

Draft and published version #

The definition stored on the workflow is the draft. Every change of it is kept as a revision. Runs started through the API (and from the app) run the draft.

Publishing copies the draft into a new immutable version (1, 2, ...) and activates the workflow. While the workflow is active, its automatic triggers (schedule, webhook, booster record) start runs of the published version, as the user who published or last activated it (run_as). Editing the draft afterwards does not change what the triggers run until you publish again.

Run statuses #

A run records the input, the state of every step and the result. Its status:

Steps run as soon as all steps before them are done, so independent branches run in parallel. A step whose incoming edges are all inactive (an untaken branch) is skipped. A failed step with an error edge continues there; without one, the run fails (steps already running finish first).

Runs are deleted after a retention period (90 days by default) together with the conversations and files their steps created. Paused runs are kept until they end.

Approval flow #

A human.approval step opens an approval and pauses the run. The people who may decide it are the user the run goes as and members of the workflow's organization named in the step; they are notified in the app and by e-mail. An approval shows a title, a message and optionally a form (a flat JSON schema with prefilled values). The decision (approve with the form data, or reject) becomes the output of the step and the run continues on approved or rejected. An approval nobody decides in time expires: the run continues on timeout when that output is connected, otherwise the step fails. See approvals.

Files in run input #

A field of the manual trigger's input_schema declared as {"type": "object", "format": "file"} holds one file. Send it in the run input either inline as base64:

{
  "invoice": {
    "filename": "invoice-1042.pdf",
    "mime_type": "application/pdf",
    "data": "data:application/pdf;base64,JVBERi0xLjcKJcfsj6IKNSAwIG9iago8PC9MZW5ndGg..."
  }
}

or as the id of a file the user already has ("invoice": "7b1e2c3d-..." or {"file_id": "7b1e2c3d-..."}). data is plain base64 or a data URL; name may be used instead of filename and content_type instead of mime_type. The upload size limit and the storage quota apply.

In the run, the value becomes the file's attachment metadata, which is also how steps return files:

{
  "file_id": "7b1e2c3d-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "filename": "invoice-1042.pdf",
  "content_type": "application/pdf",
  "file_url": "https://ayeto.ai/api/v1/public/file/read?id=7b1e2c3d-4a5b-4c6d-8e7f-9a0b1c2d3e4f&secret=...",
  "size": 48213
}

file_url downloads the file. Files sent as base64 belong to the run and are deleted with it; a file named by its id stays the user's and is not deleted with the run. The same base64 form is accepted in the file fields of an approval form and inside webhook bodies.

Limits #

The defaults below can differ per deployment.

Workflow object #

The workflow returned by the read, create and update endpoints. It also has the common fields (id, created, updated, permissions, ...).

List and read workflows #

find returns the workflows the user owns or that are shared with them, as an array of workflows, newest first unless sorted otherwise. count returns the number of matching workflows as an integer. Both take the usual query body (filters, sort_key, sort_order, limit_from, limit_to); send {} for everything. Each workflow comes with its full definition, so page through large lists.

get returns one workflow; the id is a query parameter and the body is empty.

Useful filters: ["organization_id", "==", "<organization id>"], ["organization_id", "==", null] (personal), ["active", "==", true], ["name", "regex", "invoice"].

curl -X POST "https://ayeto.ai/api/v3/workflow/find" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": [["active", "==", true]], "sort_key": "updated.timestamp", "sort_order": 1, "limit_from": 0, "limit_to": 20}'

curl -X POST "https://ayeto.ai/api/v3/workflow/get?entity_id=5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a" \
  -H "uni-api-key: $AYETO_API_KEY"

{
  "id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
  "name": "Customer question",
  "description": "Drafts an answer to a customer question",
  "organization_id": null,
  "definition": {"nodes": ["..."], "edges": ["..."]},
  "sharing": [],
  "group_sharing": [],
  "last_run": {"run_id": "c2a1b0d9-8e7f-4a6b-9c5d-4e3f2a1b0c9d", "status": "success", "finished_at": 1759401234567, "credits": 0.42},
  "published_version": 3,
  "published_at": 1759300000000,
  "active": true,
  "run_as": "0f1e2d3c-4b5a-4968-8776-655443322110",
  "created": {"timestamp": 1759000000000, "user_id": "0f1e2d3c-4b5a-4968-8776-655443322110"},
  "updated": {"timestamp": 1759400000000, "user_id": "0f1e2d3c-4b5a-4968-8776-655443322110"}
}

A workflow that does not exist or is not visible to the user returns 404.

Create a workflow #

Returns the created workflow. The definition is stored as given, even when it is not valid; validate it before running. Creating a workflow also records its first revision and creates the user's builder assistant.

curl -X POST "https://ayeto.ai/api/v3/workflow/create" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Customer question", "description": "Drafts an answer to a customer question"}'

Update a workflow #

Only the fields you send change. The organization, publishing state and last run cannot be changed here. Every change of the definition is recorded as a revision; the published version stays as it was until you publish again. Returns the updated workflow.

To change one node, read the workflow, modify its definition and send it back. Two clients updating the same workflow at once overwrite each other's definition.

Delete a workflow #

Deletes the workflow with all its runs (and the conversations and files they created), its revisions, published versions, triggers and builder assistants. Returns the deleted id as a JSON string.

Catalog #

Returns what workflows can be built from: every node type with the JSON schema of its parameters, and the tools a tool.call step can call. No request body.

Validate a workflow #

Validates the draft as the calling user (including whether the user can use the assistants and booster panels it refers to).

{
  "valid": false,
  "issues": [
    {"severity": "error", "message": "Node 'answer' has no output 'true' (outputs: default, error)", "node_id": "answer", "edge": {"source": "answer", "target": "result", "source_handle": "true"}},
    {"severity": "warning", "message": "Node 'draft' is not reachable from any trigger and never runs", "node_id": "draft", "edge": null}
  ]
}

valid is false when there is at least one issue with severity error; errors block runs and publishing, warnings do not.

Run a workflow #

Runs the draft as the calling user and answers when the run has finished or paused.

Request #

Starting from a schedule, webhook or booster record trigger runs the draft by hand, which is useful for testing: pass the input the trigger would produce, e.g. {"body": {...}, "query": {}, "headers": {}} for a webhook trigger.

The user needs run access to the workflow (see scopes and access). Before the run starts, the draft is validated; an invalid draft is rejected with 422. A missing required input key does not reject the request: the run is created and fails at its trigger step (Missing input: <keys>).

The request returns when the run ends, which may take minutes (up to the run time limit). For long runs or live progress, use streaming. When a step waits for an approval, the response comes back with status: "waiting"; follow the run with get run.

Response #

200 OK with the run.

Examples #

curl -X POST "https://ayeto.ai/api/v3/workflow/run" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
    "input": {"customer": "Jana Novak", "question": "When will order 1042 be delivered?"}
  }'

import json
import os
import requests

response = requests.post(
    "https://ayeto.ai/api/v3/workflow/run",
    headers={"uni-api-key": os.environ["AYETO_API_KEY"]},
    json={
        "workflow_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
        "input": {"customer": "Jana Novak", "question": "When will order 1042 be delivered?"},
    },
    timeout=1900,
)
response.raise_for_status()
run = response.json()
if run["status"] == "success":
    print(json.loads(run["output_json"]) if run["output_json"] else None)
else:
    print(run["status"], run["error"])

const response = await fetch("https://ayeto.ai/api/v3/workflow/run", {
  method: "POST",
  headers: {
    "uni-api-key": process.env.AYETO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    workflow_id: "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
    input: { customer: "Jana Novak", question: "When will order 1042 be delivered?" },
  }),
});
if (!response.ok) throw new Error((await response.json()).detail);
const run = await response.json();
const output = run.output_json ? JSON.parse(run.output_json) : null;
console.log(run.status, output ?? run.error);

Run object #

A run has the common fields plus:

created.user_id is the user the run went as.

Step object #

Example:

{
  "id": "c2a1b0d9-8e7f-4a6b-9c5d-4e3f2a1b0c9d",
  "workflow_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
  "organization_id": null,
  "version": null,
  "trigger_node_id": "start",
  "trigger_type": "trigger.manual",
  "trigger_depth": 0,
  "automatic": false,
  "input_json": "{\"customer\": \"Jana Novak\", \"question\": \"When will order 1042 be delivered?\"}",
  "status": "success",
  "started_at": 1759401220011,
  "active_since": 1759401220011,
  "finished_at": 1759401234567,
  "steps": [
    {
      "node_id": "start", "node_type": "trigger.manual", "status": "success",
      "started_at": 1759401220020, "finished_at": 1759401220031, "handle": null,
      "output_json": "{\"customer\": \"Jana Novak\", \"question\": \"When will order 1042 be delivered?\"}",
      "output_truncated": false, "text": "", "error": "", "file_ids": [], "conversation_id": null, "iteration": []
    },
    {
      "node_id": "answer", "node_type": "assistant.run", "status": "success",
      "started_at": 1759401220040, "finished_at": 1759401234400, "handle": null,
      "output_json": "{\"text\": \"Dear Jana, order 1042 ships on Friday ...\", \"data\": null, \"files\": []}",
      "output_truncated": false, "text": "Dear Jana, order 1042 ships on Friday ...", "error": "",
      "file_ids": [], "conversation_id": "8e2f4a6c-1b3d-4e5f-8a7b-9c0d1e2f3a4b", "iteration": []
    },
    {
      "node_id": "result", "node_type": "output", "status": "success",
      "started_at": 1759401234410, "finished_at": 1759401234420, "handle": null,
      "output_json": "{\"answer\": \"Dear Jana, order 1042 ships on Friday ...\"}",
      "output_truncated": false, "text": "", "error": "", "file_ids": [], "conversation_id": null, "iteration": []
    }
  ],
  "output_json": "{\"answer\": \"Dear Jana, order 1042 ships on Friday ...\"}",
  "error": "",
  "credits": 0.42,
  "created": {"timestamp": 1759401220000, "user_id": "0f1e2d3c-4b5a-4968-8776-655443322110"}
}

Stream a run #

Same request as run a workflow, but the response streams the events of the run as they happen. The run executes on the server to its end even when the client disconnects; read the result afterwards with get run.

Access and validation errors (no access, invalid draft, input too large) are returned as a normal HTTP error before the stream starts.

Wire format #

The response (Content-Type: text/event-stream) is a sequence of JSON objects written one after another without separators (not SSE data: lines); see streaming. Each object is a chunk:

{"timestamp": 1759401220012, "data": {"type": "run_start", "run_id": "c2a1b0d9-8e7f-4a6b-9c5d-4e3f2a1b0c9d", "node_id": null, "node_type": null, "status": "running", "handle": null, "text": "", "error": "", "output_json": "", "iteration": []}, "error": null}

• data is a run event (below).
• data: "" is a keep-alive chunk, sent about every second while nothing happens. Ignore it.
• A chunk with error set ({"status", "text", "detail"}) reports an error that ended the stream.

Events #

Every event has the fields type, run_id, node_id, node_type, status, handle, text, error, output_json and iteration; which of them carry a value depends on the type.

Events of parallel branches and loop items interleave; use node_id and iteration to tell them apart.

Examples #

curl -N -X POST "https://ayeto.ai/api/v3/workflow/run/stream" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a", "input": {"question": "When will order 1042 be delivered?"}}'

Python, splitting the stream into JSON objects with raw_decode:

import json
import os
import requests

decoder = json.JSONDecoder()

def events(response):
    """Yield the run events of a streamed response."""
    buffer = ""
    for piece in response.iter_content(chunk_size=None, decode_unicode=True):
        buffer += piece
        while True:
            buffer = buffer.lstrip()
            if not buffer:
                break
            try:
                chunk, end = decoder.raw_decode(buffer)
            except json.JSONDecodeError:
                break  # incomplete object, wait for more data
            buffer = buffer[end:]
            if chunk.get("error"):
                raise RuntimeError(chunk["error"]["detail"])
            if chunk.get("data"):
                yield chunk["data"]

with requests.post(
    "https://ayeto.ai/api/v3/workflow/run/stream",
    headers={"uni-api-key": os.environ["AYETO_API_KEY"]},
    json={"workflow_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a", "input": {"question": "When will order 1042 be delivered?"}},
    stream=True,
    timeout=(10, 120),
) as response:
    response.raise_for_status()
    response.encoding = "utf-8"
    for event in events(response):
        if event["type"] == "step_end":
            print(f"{event['node_id']}: {event['status']} {event['error']}")
        elif event["type"] == "run_waiting":
            print("paused, waiting for:", event["text"])
        elif event["type"] == "run_end":
            print("run", event["status"], event["output_json"] or event["error"])

JavaScript, splitting the stream by tracking braces outside strings:

async function* runEvents(response) {
  const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
  let buffer = "";
  while (true) {
    const { value, done } = await reader.read();
    if (done) return;
    buffer += value;
    let depth = 0, inString = false, escaped = false, start = -1, consumed = 0;
    for (let i = 0; i < buffer.length; i++) {
      const c = buffer[i];
      if (inString) {
        if (escaped) escaped = false;
        else if (c === "\\") escaped = true;
        else if (c === '"') inString = false;
      } else if (c === '"') inString = true;
      else if (c === "{") { if (depth++ === 0) start = i; }
      else if (c === "}" && --depth === 0) {
        const chunk = JSON.parse(buffer.slice(start, i + 1));
        consumed = i + 1;
        if (chunk.error) throw new Error(chunk.error.detail);
        if (chunk.data) yield chunk.data;
      }
    }
    buffer = buffer.slice(consumed);
  }
}

const response = await fetch("https://ayeto.ai/api/v3/workflow/run/stream", {
  method: "POST",
  headers: { "uni-api-key": process.env.AYETO_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    workflow_id: "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
    input: { question: "When will order 1042 be delivered?" },
  }),
});
if (!response.ok) throw new Error((await response.json()).detail);
for await (const event of runEvents(response)) {
  if (event.type === "step_start") console.log("running", event.node_id);
  if (event.type === "step_end") console.log(event.node_id, event.status, event.error);
  if (event.type === "run_waiting") console.log("paused, waiting for", event.text);
  if (event.type === "run_end") console.log("done", event.status, event.output_json || event.error);
}

Cancel a run #

Cancels a run that is waiting or queued. Its waiting steps fail and their pending approvals are cancelled. The user the run went as and users with write access to the workflow may cancel it. A run that is running cannot be cancelled (422); it ends on its own or at the run time limit. Returns the cancelled run.

Runs #

These endpoints see the runs that went as the API key's user: runs the user started, and automatic runs of workflows the user published or activated. Runs of other users are reported as not found.

find returns an array of runs and count an integer; both take the query body. Runs include all their steps and outputs, so always page. get returns one run (empty body). delete deletes a run with the conversations and files its steps created and its approvals, and returns its id; deleting a paused run ends it.

Useful filters:

curl -X POST "https://ayeto.ai/api/v3/workflow/runs/find" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": [["workflow_id", "==", "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a"]], "sort_key": "created.timestamp", "sort_order": 1, "limit_from": 0, "limit_to": 10}'

To follow a paused or queued run, poll get until its status is success, failed or cancelled.

Approvals #

The approval endpoints serve the people who decide: any user named by an approval step can use them, without other permissions on the workflow. The API key still needs the ayeto.workflow scope.

Approval object #

Common fields plus:

List approvals #

Request:

Returns {"items": [<approval>, ...], "total": <number>} with the approvals the user may decide (or decided), newest first. total is the number of all matching approvals.

Count pending approvals #

No request body. Returns {"pending": 3}, the number of approvals waiting for the user's decision. Suited for polling a badge.

Get an approval #

Returns the approval. Users who may decide it and users who can read its workflow may get it.

Decide an approval #

Only users in assignee_user_ids may decide, and only while the approval is pending and before expires_at. The form data is validated against form_schema. The decision becomes the output of the approval step:

{
  "decision": "approved",
  "data": {"amount": 1200, "note": "OK for this quarter"},
  "comment": "Approved",
  "decided_by": {"id": "0f1e2d3c-4b5a-4968-8776-655443322110", "email": "jana@example.com", "name": "Jana Novak"},
  "decided_at": 1759405000000,
  "approval_id": "e4d3c2b1-a0f9-4e8d-9c7b-6a5f4e3d2c1b"
}

The run continues in the background as the user it went as (not as the decider); its status changes from waiting to queued and then running. Returns the decided approval.

curl -X POST "https://ayeto.ai/api/v3/workflow/approval/decide" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "approval_id": "e4d3c2b1-a0f9-4e8d-9c7b-6a5f4e3d2c1b",
    "decision": "approve",
    "data": {"amount": 1200, "note": "OK for this quarter"},
    "comment": "Approved"
  }'

Publishing and triggers #

These endpoints need write access to the workflow.

Deployment info #

Returns the publishing state. It contains the webhook URLs with their secrets, which is why it needs the write scope.

Trigger fields:

A signed http.request sends the header X-Ayeto-Signature: sha256=<hex HMAC-SHA256 of the request body> computed with signing_secret, so the receiving service can verify it.

Publish a workflow #

Validates the draft as the caller, stores it as the next version, activates the workflow and makes the caller the run_as user of automatic runs. Webhook URLs of trigger nodes that existed before stay the same. Returns the deployment info. An invalid draft is rejected with 422.

Activate or deactivate #

Activating validates the published version for the caller and makes the caller the run_as user. While inactive, webhook calls return 404 and schedules do not fire. Returns the deployment info. Fails with 422 when nothing is published.

Regenerate a webhook secret #

Gives the webhook a new secret; the old URL stops working at once. Returns the deployment info with the new URL.

Preview a schedule #

Checks a schedule for a trigger.schedule node and lists its next times:

{"valid": true, "error": "", "next_runs": [1759471200000, 1759730400000, 1759816800000, 1759903200000, 1759989600000]}

An invalid schedule returns 200 with valid: false and the reason in error (wrong number of fields, unknown time zone, runs more often than the shortest allowed interval).

Builder assistant #

Every user with write access has their own builder assistant for a workflow: an assistant that reads, edits, test-runs and explains the workflow in conversation. This endpoint returns the caller's builder (creating it when missing) as an assistant. Talk to it through chat with its id as the assistant; that needs a key with the chat scope. Its edits are recorded as revisions with origin builder.

Revisions #

Every change of the definition is a revision. Changes that only move nodes, made by the same user within three minutes, are merged into the latest revision. The newest revisions are kept (100 by default).

List revisions #

Returns up to 100 revisions, newest first, without their definitions:

Get a revision #

Returns the revision with its full definition: the common fields plus workflow_id, definition, origin, changes and restored_from.

Restore a revision #

Same request as get a revision. Puts the revision's definition back as the draft; the restore is recorded as a new revision (origin restore), so it can be undone. The published version does not change. Returns the updated workflow.

Export and import #

An export is a JSON document with the draft definition, name and description. Runs, revisions, published versions, trigger state (webhook secrets), the signing secret, the organization and sharing are not exported. Assistants that steps refer to are exported as ids only.

Export a workflow #

Through an API key, the values of http.request step headers whose name looks like a credential (contains auth, token, secret, key, password, cookie, signature or session) are always emptied; the header names stay. The emptied paths are listed in secret_keys. The user needs write access, or a read share with the workflow.export permission.

{
  "version": "1.0",
  "exported_at": 1759405000000,
  "workflow": {
    "name": "Customer question",
    "description": "Drafts an answer to a customer question",
    "definition": {"nodes": ["..."], "edges": ["..."]},
    "from_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
    "secret_keys": ["notify_crm.headers.Authorization"]
  }
}

Import a workflow #

Creates a new, unpublished workflow of the caller and validates it. Steps that refer to things the caller cannot use (an assistant from another account, emptied credentials) do not block the import; they are reported so they can be fixed.

The export format must have the same major version (1), and the definition at most 200 nodes.

Copy a workflow #

Exports the draft and imports it as a new workflow of the caller in one call; the response is the same as for import. The user needs write access or a read share with the workflow.copy permission. A user with write access to the original keeps the credentials of HTTP steps; a copy made through the workflow.copy permission leaves them out.

Webhooks #

A trigger.webhook node of a published, active workflow has a public URL. Get it from triggers[].url of the deployment info:

https://ayeto.ai/api/v3/workflow/hook/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/Xq3v...secret...

Treat the URL as a secret; anyone who has it can start runs that spend the credits of the run_as user. If it leaks, regenerate it.

Request #

Send a POST with a JSON body and Content-Type: application/json. A body of another content type is passed on as text (or parsed, when it is JSON). No API key is needed.

The run input (the output of the trigger, available to steps as {{ input }}) is:

Steps read it as {{ input.body.order_id }}, {{ input.query.source }} and so on. The input is limited to 200,000 characters of JSON.

Files in the body #

Files can be sent inside the body, at any depth (up to 32 levels):

• an object with base64 data and a name or filename, and no keys other than name, filename, content_type, mime_type, data, size;
• a data URL string data:<type>;base64,....

Each file is stored as a file of the run (owned by the run_as user, subject to the upload size limit and storage quota) and replaced in the body by its attachment metadata ({file_id, filename, content_type, file_url, size}). At most 10 files per call.

Response #

200 OK as soon as the run is queued; the run executes in the background:

{"run_id": "b7c6d5e4-f3a2-4b1c-9d8e-7f6a5b4c3d2e", "status": "queued"}

The run executes the published version as the run_as user, who sees it through runs (trigger_type is trigger.webhook, automatic is true). Its input is not trusted: a step reads the user's files only when the step names them itself, never because the webhook body names them.

Rate limiting #

Each trigger accepts at most 60 calls per minute, 2,000 per hour and 20,000 per day, from any number of senders. A per-IP flood limit applies on top. A workflow also refuses new runs while it has 50 runs queued (by default). Both answer 429; a rate limit response carries Retry-After (seconds).

Example #

curl -X POST "https://ayeto.ai/api/v3/workflow/hook/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/$WEBHOOK_SECRET?source=shop" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": 1042,
    "customer": {"name": "Jana Novak", "email": "jana@example.com"},
    "invoice": {"filename": "invoice-1042.pdf", "content_type": "application/pdf", "data": "JVBERi0xLjcKJcfsj6IK..."}
  }'

Errors #

Errors have the JSON body {"detail": "..."}. Authentication, rate limit and server errors are described in conventions.

Workflow-specific errors:

A step failure is not an HTTP error: the run comes back with status: "failed" and the reason in error and in the failing step's error.