API Overview

The Snippbot API is a REST API served by the local daemon. All endpoints are available at http://{host}:{port}/api (default: http://localhost:18781/api).

Authentication

All API requests (except health checks and the bootstrap check) require a Bearer token in the Authorization header.

curl http://localhost:18781/api/agents \
  -H "Authorization: Bearer snip_your_api_key_here"

Token types

Type	Prefix	Description
API key	`snip_`	Long-lived, for CLI/automation
Session token	`sess_`	24-hour session from username/password login

Create an API key via:

Setup wizard (Step 3 — Account tab → API Key)
Settings → API Keys in the web UI
POST /api/auth/keys endpoint

Base URL

http://localhost:18781/api

For VM or server installations (custom host/port):

http://{SNIPPBOT_HOST}:{SNIPPBOT_PORT}/api

Request format

All request bodies use Content-Type: application/json
Dates use ISO 8601 format: 2026-03-01T09:00:00Z
IDs use prefixed strings: proj_abc123, agt_xyz789

curl -X POST http://localhost:18781/api/projects \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "AI Framework Research", "description": "Research top 5 AI frameworks"}'

Response format

All responses return JSON. Successful responses include the resource directly or wrapped in a result object:

// Single resource
{ "id": "proj_abc123", "status": "pending", ... }

// List resource
{ "items": [...], "total": 42 }

Error format

Errors follow a consistent structure:

{
  "error": "not_found",
  "message": "Project proj_abc123 not found",
  "status": 404
}

HTTP Status	Error code	Meaning
`400`	`bad_request`	Invalid request body or parameters
`401`	`unauthorized`	Missing or invalid auth token
`403`	`forbidden`	Token valid but insufficient permissions
`404`	`not_found`	Resource does not exist
`409`	`conflict`	State conflict (e.g., approving a non-pending project)
`422`	`validation_error`	Valid JSON but invalid field values
`500`	`internal_error`	Server error

Streaming (SSE)

Chat and some execution endpoints use Server-Sent Events for streaming responses:

curl http://localhost:18781/api/chat/messages/stream \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello", "conversation_id": "conv_abc123"}' \
  --no-buffer

SSE events use the format:

event: token
data: {"content": "Hello"}

event: done
data: {"total_tokens": 42}

WebSocket

Two WebSocket endpoints are available:

Endpoint	Description
`ws://localhost:18781/ws/events`	Main event bus — real-time updates
`ws://localhost:18781/device/ws`	Device connection protocol
`ws://localhost:18781/api/browser/stream`	Browser viewport live stream

Connect with a token in the query string:

ws://localhost:18781/ws/events?token=snip_your_key

API endpoints

Group	Base path	Description
Auth	`/api/auth`	Bootstrap, register, login, API keys
Chat	`/api/chat`	Conversations, streaming messages
Projects	`/api/projects`	Project CRUD, plan, approve, execute
Agents	`/api/agents`	Agent CRUD
Memory	`/api/memory`	Episodes, clusters, search, graph
Scheduler	`/api/scheduler`	Jobs CRUD, runs, NL parsing
Workflows	`/api/workflows`	Workflow CRUD, templates, execute
Devices	`/api/devices`, `/api/device-groups`	Device pairing, groups, health
Browser	`/api/browser`	CDP automation, screenshots
Sandbox	`/api/sandbox`	Container management, config
Hooks	`/api/hooks`, `/api/webhooks`	Event hooks, webhooks
Channels	`/api/channels`	Platform config, bindings
Settings	`/api/settings`	All settings CRUD
Monitor	`/api/monitoring`, `/health`	Usage, alerts, health, metrics
Files	`/api/files`	Upload, download, delete
Providers	`/api/providers`	AI model provider keys