Free Trial
Documentation menu

Architecture

Jetty is one API with two modes. You talk to a single endpoint, and what comes back depends on whether you ask for a plain model call or a full runbook run. Either way the call is recorded as a trajectory, so you get tracing for free.

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

The endpoint is OpenAI-compatible, so existing SDKs and tools point at it without changes.

Mode 1: Passthrough

With no jetty block, the endpoint is a standard LLM proxy across 100+ providers. Send an OpenAI-shaped request, get an OpenAI-shaped response. Switch providers by changing the model field, and nothing else moves. Every call is recorded as a trajectory automatically.

curl https://flows-api.jetty.io/v1/chat/completions \
  -H "Authorization: Bearer $JETTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4.6",
    "messages": [{ "role": "user", "content": "Explain quantum computing simply" }]
  }'

Mode 2: Runbook

Add a jetty block with a collection and a runbook_url, and Jetty provisions an isolated sandbox, runs a coding agent through the runbook, and returns structured results.

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

Same endpoint, same auth, same request shape. The presence of the jetty block is the only difference between proxying a single model call and running a sandboxed agent.

The components

  • Passthrough proxy: the OpenAI-compatible front door to 100+ providers.
  • Workflow engine: runs multi-step DAGs. See workflows & steps.
  • Runbook engine: spins up sandboxed agents to execute markdown runbooks.
  • Persistence: a relational database for metadata plus object storage for artifacts.
  • Tracing: every run produces a trajectory.

Durable execution

Workflows are backed by a durable execution engine, which gives you automatic retries and exactly-once semantics — a step that fails midway resumes rather than re-running from scratch. Each runbook run gets its own isolated sandbox, so concurrent runs can't see or step on each other.

Multi-backend storage

Artifacts and trajectories can live in Jetty-managed storage, GCS, S3, or Cloudflare R2. The backend is configurable per collection, so each team can keep its data wherever it needs to.

Built on open standards

Nothing here is proprietary lock-in. The API is OpenAI-compatible, agent tooling uses MCP, and runbooks are plain markdown in your own repo. You can take your prompts, your runbooks, and your data and walk.

Everything returns a trajectory

Whichever mode you use, the result includes a trajectory — the full execution trace of what ran, in what order, with which inputs and outputs. That's what makes a run replayable and gradeable. See trajectories & evaluation.

Next: the full request and response shapes in the API reference, or how the runbook engine works in runbooks.