HTTP API¶

Every HTTP route of the Jezero server other than the MCP tools: device uploads, the key check, the plugin bundle, the dashboard counts and the OAuth metadata. Each is served by jezero serve on the same host and port as MCP.

Routes¶

• Any client key: Authorization: Bearer <key> of any [[clients]] entry.
• Upload key: the key of a client with upload = true, a device created by jezero device approve.
• GET routes also answer HEAD. Another method gets HTTP 405 Method Not Allowed (plain text); an unknown path gets HTTP 404 Not Found.
• Errors of the inbox and overview routes are JSON: {"ok": false, "error": "MESSAGE"}. The message is safe to show to the user.

The inbox routes always need a key, even with [server].require_auth = false.

Every route, MCP included, checks the Host and Origin headers first, with the rules of the MCP endpoint: an unknown host gets HTTP 421 with the plain-text body Invalid Host header, an unknown browser origin HTTP 403 Invalid Origin header, before the key is looked at. A computer that reaches the server by a name or address missing from public_url and allowed_hosts is refused on every route.

Keys are read again from jezero.toml within a second of a change, so a key approved, rotated or revoked with jezero device needs no restart.

Check a device key¶

GET /inbox/v1/ping

Tells a device whether its key is approved for uploads. jezero_client.py status calls it.

curl -s https://YOUR-JEZERO/inbox/v1/ping -H "Authorization: Bearer $JEZERO_DEVICE_KEY"

You should see:

{"ok": true, "device": "laptop", "version": "0.1.0.dev0"}

Upload a session file¶

PUT /inbox/v1/{agent}/{relpath}

Stores one raw session file in the device's inbox folder. The connectors read it later, like a local store (see Connectors).

The body is the file itself. {agent} and {relpath} must match one of these:

<folder> and <name> are 1 to 200 characters of A-Z a-z 0-9 . _ - (Codex names also allow :); <conversation> is 8 to 64 characters of A-Z a-z 0-9 -. A .. segment is refused.

The file is written to <inbox.dir>/<device>/<agent>/<relpath>, where <device> is the client's name. The write is atomic: a newer upload of the same session replaces the file. Its modification time is the upload time, so a device that was offline does not upload behind the connector's cursor. With X-Jezero-Project, the value is written to <file>.project, which the connectors use before any other project rule; without it, an existing <file>.project is removed.

The size limit is [inbox].max_mb (default 64) × 1024 × 1024 bytes, measured after decompression.

gzip -c ~/.claude/projects/-home-me-projects-billing/4b1c2d9e.jsonl | \
  curl -s -X PUT \
    https://YOUR-JEZERO/inbox/v1/claude-code/projects/-home-me-projects-billing/4b1c2d9e.jsonl \
    -H "Authorization: Bearer $JEZERO_DEVICE_KEY" \
    -H "Content-Encoding: gzip" \
    -H "X-Jezero-Project: billing" \
    --data-binary @-

You should see:

{"ok": true, "device": "laptop", "bytes": 48213}

bytes is the size of the stored file, after decompression.

The checks run in this order: host, key, agent and path, declared size, received size, body decoding, empty body, project.

Overview¶

GET /api/v1/overview?days=14

Counts for a dashboard, over the sources the key may read: the jezero app uses it. It is kept out of MCP so agents do not get one more tool to choose from.

curl -s "https://YOUR-JEZERO/api/v1/overview?days=3" -H "Authorization: Bearer $JEZERO_TOKEN"

You should see:

{
  "ok": true,
  "device": "reader",
  "upload": false,
  "version": "0.1.0.dev0",
  "items": 4,
  "days": ["2026-10-19", "2026-10-20", "2026-10-21"],
  "sources": {
    "agent-claude-code-laptop": {"items": 3, "latest": "2026-10-20T21:23:12+00:00", "daily": [1, 1, 0]},
    "agent-codex-work-mac": {"items": 1, "latest": "2026-10-16T21:23:12+00:00", "daily": [0, 0, 0]}
  },
  "projects": {
    "billing": {"items": 3, "latest": "2026-10-20T21:23:12+00:00"},
    "atlas": {"items": 1, "latest": "2026-10-16T21:23:12+00:00"}
  }
}

When the key's sources match no stored source, the answer has the same shape with nothing in it: "items": 0, the usual days, and empty sources and projects.

Client bundle¶

GET /client/jezero-client.tar.gz

The plugin bundle that computers unpack before running jezero_client.py init: the client core and every plugin. It is public code and needs no key. The file is [server].client_bundle (default dist/jezero-client.tar.gz, relative to the config file), built by python3 scripts/build_clients.py.

curl -fsSL https://YOUR-JEZERO/client/jezero-client.tar.gz | tar -xz -C ~/.jezero-src

OAuth protected resource metadata¶

GET /.well-known/oauth-protected-resource/mcp

Served by the MCP library when require_auth = true, and named in the WWW-Authenticate header of a 401 from /mcp. The path ends with [server].path. Jezero runs no authorization server: keys are static and come from [[clients]], so MCP clients must be given the key as a header.

{
  "resource": "https://YOUR-JEZERO/mcp",
  "authorization_servers": ["https://YOUR-JEZERO"],
  "bearer_methods_supported": ["header"]
}

resource is [server].public_url, or http://HOST:PORT/PATH from [server] when it is not set.

See also¶

• MCP tools: the tools behind /mcp.
• Client: how the client core calls these routes.
• Manage computers and keys: approving devices.
• Deploy: putting the server behind a reverse proxy.