HTTP API

The web viewer exposes an HTTP API on port 8081 (configurable).

Authentication

Most endpoints require session-based authentication. Login via /api/login with OS credentials to receive a session cookie.

Endpoints

Public Endpoints

Method	Path	Auth	Description
GET	/health	PUBLIC	Health check
GET	/login	PUBLIC	Login page
GET	/logout	PUBLIC	Logout page
GET	/api/security-context	PUBLIC	Security context check
POST	/api/login	PUBLIC	Login API
GET	/static/{filename:.*}	PUBLIC	Static files

Protected Endpoints

These endpoints require the auth type shown in the table.

Method	Path	Auth	Description
GET	/api/gateway/health	TOKEN_OR_SESSION	Aggregate gateway + per-user daemon serving health
GET	/api/tunnel	TOKEN_OR_SESSION	Tunnel observability snapshot
GET	/api/state/sessions	TOKEN_OR_SESSION	List monitored sessions
GET	/api/state/sessions/{session_id}	TOKEN_OR_SESSION	Get monitored session
GET	/api/state/sessions/{session_id}/parse	TOKEN_OR_SESSION	Parse session output
GET	/api/state/sessions/{session_id}/capture	TOKEN_OR_SESSION	Get raw terminal content
POST	/api/sessions/wait-any	TOKEN_OR_SESSION	Wait for any session attention
POST	/api/sessions/{session_id}/respond	TOKEN_OR_SESSION	Send input to a session
POST	/api/sessions/{session_id}/exit	TOKEN_OR_SESSION	Exit a session cleanly
POST	/api/sessions/{session_id}/wait	TOKEN_OR_SESSION	Wait for session attention
POST	/api/sessions/{session_id}/inbox	TOKEN_OR_SESSION	Send a text snippet to the inbox
POST	/api/sessions/{session_id}/clipboard	TOKEN_OR_SESSION	Deprecated alias of /inbox
POST	/api/sessions/{session_id}/share	TOKEN_OR_SESSION	Share a document to the inbox
POST	/api/sessions/{session_id}/send	TOKEN_OR_SESSION	Send raw input to a session
POST	/api/sessions/{session_id}/scroll	TOKEN_OR_SESSION	Scroll a session (copy-mode)
GET	/auth/token/{token}	MAGIC_LINK	Magic link login
GET	/api/machines	SESSION	List known machines
POST	/api/machines/validate	SESSION	Validate a remote machine before adding
POST	/api/logout	SESSION	Logout
POST	/api/auth/logout-user	TOKEN_OR_SESSION	End all web sessions of the calling user
GET	/api/auth/sessions	TOKEN_OR_SESSION	List the calling user's live web login sessions
GET	/api/whoami	SESSION	Get current user
GET	/api/login-token	API_TOKEN	Generate magic link
POST	/api/log	SESSION	Remote logging
GET	/api/sessions	STATUS_COOKIE	List tmux sessions
GET	/api/session/{session_id}	SESSION	Get session details
GET	/api/capture/{session_id}	TOKEN_OR_SESSION	Capture session as PNG
GET	/api/scroll/{session_id}	TOKEN_OR_SESSION	Capture scrollback as PNG
GET	/api/inbox/{session_id}	TOKEN_OR_SESSION	List/clear notification inbox
DELETE	/api/inbox/{session_id}	TOKEN_OR_SESSION	List/clear notification inbox
GET	/api/clipboard/{session_id}	TOKEN_OR_SESSION	Deprecated alias of /api/inbox
DELETE	/api/clipboard/{session_id}	TOKEN_OR_SESSION	Deprecated alias of /api/inbox
POST	/api/mail/{session_id}	TOKEN_OR_SESSION	Agent mailbox: send / peek / clear
GET	/api/mail/{session_id}	TOKEN_OR_SESSION	Agent mailbox: send / peek / clear
DELETE	/api/mail/{session_id}	TOKEN_OR_SESSION	Agent mailbox: send / peek / clear
POST	/api/mail/{session_id}/get	TOKEN_OR_SESSION	Agent mailbox: pop next message
POST	/api/mail/{session_id}/wait	TOKEN_OR_SESSION	Agent mailbox: long-poll for a message
GET	/api/fs/complete	SESSION	Autocomplete working directory
GET	/api/fs/list/{session_id}	TOKEN_OR_SESSION	List files in the session's project dir
GET	/api/fs/read/{session_id}	TOKEN_OR_SESSION	Read a file from the session's project dir
GET	/api/fs/raw/{session_id}	TOKEN_OR_SESSION	Raw file bytes from the session's project dir (inline; ?download=1 to save)
POST	/api/resize/{session_id}	TOKEN_OR_SESSION	Resize terminal
POST	/api/upload/{session_id}	TOKEN_OR_SESSION	Upload file to session cwd
POST	/api/sessions/create	TOKEN_OR_SESSION	Create session (web or CLI)
POST	/api/sessions/{session_id}/terminate	TOKEN_OR_SESSION	Terminate session (web or CLI)
GET	/api/session-configs	SESSION	Get session configs
DELETE	/api/session-configs/{index}	SESSION	Delete session config
GET	/	SESSION	Main app
GET	/session/{session_name}	SESSION	Session deep link
GET	/session/{session_name}/scrollback	SESSION	Session scrollback deep link
GET	/session/{session_name}/keyboard	SESSION	Session keyboard deep link
GET	/session/{session_name}/passenger	SESSION	Session passenger deep link
GET	/tunnel	SESSION	Tunnel status page
GET	/api/code/status	TOKEN_OR_SESSION	VS Code Web availability for the calling user
GET	/api/code/status/{session_id}	TOKEN_OR_SESSION	VS Code Web availability + deep link for one session
POST	/api/code/stop	TOKEN_OR_SESSION	Stop the calling user's VS Code Web backend
GET	/code/{username}	SESSION	VS Code Web (redirect to trailing slash)
ANY	/code/{username}/{tail:.*}	SESSION	VS Code Web (proxied serve-web)
GET	/ws/{session_id}	SESSION_SAME_ORIGIN	WebSocket streaming
GET	/api/github/status/{session_id}	TOKEN_OR_SESSION	GitHub repo link for a session's workdir

Endpoint Details

GET /health

Liveness check endpoint. Success and error envelopes are defined by agentwatch/server/utils/responses.py.

Response:

{
  "s": "ok",
  "client_version": "2026070618",
  "server_version": "0.62.0"
}

POST /api/login

Authenticate with OS credentials.

Request:

{
  "username": "user",
  "password": "password",
  "force": false
}

Response:

{
  "success": true,
  "username": "user"
}

If another session exists and force is false:

{
  "success": false,
  "session_exists": true,
  "existing_session": {
    "ip": "192.168.1.100",
    "hostname": "other-device.local",
    "location": "Local Network"
  }
}

GET /api/sessions

List all tmux sessions with detection info.

Response:

{
  "hostname": "macbook",
  "sessions": [
    {
      "session_id": "$0",
      "session_name": "coding-0",
      "created_at": 1707321600,
      "attached": false,
      "windows": 1,
      "cwd": "/home/user/project",
      "program": "Claude Code",
      "state": "Idle"
    }
  ]
}

GET /api/capture/{session_id}

Capture terminal as PNG image.

Response: image/png

GET /api/scroll/{session_id}

Capture scrollback buffer.

Query Parameters: - max_lines: Maximum lines to capture (default: 500, max: 2000)

Response:

{
  "type": "scroll_response",
  "png_base64": "iVBORw0KGgo...",
  "total_lines": 500,
  "pane_height": 24,
  "history_size": 2000,
  "cols": 80,
  "retina": true
}

POST /api/resize/{session_id}

Resize terminal dimensions.

Request:

{
  "cols": 120,
  "rows": 40
}

Response:

{
  "s": "ok",
  "cols": 120,
  "rows": 40
}