Workflows · Ephemeral docs

Save run definitions under a name and start them with POST /v1/runs. Member and admin keys can use every endpoint on this page. See workflows for how saved fields and overrides combine.

Save a workflow

PUT/v1/workflows/{name}

Creates the workflow, or replaces it if the name exists. Names start with a letter or digit and contain up to 128 letters, digits, _, . or -.

Body

promptstringrequired

The task. Up to 128 KiB.

modelstring

Model ID. When omitted, each run uses the default model at the time it is created.

filesarray

File entries, as in a run request. Names are resolved when each run is created.

connectionsobject

Connections keyed by the name the agent sees. Prefer {"ref": "<saved name>"} entries.

descriptionstring

What the workflow does and what input it expects. Up to 500 characters.

input_schemaobject

A JSON Schema that each run's input must match; a run that does not match is refused with 400. See describing inputs and outputs.

output_schemaobject

A JSON Schema that each run's output must match; the output is then JSON, and a run whose output does not match fails. See describing inputs and outputs.

timeout_secondsinteger

1 to 3600. Runs use 300 when omitted.

shellboolean

Runs use true when omitted.

webboolean | object

Web access for the workflow's runs: true, or an object with allow and search. Off when omitted.

A workflow cannot hold input, max_cost_micros or callback; those belong to each run. The response is {"name": "investigate-payment"}.

curl -X PUT $EPHEMERAL_URL/v1/workflows/investigate-payment \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Find out why this payment failed. Follow the playbook.",
    "model": "anthropic/claude-haiku-5.5",
    "files": [{ "file": "playbook.md" }],
    "connections": { "payments": { "ref": "payments-api", "allowed_methods": ["GET"] } },
    "timeout_seconds": 120,
    "shell": false
  }'

Send the workflow name to POST /v1/runs with the input and budget for this run. Any definition field you include replaces the saved value for this run; files and connections replace the whole collection.

Terminal

curl $EPHEMERAL_URL/v1/runs \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workflow":"investigate-payment","input":{"payment_id":"pay_123"},"max_cost_micros":500000}'

If the workflow does not exist, the request fails with 400 and the message saved workflow not found.

List workflows

GET/v1/workflows

Returns the workflows of the organization in alphabetical order, each as an object with its name. Add ?detail=true to include each workflow's description, input_schema and output_schema when it has them. Fetch a workflow by name to see its whole definition.

JSON

[{ "name": "investigate-payment" }, { "name": "weekly-report" }]

With ?detail=true, an agent can see what each workflow expects and returns:

JSON

[
  {
    "name": "weather",
    "description": "Current weather for a city. Input is a city name.",
    "input_schema": { "type": "object", "required": ["city"], "properties": { "city": { "type": "string" } } },
    "output_schema": { "type": "object", "required": ["city", "temperature_c", "summary"] }
  },
  { "name": "weekly-report" }
]

Get a workflow

GET/v1/workflows/{name}

Returns the saved definition. Credentials in inline connections are removed, and query values in their URLs are masked.

To edit a workflow, fetch it, change it and save it back with PUT. Credential fields you leave empty keep their stored values, as long as the connection's authentication type is unchanged.

Delete a workflow

DELETE/v1/workflows/{name}

Deletes the workflow and returns 204 No Content. Runs that already used it are not affected.

Workflows are not versioned. Saving or deleting one takes effect for the next run that names it.

Save a workflow

Start a workflow

List workflows

Get a workflow

Delete a workflow