API Server (pocketpaw serve)

The pocketpaw serve command starts PocketPaw as a headless API server without the web dashboard frontend. It exposes the full REST API and WebSocket endpoints, making it ideal for:

• The desktop client (Tauri app) connecting over localhost
• Custom scripts and automation
• External integrations that only need the API
• Docker and headless server deployments

Quick Start

# Start the API server (default: localhost:8888)
pocketpaw serve

# Custom host and port
pocketpaw serve --host 0.0.0.0 --port 9000

# Development mode with auto-reload
pocketpaw serve --dev

What’s Included

The API server starts the full PocketPaw backend:

The only difference from the default pocketpaw command is that no HTML/CSS/JS frontend is served. All API endpoints work identically.

Authentication

The API server supports multiple authentication methods:

Master Token

On first run, PocketPaw generates a master access token saved at ~/.pocketpaw/access_token. Use it as a Bearer token:

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8888/api/v1/health

Session Tokens

Exchange the master token for a short-lived session token:

# Get a session token
curl -X POST http://localhost:8888/api/v1/auth/session \
  -H "Authorization: Bearer YOUR_MASTER_TOKEN"

# Response: { "session_token": "uuid:hmac_signature" }

API Keys

Create scoped API keys for long-lived access:

# Create an API key
curl -X POST http://localhost:8888/api/v1/auth/api-keys \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-script", "scopes": ["chat", "sessions"]}'

# Response includes the key (shown once): { "key": "pp_xxxx...", "id": "..." }

OAuth2 (PKCE)

For desktop and third-party apps, use the OAuth2 PKCE flow:

1. GET /api/v1/oauth/authorize?client_id=...&code_challenge=...
2. User approves consent
3. POST /api/v1/oauth/token with authorization code
4. Use the returned access token (ppat_* prefix)

Localhost Bypass

By default, requests from 127.0.0.1 or ::1 skip authentication. Disable this with:

export POCKETPAW_LOCALHOST_AUTH_BYPASS=false

API Endpoints

All endpoints are prefixed with /api/v1/. Here’s a summary by category:

Chat

Sessions

Settings

Memory

Health & Diagnostics

Identity

Channels

MCP Servers

Skills

Reminders & Intentions

Backends

Kits (Command Centers)

Files

Remote Access

Events (SSE)

WebSocket

Connect to the WebSocket for real-time streaming:

const ws = new WebSocket('ws://localhost:8888/api/v1/ws?token=YOUR_TOKEN');

// Send a chat message
ws.send(JSON.stringify({
  type: 'chat',
  content: 'Hello, PocketPaw!',
  session_id: 'my-session'
}));

// Receive streaming responses
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // data.type: 'chunk', 'stream_end', 'tool_start', 'tool_result', 'thinking', 'error'
};

WebSocket paths: /ws, /api/v1/ws, /v1/ws (all equivalent).

Comparison: serve vs Default Mode

OpenAPI Documentation

When the API server is running, interactive API docs are available at:

• Swagger UI: http://localhost:8888/api/v1/docs
• ReDoc: http://localhost:8888/api/v1/redoc
• OpenAPI JSON: http://localhost:8888/api/v1/openapi.json