Common Gotchas

Known quirks and parameter mismatches that trip up agents working with Jetty. If your workflow runs but produces unexpected results (or errors), check here first.

Parameter Mismatches

Several step templates have documentation that doesn't match what the runtime actually expects.

litellm_chat

Parameter	Docs say	Runtime expects
User prompt	user_prompt / user_prompt_path	prompt / prompt_path

Use prompt or prompt_path — the user_prompt variants won't work.

simple_judge

Parameter	Docs say	Runtime expects
Content to judge	content / content_path	item / item_path (single) or items / items_path (multiple)
Judging criteria	criteria / criteria_path	instruction / instruction_path

Both instruction and item/items are required — omitting either will error.

The score_range parameter uses its values as category labels (strings), not numeric scores. For example, "score_range": ["1", "2", "3", "4", "5"] produces a categorical judgment like "3", not a number.

Image support: Pass a storage path (.webp, .png, .jpg) as item_path — the judge auto-converts it for vision.

replicate_text2image

Output is at .outputs.images[0].path — not .outputs.storage_path.

litellm_vision

For storage paths (files already in Jetty), use image_path_expr — not image_url_path (which is for external URLs).

gemini_image_generator

Output is at .outputs.images[0].path — same as replicate_text2image, not .outputs.storage_path.

---

API Response Formats

Trajectories are wrapped

The trajectories endpoint returns an object, not an array:

{
  "trajectories": [...],
  "total": 100,
  "page": 1,
  "limit": 20,
  "has_more": true
}

Access via .trajectories[] or .trajectories[0] — not .[] or .[0] directly.

Steps are objects, not arrays

Inside a trajectory, steps is an object keyed by step name:

{
  "steps": {
    "generate": { "outputs": { "content": "..." } },
    "judge": { "outputs": { "results": [...] } }
  }
}

Access with .steps.generate.outputs.content, not .steps[0].outputs.content.

Step templates response

The step templates list endpoint returns {"templates": [...]} — access via .templates[].

---

URL Disambiguation

Jetty has three domains that are easy to mix up:

Domain	Purpose	Use for API calls?
flows-api.jetty.io	Flows API — run workflows, view trajectories, download files	Yes
dock.jetty.io	Dock API — manage collections, tasks, datasets, models	Yes
flows.jetty.io	Web frontend (HTML)	No — returns HTML, not JSON

Common mistake: using flows.jetty.io (frontend) instead of flows-api.jetty.io (API).

---

Token Handling

• Inline the token in bash commands: set TOKEN="mlc_..." at the start, then use $TOKEN
• Don't rely on $JETTY_API_TOKEN as an environment variable — it's not persisted across shell invocations in most coding agents
• Tokens are collection-scoped — a token for one collection will return 403 on a different collection

---

File Downloads

Download files from trajectories using the Flows API:

GET https://flows-api.jetty.io/api/v1/file/{full_file_path}

The file path comes from trajectory step outputs — typically at .steps.{step}.outputs.files[].path or .steps.{step}.outputs.images[].path.

Not dock.jetty.io/api/v1/assets/ — that endpoint doesn't exist.

---

Other Quirks

run-sync has a timeout

The synchronous run endpoint has a server-side timeout. For long-running workflows, use the async run-workflow and poll trajectories instead.

File uploads require multipart form data

Use curl -F (multipart), not curl -d (JSON body), when running workflows.

Step order matters

Steps in the steps array execute sequentially. A step cannot reference outputs from a step that runs after it.

Path expression wildcards

[*] returns an array of all matching values: step1.outputs.items[*].id → ["id1", "id2", ...]. Different from [0] which returns a single value.

Label values are always strings

All label values are strings, even if they look numeric. "2.5" is stored as a string, not a number.

Bash scripting in agents

Complex multi-step bash commands can break due to zsh escaping. Write to a temp file and execute:

cat > /tmp/jetty-script.sh << 'SCRIPT'
TOKEN="mlc_your_token"
# ... your commands ...
SCRIPT
bash /tmp/jetty-script.sh