API Reference

Fleet exposes a REST API at http://localhost:3000/api. All request and response bodies use JSON unless otherwise noted.

Sessions

List Sessions

GET /api/sessions

Returns all sessions with live status merged from running instances.

Response (200):

[
  {
    "instanceId": "uuid",
    "workspaceId": "uuid",
    "workspaceDirectory": "/home/dev/my-project",
    "workspaceDisplayName": "My Project",
    "isolationStrategy": "worktree",
    "sessionStatus": "idle",
    "instanceStatus": "running",
    "dbId": "uuid",
    "session": {
      "id": "opencode-session-id",
      "title": "Implement auth module"
    }
  }
]

Create Session

POST /api/sessions

Request body:

Field	Type	Required	Description
directory	string	Yes	Absolute path to the workspace directory
title	string	No	Session title (default: "New Session")
isolationStrategy	"existing" | "worktree" | "clone"	No	Workspace isolation (default: "existing")
branch	string	No	Git branch for worktree/clone
onComplete	object	No	Callback config: { notifySessionId, notifyInstanceId }

Response (200):

{
  "instanceId": "uuid",
  "workspaceId": "uuid",
  "session": {
    "id": "opencode-session-id",
    "title": "Implement auth module"
  }
}

Get Session Detail

GET /api/sessions/{id}?instanceId={instanceId}

Returns session data with messages and workspace metadata.

Response (200):

{
  "session": { "id": "...", "title": "..." },
  "messages": [],
  "workspaceId": "uuid",
  "workspaceDirectory": "/home/dev/my-project",
  "isolationStrategy": "existing"
}

Rename Session

PATCH /api/sessions/{id}

Request body:

{ "title": "New Title" }

Response (200):

{ "id": "uuid", "title": "New Title" }

Errors: 400 if title is missing or empty, 404 if session not found.

Terminate Session

DELETE /api/sessions/{id}?instanceId={instanceId}

Optional query parameters:

Parameter	Description
cleanupWorkspace	Set to true to delete the worktree/clone directory
permanent	Set to true to permanently remove from database

Response (200):

{ "message": "Session terminated" }

Send Prompt

POST /api/sessions/{id}/prompt

Request body:

{
  "instanceId": "uuid",
  "text": "Your prompt here",
  "agent": "shuttle"
}

The agent field is optional. Returns 204 No Content.

Abort Session

POST /api/sessions/{id}/abort?instanceId={instanceId}

Response (200):

{ "message": "Session aborted" }

Resume Session

POST /api/sessions/{id}/resume

Response (200):

{
  "instanceId": "uuid",
  "session": { "id": "...", "title": "..." }
}

Session Events (SSE)

GET /api/sessions/{id}/events?instanceId={instanceId}

Server-Sent Events stream. Each event is JSON:

data: {"type": "session.status", "properties": {...}}

Event types include session.status, session.idle, part.*, message.*, error, and permission.*. The connection sends keepalive comments every 15 seconds.

Session Messages (Paginated)

GET /api/sessions/{id}/messages?instanceId={instanceId}&limit=50&before={messageId}

Parameter	Default	Description
limit	50	Max messages to return (max 200)
before	—	Cursor for pagination (message ID)

Session Diffs

GET /api/sessions/{id}/diffs?instanceId={instanceId}

Response (200):

[
  {
    "file": "src/auth.ts",
    "before": "...",
    "after": "...",
    "additions": 15,
    "deletions": 3,
    "status": "modified"
  }
]

Session History

GET /api/sessions/history

Parameter	Default	Description
search	—	Full-text search on title
status	—	Filter by status
from	—	Start date (ISO 8601)
to	—	End date (ISO 8601)
limit	20	Max results (max 100)
offset	0	Pagination offset

Response (200):

{
  "sessions": [
    { "id": "...", "title": "...", "status": "completed" }
  ],
  "total": 42
}

---

Workspaces

Rename Workspace

PATCH /api/workspaces/{id}

Request body:

{ "displayName": "My Project" }

Response (200):

{ "id": "uuid", "displayName": "My Project" }

---

Workspace Roots

List Workspace Roots

GET /api/workspace-roots

Response (200):

{
  "roots": [
    { "id": null, "path": "/home/user", "source": "env", "exists": true },
    { "id": "uuid", "path": "/home/user/projects", "source": "user", "exists": true }
  ]
}

Add Workspace Root

POST /api/workspace-roots

Request body:

{ "path": "/absolute/path" }

Response (201):

{ "id": "uuid", "path": "/resolved/path" }

Remove Workspace Root

DELETE /api/workspace-roots/{id}

Only user-added roots (source: "user") can be removed. Environment roots cannot be deleted.

Response (200):

{ "ok": true }

---

Directories

Browse Directories

GET /api/directories?path={absolutePath}&search={term}

Lists subdirectories within an allowed workspace root. Omit path to list the roots themselves.

Response (200):

{
  "entries": [
    { "name": "my-project", "path": "/home/user/my-project", "isGitRepo": true }
  ],
  "currentPath": "/home/user",
  "parentPath": null,
  "roots": ["/home/user"]
}

Noise directories (.git, node_modules, .next, etc.) and hidden directories are excluded.

---

Instances

List Commands

GET /api/instances/{id}/commands

Response (200):

[
  { "name": "compact", "description": "Compact the conversation" }
]

List Agents

GET /api/instances/{id}/agents

Response (200):

[
  { "name": "shuttle", "description": "...", "mode": "code", "color": "#..." }
]

Find Files

GET /api/instances/{id}/find/files?query={searchTerm}

Fuzzy-search files in the instance's workspace. Returns up to 20 results. Query max 256 characters.

Response (200): string[] (file paths)

---

Notifications

List Notifications

GET /api/notifications?unread=true&limit=50

Response (200): Array of notification objects.

Mark Notification Read

PATCH /api/notifications/{id}

Use id=all to mark all notifications as read.

Response (200):

{ "success": true }

Delete All Notifications

DELETE /api/notifications

Response (200):

{ "deleted": 5 }

Unread Count

GET /api/notifications/unread-count

Response (200):

{ "count": 3 }

Notification Stream (SSE)

GET /api/notifications/stream

Real-time notification delivery via Server-Sent Events:

data: {"type": "notification", "notification": {...}}

---

Fleet

Fleet Summary

GET /api/fleet/summary

Response (200):

{
  "activeSessions": 2,
  "idleSessions": 1,
  "totalTokens": 0,
  "totalCost": 0,
  "queuedTasks": 0
}

---

Config

Get Config

GET /api/config

Returns user-level Weave config, installed skills, and config file paths.

Update Config

PUT /api/config

Request body: Full or partial config object (must include agents key).

Response (200):

{ "ok": true }

---

Skills

List Skills

GET /api/skills

Response (200):

{ "skills": [] }

Install Skill

POST /api/skills

Request body:

{ "url": "https://...", "agents": ["shuttle"] }

Or install from content directly:

{ "content": "# Skill content...", "agents": ["shuttle"] }

Response (201):

{ "ok": true, "skill": {} }

Remove Skill

DELETE /api/skills/{name}

Response (200):

{ "ok": true }

---

Version

Get Version

GET /api/version

Response (200):

{
  "version": "0.5.0",
  "latest": "0.5.0",
  "updateAvailable": false,
  "checkedAt": "2026-03-05T10:30:00.000Z"
}

---

Open Directory

Open in Editor / Terminal

POST /api/open-directory

Request body:

{
  "directory": "/absolute/path",
  "tool": "vscode"
}

Allowed tools: vscode, cursor, terminal, explorer.

Response (200):

{ "ok": true }