API reference

Interactive OpenAPI 3.1 documentation for CloudyBot’s public HTTP API. The spec below is loaded from /openapi.yaml (source of truth in the repo: docs/openapi.yaml). Use Swagger UI to browse schemas, try requests against production or your local server, and filter by tag.

Prose companion: For narrative walkthroughs, edge cases, and routes omitted from this subset, see developer API reference and repo docs/API-REFERENCE.md. Product setup → getting started · architecture → developers hub.

Base URL and format

Production — https://cloudybot.ai (same host as the dashboard).
Local dev — http://127.0.0.1:3000 (default PORT in api/.env).
JSON for most routes; POST /chat may return JSON or SSE (text/event-stream) depending on server configuration.

Authentication

User-facing routes require Authorization: Bearer <session token>. Obtain a token from POST /api/auth/signup or POST /api/auth/login. The API derives userId from the session only — a mismatched userId in POST /chat returns 400. There is no separate public API-key product today; integrations reuse the same session model as the web dashboard.

Admin diagnostics (X-Admin-Token) and internal lean-agent routes are intentionally excluded from this OpenAPI surface.

Quick start (integrator path)

GET /health — confirm the process is alive; GET /health/ready — database ready.
POST /api/auth/login → session token.
POST /api/threads → threadId (optional title).
POST /chat with message and threadId.
GET /api/chat/history?threadId=… for transcript replay; GET /usage/me for remaining AI credits.

Thread CRUD: GET /api/threads, PATCH /api/threads/:id, DELETE /api/threads/:id. Pinned memory per thread: GET/PUT/DELETE /api/user/memory?threadId=… — see memory model.

What this spec includes

Tags in the OpenAPI file map to integrator-facing routes:

Health — liveness, readiness, optional OpenClaw gateway probe.
Auth — signup, login, password reset, email verification.
Threads & Chat — thread list/create/rename/delete, POST /chat, history, clear.
Usage — GET /usage/me (plan bucket AI credits; wallet top-ups may appear separately in the dashboard).
Referral — signup attribution and bonus credit hooks where enabled.

Real-time dashboard updates may also use GET /api/events (SSE). Browser sessions (/api/browser/*), skill-specific connectors, and webhooks are documented in repo docs/API-REFERENCE.md and feature READMEs — not all are published here.

Common errors

401 — missing or invalid Bearer token.
400 — missing threadId/message, moderation block, or context limit.
404 — thread not found or not owned by the session user.
429 — plan rate limit (requests/hour + burst) or AI credit cap exhausted.

Plan caps come from plans.js — limits FAQ. Successful chat responses include usage.remaining / remainingTasks task-equivalent credits.

Interactive spec

Use the filter box in Swagger UI to jump to a path. Click Authorize, paste your Bearer token, then Try it out on individual operations. Status and incident history → status page.