jetty

For endpoints not documented in this skill, the Jetty API serves a live OpenAPI spec and Swagger UI:

Both are reachable without authentication. When this skill's docs don't mention an endpoint you need, check the OpenAPI spec first — it's the ground truth.

For a compact orientation to the whole platform — the state model, the emulated CLI verbs (jetty run, jetty status, jetty simulate, jetty init), the runbook file format, and the anti-patterns that bite — see MACHINE_CONTEXT.md and agent-instructions.md (the pasteable onboarding trigger). They ship at the plugin/repo root; if this skill was installed detached (e.g. a single symlinked skill dir), fetch them from https://jetty.io/MACHINE_CONTEXT.md and https://jetty.io/agent-instructions.md.

When sharing links with the user (e.g., after launching a run), use these exact URL patterns. Do NOT guess or invent URL paths — only use the formats listed here:

The mlc_ API key is collection-scoped (it resolves to the org that owns the collection). Subscription credentials (Nous / Codex / Anthropic, under Settings → Connected Accounts) are user-scoped to your Clerk user. So to link or run on a personal subscription from the CLI, you must act as that user — an mlc_ key can't see your linked accounts.

scripts/jetty_auth.py does a browser login (Clerk OAuth, Authorization Code + PKCE, localhost loopback) and stores a refreshable user token at ~/.config/jetty/user-token.json (separate from the mlc_ key):

JA="$(dirname "$0")/scripts/jetty_auth.py"   # or the skill's scripts/jetty_auth.py
python3 "$JA" login        # browser login as your Clerk user
python3 "$JA" whoami       # show sub / email / azp
python3 "$JA" accounts     # list your linked subscriptions
python3 "$JA" connect nous # paste a Portal refresh token (hermes setup --portal)
python3 "$JA" token        # print a fresh access token (auto-refreshes)
python3 "$JA" logout

Which token to use:

• User-scoped ops — Connected Accounts (/connected-accounts/*) and running a task on a subscription — must use the user token: AUTH="Bearer $(python3 "$JA" token)".
• Collection-scoped ops (create/run/inspect tasks normally) keep using the mlc_ key as above.

Run a runbook on a connected subscription (user identity + the subscription_credential param):

python3 "$JA" login            # once
TOK="$(python3 "$JA" token)"
curl -s -X POST -H "Authorization: Bearer $TOK" \
  -F 'init_params={"subscription_credential":"nous"}' \
  "https://flows-api.jetty.io/api/v1/run/{COLLECTION}/{TASK}"

Requires the Clerk "Jetty CLI" OAuth app (provisioned) and mise accepting its azp. Config is env-overridable (JETTY_CLERK_CLIENT_ID, JETTY_CLERK_ISSUER, JETTY_API). See the "CLI login via Clerk OAuth" design doc on the Subscription Credential Forwarding project for the full architecture.

# Run async (returns immediately with workflow_id)
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -F 'init_params={"key": "value"}' \
  "https://flows-api.jetty.io/api/v1/run/{COLLECTION}/{TASK}" | jq

# Run sync (waits for completion — use for testing, not production)
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -F 'init_params={"key": "value"}' \
  "https://flows-api.jetty.io/api/v1/run-sync/{COLLECTION}/{TASK}" | jq

# Run with file upload (must use -F multipart, not -d JSON)
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -F 'init_params={"prompt": "Analyze this document"}' \
  -F "files=@/path/to/file.pdf" \
  "https://flows-api.jetty.io/api/v1/run/{COLLECTION}/{TASK}" | jq

How init_params merge: the run's init_params are merged over the task's stored workflow.init_params shallowly, per top-level key — caller wins. A nested object is replaced whole, not merged. For runbook tasks this matters for vars: sending {"vars": {"url": "..."}} replaces the task's entire vars object, so any variable you leave out is gone (its {{placeholder}} stays unsubstituted). Read the task first (GET /api/v1/tasks/{COLLECTION}/{TASK} → .workflow.init_params.vars) and send the full object with your changes applied. Routine init_params_overrides merge the same way.

Instead of polling, pass webhook_url on an async run and Jetty POSTs to it when the run finishes (completed or failed). There is no webhook registration endpoint — the URL rides on the request:

• POST /api/v1/run/{COLLECTION}/{TASK} — webhook_url / webhook_secret as form fields (multipart) or top-level JSON fields
• Chat-completions runbook mode — jetty.webhook_url / jetty.webhook_secret; with a webhook set (and stream: false) the call returns 202 immediately
• Routines — webhook_url / webhook_secret on the routine, applied to every run it fires
• /api/v1/run-sync ignores both fields and never sends a webhook (the response already carries the result). The MCP run-workflow tools don't expose webhook fields; use the REST API.

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -F 'init_params={"prompt": "analyze this"}' \
  -F 'webhook_url=https://ops.example.com/jetty' \
  -F "webhook_secret=$WEBHOOK_SECRET" \
  "https://flows-api.jetty.io/api/v1/run/{COLLECTION}/{TASK}" | jq

Signed vs. unsigned — webhook_secret is optional:

A URL alone is enough to get deliveries; the secret only adds the signature. When the receiver acts on the payload, set a secret and have the receiver fail closed: reject requests with no X-Mise-Signature, recompute the HMAC over the timestamp header + . + the raw body bytes, compare in constant time, and reject stale timestamps.

• Body: the full trajectory JSON (same as GET /api/v1/trajectory/{COLLECTION}/{TASK}/{TRAJECTORY_ID}); check .status. webhook_secret is never included.
• Delivery: up to 3 attempts (1 s, 2 s backoff, 30 s timeout each); any status < 400 counts as delivered. Best effort — a failed delivery is logged on the run but never fails it.
• Not to be confused with the webhook step activity, which makes an outbound HTTP call mid-workflow.

Before triggering a run, check if the collection is on an active trial with no provider keys configured:

TOKEN="$(cat ~/.config/jetty/token)"
# Check trial status
TRIAL=$(curl -s -H "Authorization: Bearer $TOKEN" \
  "https://flows-api.jetty.io/api/v1/trial/{COLLECTION}")
TRIAL_ACTIVE=$(echo "$TRIAL" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('active', False))")

# Check if provider keys exist
COLL=$(curl -s -H "Authorization: Bearer $TOKEN" \
  "https://flows-api.jetty.io/api/v1/collections/{COLLECTION}/environment")
HAS_KEYS=$(echo "$COLL" | python3 -c "
import sys, json
d = json.load(sys.stdin)
evars = d.get('environment_variables', {})
keys = ['OPENROUTER_API_KEY', 'OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'GEMINI_API_KEY', 'REPLICATE_API_TOKEN']
print(any(k in evars for k in keys))
")

If the trial is active and no provider keys are configured (HAS_KEYS is False), include use_trial_keys: true in the run request body:

# Run with trial keys
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -F 'init_params={"key": "value"}' \
  -F 'use_trial_keys=true' \
  "https://flows-api.jetty.io/api/v1/run/{COLLECTION}/{TASK}" | jq

After triggering a run, if the response includes trial metadata (e.g., trial object with runs_used, runs_limit, runs_remaining), display it to the user:

Trial run {runs_used}/{runs_limit}

Don't be precious about the run count — running out mid-testing is no big deal. If runs_remaining is low, mention it but keep it reassuring:

{runs_remaining} trial runs left. Running low while testing? Email dev@jetty.io and we'll top you up — no problem. You can also add your own API keys anytime with /jetty-setup.

# Example: parse trial metadata from run response
RESPONSE=$(curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -F 'init_params={"key": "value"}' \
  "https://flows-api.jetty.io/api/v1/run/{COLLECTION}/{TASK}")

echo "$RESPONSE" | python3 -c "
import sys, json
d = json.load(sys.stdin)
trial = d.get('trial')
if trial:
    used = trial.get('runs_used', '?')
    limit = trial.get('runs_limit', '?')
    remaining = trial.get('runs_remaining', '?')
    print(f'Trial run {used}/{limit}')
    if isinstance(remaining, int) and remaining <= 2:
        print(f'{remaining} trial runs left. Running low while testing? Email dev@jetty.io for a top-up — no problem. You can also add your own keys with /jetty-setup.')
"

Any storage path the API returns can be downloaded with GET /api/v1/file/{FULL_FILE_PATH} — singular file, storage path appended as-is (no ?path= form). Storage paths are collection-prefixed ({collection}/{task}/0000/...), and the token must belong to that collection. This works for:

• Generated assets: .steps.{STEP}.outputs.images[0].path
• Runbook artifacts: every results_files[].path and primary_files[] entry on the runbook run step output — i.e. everything the agent wrote to /app/results/

# Download a generated file — path from trajectory: .steps.{STEP}.outputs.images[0].path
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://flows-api.jetty.io/api/v1/file/{FULL_FILE_PATH}" -o output_file.jpg

# Runbook artifacts: list the storage paths from the run step output…
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://flows-api.jetty.io/api/v1/db/trajectory/{COLLECTION}/{TASK}/{TRAJECTORY_ID}" \
  | jq -r '.steps.run.outputs.results_files[].path'

# …then fetch each one via /api/v1/file/ — each path value is already a
# full collection-prefixed storage path; use it as-is, don't re-prefix
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://flows-api.jetty.io/api/v1/file/{PATH_FROM_RESULTS_FILES}" \
  -o local_name.ext

# List everything stored under a run's folder
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://flows-api.jetty.io/api/v1/list-files?prefix={COLLECTION}/{TASK}/0000" | jq '.files'

# Or download an entire trajectory (all assets) as a zip
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://flows-api.jetty.io/api/v1/trajectory/{COLLECTION}/{TASK}/{TRAJECTORY_ID}/download" -o run.zip

⚠️ These are the only download routes. /api/v1/files/{path} (plural) is the OpenAI-style Files API keyed by opaque file-… ids — it 404s on storage paths. /api/v1/storage/..., /api/v1/results/..., /api/v1/sandbox/download, and ?path= variants do not exist.

# Add a label to a trajectory
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://flows-api.jetty.io/api/v1/trajectory/{COLLECTION}/{TASK}/{TRAJECTORY_ID}/labels" \
  -d '{"key": "quality", "value": "high", "author": "user@example.com"}' | jq

Label fields: key (required), value (required), author (required).

For the full catalog, read references/step-templates.md.

# List all available step templates
curl -s "https://flows-api.jetty.io/api/v1/step-templates" | jq '[.templates[] | .activity_name]'

# Get details for a specific activity
curl -s "https://flows-api.jetty.io/api/v1/step-templates" | jq '.templates[] | select(.activity_name == "litellm_chat")'

When deploying a runbook as a Jetty task:

1. Parse the runbook's YAML frontmatter for a secrets block
2. Extract required env var names from secrets.*.env
3. Check the target collection's configured environment variables
4. If any required secrets are missing, prompt the user to set them before proceeding
5. Package only non-secret parameters as init_params in the run request
6. Secrets are accessed by steps via collection environment variables at runtime

The run request supports secret_params for ad-hoc secret passing:

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -F 'init_params={"prompt": "analyze this"}' \
  -F 'secret_params={"TEMP_API_KEY": "sk-..."}' \
  "https://flows-api.jetty.io/api/v1/run/{COLLECTION}/{TASK}"

secret_params are merged into the runtime environment (same as collection env vars) but are NEVER stored in the trajectory. Use this for one-off runs; for production, configure secrets as collection environment variables.

A runbook is a structured markdown document (RUNBOOK.md) that tells a coding agent how to accomplish a complex, multi-step task with evaluation loops and quality gates. Runbooks can be executed locally (the agent follows the runbook directly) or remotely on Jetty (via the chat-completions endpoint).

When the user says "run runbook", determine the mode:

• "run runbook locally" / "follow the runbook" / no explicit mode → Local mode
• "run runbook on Jetty" / "run runbook remotely" / "deploy runbook" → Remote mode

If ambiguous, use AskUserQuestion to ask.

The agent becomes the executor. Read the RUNBOOK.md and follow it step by step.

1. Read the runbook file with the Read tool
2. Parse the frontmatter for version, evaluation pattern, and secrets
3. Parse the Parameters section — identify which parameters have defaults and which need values
4. Ask the user for any required parameter values that are missing (use AskUserQuestion)
5. For each secret declared in frontmatter, check if the env var is set: echo "${SECRET_NAME:+SET}". If missing, prompt the user.
6. Create the results directory: mkdir -p {{results_dir}}
7. Follow each step in order — Environment Setup, Processing Steps, Evaluation, Iteration, Report, Final Checklist
8. Write all output files to {{results_dir}} (defaults to ./results locally)

# Example: user says "run the runbook with sample_size=5"
mkdir -p ./results
# Then follow each step from the RUNBOOK.md...

Launch the runbook on Jetty's sandboxed infrastructure via the OpenAI-compatible chat-completions endpoint.

Endpoint: POST https://flows-api.jetty.io/v1/chat/completions

1. Read the runbook file with the Read tool
2. Parse the YAML frontmatter for agent, model, model_provider, snapshot, and secrets:
   • agent → use as jetty.agent (default: claude-code)
   • model → use as model in the request (default: claude-sonnet-4-6)
   • model_provider → use as jetty.model_provider (default: anthropic)
   • snapshot → use as jetty.snapshot (default: python312-uv; use prism-playwright if the runbook needs a browser)
   • secrets → check that each required secret is configured as a collection env var:
   Copy

   curl -s -H "Authorization: Bearer $TOKEN" \
     "https://flows-api.jetty.io/api/v1/collections/{COLLECTION}/environment" | jq '.environment_variables | keys'

   If any required secrets are missing, prompt the user to set them (or pass via secret_params).
3. Parse the Parameters section of the runbook. Identify all {{template_variable}} placeholders and their defaults. Ask the user for any required parameter values that are missing (use AskUserQuestion). These go in jetty.template_variables.
4. Check trial key eligibility — use the same trial detection logic from Trial Key Support above. If the trial is active and no provider keys are configured, set use_trial_keys: true in the jetty block below.
5. Ask the user for the collection and task name. Also ask for any file uploads.
6. Build and send the request — the runbook content goes in the system message, and template variables go in jetty.template_variables (not in the user message):

# Read the runbook content
RUNBOOK_CONTENT="$(cat /path/to/RUNBOOK.md)"

# Check trial eligibility (see Trial Key Support section)
TOKEN="$(cat ~/.config/jetty/token)"
TRIAL=$(curl -s -H "Authorization: Bearer $TOKEN" \
  "https://flows-api.jetty.io/api/v1/trial/{COLLECTION}")
TRIAL_ACTIVE=$(echo "$TRIAL" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('active', False))")
COLL=$(curl -s -H "Authorization: Bearer $TOKEN" \
  "https://flows-api.jetty.io/api/v1/collections/{COLLECTION}/environment")
HAS_KEYS=$(echo "$COLL" | python3 -c "
import sys, json
d = json.load(sys.stdin)
evars = d.get('environment_variables', {})
keys = ['OPENROUTER_API_KEY', 'OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'GEMINI_API_KEY', 'REPLICATE_API_TOKEN']
print(any(k in evars for k in keys))
")
# Set USE_TRIAL to true if trial is active and no provider keys exist
USE_TRIAL=$( [ "$TRIAL_ACTIVE" = "True" ] && [ "$HAS_KEYS" = "False" ] && echo true || echo false )

# Build the request payload
cat <<PAYLOAD | curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://flows-api.jetty.io/v1/chat/completions" \
  --data-binary @-
{
  "model": "claude-sonnet-4-6",
  "messages": [
    {"role": "system", "content": $(jq -Rs '.' <<< "$RUNBOOK_CONTENT")},
    {"role": "user", "content": "Execute the runbook."}
  ],
  "stream": false,
  "jetty": {
    "runbook": true,
    "collection": "{COLLECTION}",
    "task": "{TASK}",
    "agent": "claude-code",
    "model_provider": "anthropic",
    "snapshot": "python312-uv",
    "template_variables": {
      "sample_size": "10",
      "results_dir": "/app/results"
    },
    "use_trial_keys": $USE_TRIAL
  }
}
PAYLOAD

Important: Template variables ({{sample_size}}, {{results_dir}}, etc.) must go in jetty.template_variables, NOT in the user message text. The backend substitutes {{var}} placeholders in the runbook instruction before the agent sees it. The user message is only used as a prompt/instruction to the agent (it's also exposed as {{prompt}}).

Send every variable. In this mode the run's vars are built from jetty.template_variables plus prompt and results_dir, and they replace the task's stored vars wholesale — defaults saved on the task are not merged in. Include every parameter the runbook uses, with its default if the user didn't override it.

7. Extract the trajectory ID from the response
8. Monitor the trajectory using the standard trajectory inspection commands:
   Copy

   curl -s -H "Authorization: Bearer $TOKEN" \
     "https://flows-api.jetty.io/api/v1/db/trajectory/{COLLECTION}/{TASK}/{TRAJECTORY_ID}" | jq '{status, steps: (.steps | keys)}'

The chat-completions endpoint supports two modes via a single URL:

Jetty block fields:

File upload (if the runbook needs input files):

Pick one of the two flows below — the upload endpoint and the jetty field are paired; don't cross them.

Recommended — sandbox upload → jetty.file_paths:

# 1. Upload via multipart. The form field name MUST be `files` (repeatable). Returns storage paths.
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -F "files=@/path/to/input.csv" \
  "https://flows-api.jetty.io/api/v1/sandbox/upload" | jq
# => { "upload_id": "...", "file_paths": ["{COLLECTION}/_sandbox_uploads/<id>/input.csv"], "count": 1 }

# 2. Put the returned storage path(s) into jetty.file_paths on the chat-completions request.
#    Files mount under /app/assets/ in the sandbox (the runbook step renames each stored
#    copy to <trajectory_id>.NN.<ext>); zip files are auto-extracted.

Alternative — OpenAI-style upload → jetty.files:

curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/input.csv" \
  "https://flows-api.jetty.io/api/v1/files" | jq '.id'
# => "file-abc123"  — pass this in jetty.files (NOT jetty.file_paths)

⚠️ Don't put a file-… id in jetty.file_paths. Entries in file_paths are loaded as raw storage keys, so a file-… id fails to resolve and is silently dropped — init_params.file_paths arrives as [], the file never reaches the sandbox, and the run can still report success: true with empty, schema-valid output. There is no POST /api/v1/files/upload endpoint (it returns 405); use /api/v1/sandbox/upload (→ file_paths) or /api/v1/files (→ files) as shown above.

With the OpenAI Python SDK:

from openai import OpenAI

client = OpenAI(
    base_url="https://flows-api.jetty.io",
    api_key="your-jetty-api-token"
)

# Read runbook
with open("RUNBOOK.md") as f:
    runbook = f.read()

response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[
        {"role": "system", "content": runbook},
        {"role": "user", "content": "Execute the runbook."}
    ],
    stream=True,
    extra_body={
        "jetty": {
            "runbook": True,
            "collection": "my-org",
            "task": "my-task",
            "agent": "claude-code",
            "model_provider": "anthropic",
            "snapshot": "python312-uv",  # or "prism-playwright" for browser
            "template_variables": {
                "sample_size": "10",
            },
        }
    }
)

Sandbox conventions:

• Template variables ({{results_dir}}, {{sample_size}}, etc.) are substituted by the backend before the agent sees the instruction. Pass them in jetty.template_variables, never in the user message text
• results_dir defaults to /app/results on Jetty (vs ./results locally) — it's auto-included as a template variable
• Everything written to /app/results/ is persisted to cloud storage — after the run, fetch artifacts with GET /api/v1/file/{storage path} using the results_files/primary_files paths from the run step output (see Download Files above)
• Secrets resolve from collection environment variables
• snapshot controls the sandbox image: python312-uv (default) or prism-playwright (Playwright + Chromium for browser tasks). Read this from the runbook's YAML frontmatter
• The sandbox is destroyed after execution — artifacts and logs survive

A routine is a saved schedule that fires an existing task on a recurring cadence. Routines build on the same FlowWorkflow.run pipeline as one-shot runs, with optional init_params_overrides merged on top of the task's defaults (shallow, per top-level key — an override of vars replaces the whole vars object, so include every variable). A routine can also carry webhook_url / webhook_secret, applied to every run it fires (see Completion webhooks). Trajectories produced by a routine are tagged with triggered_by_routine_id for easy filtering.

Use the MCP tools (preferred) or hit the REST API directly:

Cadence enum (UTC only in v1):

Validation rules (enforced server-side):

• init_params_overrides keys MUST be a subset of task.workflow.init_params. Unknown keys return 400 with the offending key list.
• daily / weekdays / weekly require hour_utc. weekly additionally requires day_of_week.
• manual rejects cadence params other than type.
• API keys can only manage routines in the collection they are bound to.

Example: schedule a daily 9am UTC summary

TOKEN="$(cat ~/.config/jetty/token)"
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://flows-api.jetty.io/api/v1/routines/{COLLECTION}/{TASK}" \
  -d '{
    "name": "daily-summary",
    "cadence": {"type": "daily", "hour_utc": 9, "minute_utc": 0},
    "init_params_overrides": {"prompt": "Summarize yesterday"}
  }' | jq

To inspect runs from a routine, call list-routine-runs (or hit .../runs) — these are the same trajectories you would see via list-trajectories, filtered to those tagged with triggered_by_routine_id.

init_params.prompt              # Input parameter
step1.outputs.text              # Output from step1
step1.outputs.items[0].name     # Array index access
step1.outputs.items[*].id       # Wildcard (returns array of all ids)
step1.inputs.prompt             # Input that was passed to step1

For workflow templates (simple chat, image generation, model comparison, fan-out, etc.), read references/workflow-templates.md.

• Use prompt / prompt_path (NOT user_prompt / user_prompt_path)
• system_prompt / system_prompt_path works as documented
• prompt_path must resolve to a single string. If it resolves to an array (e.g. init_params.distill_texts: ["a", "b", "c"]), the Anthropic provider path crashes deep in litellm with TypeError: string indices must be integers, not 'str' (the is_pdf_used check assumes each content entry is a dict and indexes it with "type"). Workaround: stringify the array caller-side and pass a single string (prompt: JSON.stringify(arr) or a delimited join), and describe the shape in system_prompt so the model knows to parse it.
• Haiku-class models can default to acknowledgement boilerplate on large inputs. If a step that distills/synthesizes/transforms a long input (a chat history, a multi-doc dossier, a structured JSON blob) starts returning "I understand. I'm ready to receive..." style messages instead of the expected output, the user prompt is reading as context rather than as a request. Two patches that consistently fix this in practice:
  • In the runbook's system_prompt, explicitly bracket the input ("The subject input begins below the horizontal rule and ends at end-of-message.") and name the deliverable.
  • On the caller side, append an explicit trailing instruction after the long input — e.g. "\n\nProduce the X JSON now per your output schema. Begin your response with { and end with }. No preamble, no markdown fences, no commentary." Together these make the request shape unambiguous even on Haiku-tier models.

• For a child task in the same collection, use the plain task name in child_workflow_name (for example, process-single-item), not {COLLECTION}/process-single-item.
• Use child_init_params / child_init_params_path for values shared by every emitted child workflow.
• The runtime returns child references at .outputs.trajectory_references (NOT .outputs.trajectory_ids).
• items: [...] (literal array) is not accepted — only items_path: "<ref>". Passing a literal items array fails workflow start with ValueError: items_path is required. Workaround: hoist the literal set into init_params and reference it, e.g. init_params.perspectives: ["a", "b", "c", "d"] plus items_path: "init_params.perspectives".

• Use trajectory_list_path pointing at a list of trajectory reference objects (usually fanout_step.outputs.trajectory_references), NOT trajectory_ids_path.
• Use extract_keys as a dictionary of output key to child trajectory path, NOT extract_paths.
• Example:
  Copy

  {
    "activity": "extract_from_trajectories",
    "trajectory_list_path": "process_all.outputs.trajectory_references",
    "extract_keys": {
      "text": "extract.outputs.text"
    }
  }

• Outputs at .outputs.images[0].path (NOT .outputs.storage_path or .outputs.image_url)
• Also available: .outputs.images[0].extension, .outputs.images[0].content_type

• Outputs at .outputs.images[0].path (NOT .outputs.storage_path)

• For storage paths from previous steps: use image_path_expr (NOT image_url_path)
• image_url_path is for external HTTP URLs only
• ⚠️ External URLs may be rejected on the deployed runtime. Observed 2026-05 on flows-api.jetty.io: passing an external URL via image_url/image_url_path fails with ValueError: image_path is required for vision models, and passing the same URL to image_path/image_path_expr makes Jetty parse https://... as a workflow reference (task_name/trajectory_id) and fail with ValueError: Invalid workflow reference: https. In that case litellm_vision only accepted an internal collection-prefixed storage key via image_path. If your image lives on an external CDN, first upload it to Jetty storage (POST /api/v1/files) and reference the returned storage key — or call the vision model's provider SDK directly outside Jetty.

• Use item / item_path (NOT content / content_path)
• Use instruction / instruction_path (NOT criteria / criteria_path)
• For multiple items: items / items_path
• Supports images: pass a .webp/.png/.jpg storage path as item_path
• score_range in categorical mode uses range values as labels, not numeric scores

# 1. Find the failed trajectory
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://flows-api.jetty.io/api/v1/db/trajectories/{COLLECTION}/{TASK}?limit=5" \
  | jq '.trajectories[] | {trajectory_id, status, error}'

# 2. Examine which step failed (steps is an object, not array)
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://flows-api.jetty.io/api/v1/db/trajectory/{COLLECTION}/{TASK}/{TRAJECTORY_ID}" \
  | jq '.steps | to_entries[] | select(.value.status == "failed") | {step: .key, error: .value}'

# 3. Check workflow logs
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://flows-api.jetty.io/api/v1/workflows-logs/{WORKFLOW_ID}" | jq

Errors from fan-out children often surface on the parent. When a list_emit_await orchestrator reports something vague like "synthesize step missing", the real failure is usually in one of the child trajectories — for example, a downstream LLM call rejecting an empty prompt because the parent didn't forward init_params correctly. Walk the chain:

# 1. Pull the parent trajectory and find the fan-out step.
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://flows-api.jetty.io/api/v1/db/trajectory/{COLLECTION}/{ORCHESTRATOR_TASK}/{TRAJECTORY_ID}" \
  | jq '.steps.{FANOUT_STEP}.outputs.trajectory_references[] | {trajectory_id, name}'

# 2. For each child trajectory, fetch and look at its failed step.
CHILD_ID=...   # from step 1
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://flows-api.jetty.io/api/v1/db/trajectory/{COLLECTION}/{CHILD_TASK}/${CHILD_ID}" \
  | jq '{status, error, steps: (.steps | to_entries[] | select(.value.status == "failed") | {step: .key, error: .value.error})}'

The root cause is almost always at the deepest layer (the LLM call's error message), not the parent's "missing step" summary. If a child trajectory's init_params arrive empty or wrong-shaped, that's a signal the orchestrator's state wiring (e.g. child_init_params / child_init_params_path) isn't forwarding what you expected — re-check the parent's step config.

# 1. Create
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://flows-api.jetty.io/api/v1/tasks/{COLLECTION}" \
  -d '{
    "name": "test-echo",
    "description": "Simple echo test",
    "workflow": {
      "init_params": {"text": "Hello!"},
      "step_configs": {"echo": {"activity": "text_echo", "text_path": "init_params.text"}},
      "steps": ["echo"]
    }
  }' | jq

# 2. Run sync
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  -F 'init_params={"text": "Test message"}' \
  "https://flows-api.jetty.io/api/v1/run-sync/{COLLECTION}/test-echo" | jq

# 3. Check result
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://flows-api.jetty.io/api/v1/db/trajectories/{COLLECTION}/test-echo?limit=1" | jq '.trajectories[0]'

For batch run scripts, read references/batch-runs.md.