api web api

Web API

Active contributors: Zachary BENSALEM

Base URL and transport

The production launcher in packages/fleet-web/dist/web/launcher.mjs serves the client bundle and API from one Node HTTP server. It binds to loopback by default at 127.0.0.1:3000, accepts only 127.0.0.1, localhost, or ::1 for --host, and accepts ports from 0 through 65535. Port 0 asks the OS for an ephemeral port. Requests with a non-loopback Host or Origin receive 403 Loopback requests only. The source implementation is scripts/prime-agent-web-launcher.mjs.

Development uses pnpm run dev:web, which starts Vite for web/app on port 3000. VITE_FLEET_PI_CHAT_RUNTIME_URL can redirect selected runtime API prefixes when the browser bundle and runtime are served separately; the mapping is implemented in web/app/src/lib/pi/chat-runtime-url.ts.

Two streaming transports share the chat stream event vocabulary:

• POST /api/chat returns newline-delimited JSON with one frame per line.
• GET /api/chat/events returns server-sent events for session pushes, pending dialogs, child-agent streams, and bounded replay.

Authentication

The local web interface has no user authentication. The access boundary is the loopback bind and request-header check, not a bearer token. The server trusts anyone who can reach the local port with the user's workspace and permissions. web/app/src/lib/auth-stub.ts documents this v1 behavior, while the launcher rejects non-loopback hosts before opening the server.

Endpoints

TanStack Start route files under web/app/src/routes/api/ delegate to framework-free handlers exported from web/server/src/index.ts. The handler implementations are under web/server/src/handlers/.

Health

Method	Path	Purpose
GET	/api/health	Reports process liveness, uptime, and per-workspace IPython readiness.

Chat and sessions

Method	Path	Purpose
POST	/api/chat	Submit a turn and receive its NDJSON stream.
POST	/api/chat/abort	Abort the active run and cancel pending dialogs.
POST	/api/chat/new	Create a session, registering the launch project when needed.
POST	/api/chat/resume	Resume a saved session and return its transcript, plans, and presentation.
GET	/api/chat/session	Load a session; with attachmentId, download one managed attachment.
POST	/api/chat/session	Upload multipart attachments for a session.
PUT	/api/chat/session	Upsert a durable Plan-mode presentation.
PATCH	/api/chat/session	Delete a queued steering or follow-up message using an expected-text guard.
GET	/api/chat/sessions	List saved sessions, optionally filtered by projectId.
PATCH	/api/chat/sessions	Rename a session.
DELETE	/api/chat/sessions	Delete a session and its managed Fleet sidecars.
POST	/api/chat/question	Answer a pending extension UI question.
POST	/api/chat/command	Run a server-side session command such as context, export, fork, or reload.
GET	/api/chat/commands	Return the slash-command catalog from built-ins, skills, prompts, and extensions.
POST	/api/chat/model	Change the active session model.
GET	/api/chat/events	Open a session or child-agent SSE stream with optional cursor replay.

Models, resources, settings, and providers

Method	Path	Purpose
GET	/api/chat/models	List all or enabled models, with optional project filtering.
POST	/api/chat/models/discover	Discover models from a custom or OpenAI-compatible provider URL.
GET	/api/chat/resources	List packages, skills, prompts, extensions, themes, and agent files for a cwd.
GET	/api/chat/settings	Return effective global-plus-project Pi settings.
PATCH	/api/chat/settings	Update supported Pi settings fields.
GET	/api/chat/providers	List built-in, custom, and OpenAI-compatible provider rows.
POST	/api/chat/providers	Store a credential or register a custom provider.
DELETE	/api/chat/providers	Remove a credential and managed provider registration.
POST	/api/chat/providers/oauth	Start, poll, continue, or cancel an OAuth login.
PUT	/api/chat/artifacts	Validate and store an OpenUI HTML artifact.

Workspace

Method	Path	Purpose
GET	/api/workspace/tree	Return a bounded workspace-relative file tree.
GET	/api/workspace/file	Read one contained workspace file using path and optional projectId.
GET	/api/workspace/browse	Return 410; workspace-root switching uses /api/projects/browse.
POST	/api/workspace/root	Return 405; the workspace root is fixed when Fleet starts.

Projects

Method	Path	Purpose
GET	/api/projects	List registered projects and sessions with secret-redacted labels.
POST	/api/projects	Register a project from a path or opaque directory token.
PATCH	/api/projects?projectId=	Rename a project.
DELETE	/api/projects?projectId=	Unregister a project without deleting its sessions.
GET	/api/projects/browse	Browse directories with expiring opaque tokens.
POST	/api/projects/fork	Copy a session into another registered project.

Error envelope

web/server/src/wrap-api-handler.ts wraps every handler. Errors are returned as a FleetErrorEnvelope with code, message, optional provider, terminal state, and a remediation action. Codes cover authentication, kernel, context, budget, tool, rate-limit, network, extension, abort, and unknown failures. safeErrorMessage removes local filesystem paths before messages reach the browser. web/app/src/lib/pi/chat-fetch.ts parses the envelope into ChatRequestError.

Streaming semantics

NDJSON frames are single-line JSON objects. readChatStream in web/app/src/lib/pi/chat-fetch.ts splits the response and selectively validates frames; high-frequency delta frames use a fast path. The SSE handler writes a connected frame with adapterCapabilities, then uses the per-channel RingBuffer from web/server/src/ring-buffer.ts. The default capacity is 500 entries, each with a monotonic sequence used as the SSE id.

Clients resume with Last-Event-ID or lastEventId. If the cursor is older than the retained range, the server sends state.agent_settled with resync-required; the browser reloads /api/chat/session instead of replaying or re-running the turn. A first connection also replays still-pending tool-Question frames. Heartbeat comments are emitted every 15 seconds.

One turn

sequenceDiagram
    participant B as Browser
    participant R as Chat route
    participant P as PrimeBridge
    participant D as Prime Agent daemon
    B->>R: POST ChatRequest
    R->>P: Resolve session and validate attachments
    R-->>B: start frame
    R->>P: prompt
    P->>D: promptAndWait
    loop Runtime events
        D-->>P: Agent events
        P-->>R: Mapped ChatStreamEvent
        R-->>B: NDJSON frames
        P-->>B: SSE frames for session-wide updates
    end
    D-->>P: Turn settled
    P-->>R: promptAndWait resolves
    R-->>B: done frame

Loading

Where next

• HTTP handlers explains the server implementation behind these routes.
• API client explains browser requests and stream parsing.
• Chat stream event defines the shared frame vocabulary.
• Daemon protocol describes the upstream calls below the Fleet adapter.