API reference

The Jetty REST API is one HTTP surface behind a single base URL. Most of what you do runs through one OpenAI-compatible endpoint, while a handful of smaller APIs cover scheduling, async callbacks, and source control. Everything here authenticates the same way and records every call as a trajectory.

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 /jetty-setup in Claude Code to write it to ~/.config/jetty/token. Prefer not to hand-roll requests? The typed SDK and the MCP tool layer wrap everything below.

Chat completions — the primary endpoint

POST /v1/chat/completions is OpenAI-compatible and has two modes. The mode is decided by whether your request body carries a jetty block.

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 trajectory 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-4",
    "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-4.6",
    "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 quickstart.

Async vs. sync runs

A synchronous run that exceeds ~100s may return a Cloudflare 524 while the run continues server-side. Rather than retry the HTTP call, poll the trajectory list.

Long runbook runs routinely outlast the proxy timeout. Treat the 524 as “still working,” not “failed”: a retry just starts a second run. See troubleshooting for the polling pattern.

Routines API

Routines are scheduled runs. 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 trajectories to track a run from start to finish. Each trajectory 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"

Most builders never call this surface by hand. Reach for the typed Client SDK in TypeScript apps, or the MCP server inside your editor, since both wrap these endpoints. For the data model behind it, see architecture.