API Overview

The NimbleBrain HTTP API gives you programmatic access to chat, apps, conversations, tools, and real-time events. Every endpoint uses JSON over HTTP and follows consistent conventions.

Base URL

http://localhost:27247

The default port is 27247. Override it with the --port flag or the http.port field in nimblebrain.json.

Content Type

All request and response bodies use application/json. Set the Content-Type header on every request that includes a body:

Content-Type: application/json

SSE endpoints (/v1/chat/stream and /v1/events) return text/event-stream.

Authentication

NimbleBrain uses pluggable auth adapters configured via instance.json. Three modes:

• Dev (default) — no authentication when no instance.json exists
• Local — per-user API keys with Bearer token or session cookie
• OIDC — JWT verification via WorkOS or any OIDC provider

See Authentication for full details.

Error Format

All errors return a JSON object with an error field and an optional message field:

{
  "error": "not_found",
  "message": "App \"weather\" not found"
}

Common error codes:

error Value	HTTP Status	Meaning
"bad_request"	400	Invalid request body or parameters
(empty body)	401	Authentication failed
"protected"	403	Bundle is protected from uninstall
"not_found"	404	Resource does not exist
"already_installed"	409	Bundle is already installed
"install_failed"	500	Bundle installation failed
"credentials_required"	400	Bundle needs API keys in the env field

Validation errors on request bodies return a 400 with a descriptive error or message string:

{
  "error": "message is required and must be a string"
}

Endpoint Reference

Every endpoint requires authentication unless noted otherwise.

Method	Path	Auth	Description
GET	/v1/health	No	Health check
GET	/v1/bootstrap	Yes	Bootstrap — user, workspaces, shell config
POST	/v1/chat	Yes	Synchronous chat
POST	/v1/chat/stream	Yes	Streaming chat (SSE)
GET	/v1/apps/:name/resources/:path	Yes	Fetch a UI resource
POST	/v1/tools/call	Yes	Direct tool invocation
GET	/v1/shell	Yes	Shell configuration (placements, endpoints) — requires X-Workspace-Id
GET	/v1/files/:fileId	Yes	Serve an uploaded file
GET	/v1/events	Yes	Workspace SSE event stream
GET	/v1/auth/provider	No	Auth adapter info (local, oidc, or dev)
GET	/v1/auth/authorize	No	OIDC authorization redirect
GET	/v1/auth/callback	No	OIDC callback handler
POST	/v1/auth/login	No	Validate credentials, set session cookie
POST	/v1/auth/logout	Yes	Clear session cookie
GET	/v1/auth/session	Yes	Check session validity
POST	/v1/auth/refresh	Yes	Refresh session token
POST GET DELETE	/mcp	Yes	MCP server endpoint (Streamable HTTP)

CORS

CORS behavior depends on your configuration:

• Dev mode (no auth configured) — Access-Control-Allow-Origin: *
• Auth configured with ALLOWED_ORIGINS — only listed origins get CORS headers, with Access-Control-Allow-Credentials: true for cookie support
• Auth configured without ALLOWED_ORIGINS — same-origin only (no CORS headers)

The server handles OPTIONS preflight requests automatically with a 204 No Content response.

SSE Streams

The API exposes two Server-Sent Events streams:

1. Chat stream (POST /v1/chat/stream) — per-request stream of chat events. Events: text.delta, tool.start, tool.done, done, error. See Chat.
2. Workspace stream (GET /v1/events) — persistent connection for workspace-level events. Events: bundle.installed, bundle.uninstalled, bundle.crashed, bundle.recovered, bundle.dead, data.changed, config.changed, skill.created, skill.updated, skill.deleted, file.created, file.deleted, bridge.tool.call, bridge.tool.done, heartbeat. See Events.