API Reference

The Jetty REST API is one HTTP surface. The primary way in is the tasks API: deploy a runbook as a task, start runs of it, and poll the results. An OpenAI-compatible chat-completions endpoint is also provided for compatibility, so OpenAI-shaped SDKs and tools can point at Jetty without changes. A handful of smaller APIs cover scheduling, async callbacks, and source control. Everything here authenticates the same way and records every call as a run (the API calls them trajectories).

Base URL & auth

The base URL is https://flows-api.jetty.io. Authenticate every request with a bearer token:

Authorization: Bearer $JETTY_API_TOKEN

Grab a token from Settings → API keys, or run the jetty-setup skill from an agent with the Jetty plugin to write it to ~/.config/jetty/token. Prefer not to hand-roll requests? The typed SDK and the MCP tool layer wrap everything below.

Tasks API

The tasks API is the front door. Deploy a runbook as a task once (from the web app or your agent), and it becomes a stable, named thing you can run, schedule, and override per run — without resending the runbook each time:

curl -X POST https://flows-api.jetty.io/api/v1/run/my-collection/cbc-homepage-summary \
  -H "Authorization: Bearer $JETTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "init_params": {
      "vars": { "url": "https://www.cbc.ca/" }
    }
  }'

The call is async by design: it returns an id, and you poll the run for progress and results. The init_params merge over the task's stored defaults (caller wins). For short jobs, /api/v1/run-sync/{collection}/{task} waits for the result instead. The full task surface is in the machine instructions.

Chat Completions API

The POST /v1/chat/completions endpoing enables the OpenAI API so you can point at Jetty without changes. It is secondary to the tasks API. There are two modes.

Passthrough mode (no jetty block)

Without a jetty block, the endpoint is a standard LLM proxy across 100+ providers. Send it like any OpenAI chat request, and every call is recorded as a run you can replay and grade later.

curl https://flows-api.jetty.io/v1/chat/completions \
  -H "Authorization: Bearer $JETTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      { "role": "user", "content": "Summarize the theory of relativity in 3 bullets" }
    ]
  }'

Runbook mode (add a jetty block)

Add a jetty block with a collection and a runbook_url and the same endpoint provisions a sandbox, runs an agent against your runbook, and returns structured results.

curl https://flows-api.jetty.io/v1/chat/completions \
  -H "Authorization: Bearer $JETTY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "messages": [
      { "role": "user", "content": "Research the EV charging market" }
    ],
    "jetty": {
      "collection": "my-collection",
      "runbook_url": "https://github.com/org/repo/blob/main/RUNBOOK.md"
    }
  }'

See the full walkthrough in the get-started guide.

Scheduling API

Scheduled runs are configured under the routines endpoint (the API's name for a schedule). Create, list, update, and delete them, or trigger one immediately with run-now.

POST   /v1/routines           # create
GET    /v1/routines           # list
PATCH  /v1/routines/{id}      # update
DELETE /v1/routines/{id}      # delete
POST   /v1/routines/{id}/run  # run now

Webhooks

Register a callback URL to be notified when an async workflow completes. Payloads are HMAC-signed, so verify the signature before trusting the body. Webhooks are how human-in-the-loop steps hand control back to your system.

GitHub PR API

Open pull requests programmatically from a workflow, so an agent that produces code or config changes can land them through review rather than commit directly.

Monitoring a run

List or get runs to track one from start to finish. Each run captures the step inputs and outputs, so you can watch progress, inspect results, and grade them.

curl https://flows-api.jetty.io/v1/trajectories \
  -H "Authorization: Bearer $JETTY_API_TOKEN"

Behind the endpoint

One API surface, five components:

• Passthrough proxy: the OpenAI-compatible front door to 100+ providers.
• Workflow engine: runs multi-step DAGs. See Running AI Workloads.
• Runbook engine: spins up sandboxed agents to execute markdown runbooks.
• Persistence: a relational database for metadata plus object storage for artifacts.
• Tracing: every execution is recorded as a run — the full trace of what ran, in what order, with which inputs and outputs. That's what makes a run replayable and gradeable.

Durable execution

Workflows are backed by a durable execution engine, which gives you automatic retries and exactly-once semantics. Each runbook run gets its own isolated sandbox, so concurrent runs can't see or step on each other.