Workflows

A workflow is a run definition saved under a name. It holds the prompt, model, files, connections, timeout, shell and web settings. Your code starts it by name and sends only what changes from run to run.

{
  "workflow": "investigate-payment",
  "input": { "payment_id": "pay_123" },
  "max_cost_micros": 500000
}

What is saved and what each run sends

Save a workflow in the dashboard under Workflows, with PUT /v1/workflows/{name}, or with ephemeral workflows save. JSON is the wire format; the CLI also reads YAML. Names start with a letter or digit and can contain letters, digits, _, . and -, up to 128 characters.

Overriding saved fields

Any of prompt, model, files, connections, timeout_seconds, shell and web in the run request replaces the saved value for that run only. Files and connections are replaced as a whole collection. They are never merged with the saved ones.

{
  "workflow": "investigate-payment",
  "input": { "payment_id": "pay_123" },
  "connections": {},
  "max_cost_micros": 500000
}

An empty object or array clears that collection for the run. To change one connection or file, send the complete list you want the run to have.

When references are resolved

A workflow refers to files and saved connections by name. Ephemeral resolves those names when the run is created, and the run keeps what it resolved. A file name resolves to the latest upload with that name, so uploading a new version of playbook.md changes what the next run reads without editing the workflow.

If a referenced file or connection no longer exists, the run request fails with 400 and names the missing reference. Nothing is queued and nothing is charged.

Describing inputs and outputs

Three optional fields let a workflow describe itself, so that people, other code and AI agents know how to call it without reading its prompt. description says in a sentence or two what the workflow does and what input it expects (up to 500 characters). input_schema is a JSON Schema that the run's input must match. output_schema is a JSON Schema that the run's output must match. All three come back from GET /v1/workflows?detail=true and from the MCP list_workflows tool, and they work on an inline run too.

description: Current weather for a city. Input is a city name.
prompt: Look up the current weather for the city in the input and report it.
web: true
input_schema:
  type: object
  required: [city]
  properties:
    city: { type: string }
output_schema:
  type: object
  required: [city, temperature_c, summary]
  properties:
    city: { type: string }
    temperature_c: { type: number }
    summary: { type: string }

The input is checked when a run is created, whether it comes from the API, the CLI, an MCP tool or a schedule. If it does not match, the request fails with 400 and names each problem as a path and a reason, such as input.city: required. Nothing is queued and nothing is charged. A schedule's input is checked when you create or change the schedule, and again at every start; a start that no longer matches is recorded as the schedule's last error.

The output must be JSON that matches output_schema. The agent is told the schema and asked to reply with the JSON only. If its reply does not match, it is sent the exact errors and asked to correct it, up to two times. Ephemeral then checks the output again: a match leaves the run succeeded, with the JSON text as the output and no code block around it. A mismatch ends the run failed with an error such as output did not match output_schema: output.temperature_c: got string, want number, and the output text is kept so you can see what the agent wrote. A zero-data-retention run keeps no detail in the error.

Schemas use JSON Schema draft 2020-12 (a $schema naming draft 7 or earlier also works), up to 32 KiB each, and may refer only to definitions inside the schema, such as #/$defs/address. An invalid schema is refused with 400 when the workflow is saved or the run is created.

Editing a workflow

Saving a workflow again replaces it. There is no version history. Runs created before the change keep the definition they were created with; to see exactly what a run used, read its definition.

Reading a workflow returns it with connection credentials and URL secrets removed. If you save it back with those fields left out, the stored credentials are kept as long as the authentication type stays the same.