Docs / Developers / API reference

API reference

CloudyBot exposes a REST API for dashboard-style integrations: sign up or log in, create threads, send chat, and read usage. The canonical interactive spec is /api-docs (OpenAPI 3.1 + Swagger UI). This page explains how the pieces fit together; request/response schemas live in the spec.

Open interactive API reference

Base URL and format

Production — https://cloudybot.ai (same host as the dashboard).
Self-hosted — default http://localhost:3000 from api/.env PORT.
JSON for most routes; POST /chat may return JSON or SSE (text/event-stream) depending on server config.

Authentication

User 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-only diagnostics use X-Admin-Token and are not for end-user apps.

Core endpoints (integrator path)

Typical sequence:

POST /api/auth/login → session token.
POST /api/threads → threadId (optional title).
POST /chat with message and threadId (optional attachmentFileIds, model, fastMode).
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 facts per thread: GET/PUT/DELETE /api/user/memory?threadId=… — see memory model.

What the spec documents

Health — GET /health, GET /health/ready, GET /health/openclaw.
Auth & account — signup, login, password reset, email verification flows.
Chat & threads — POST /chat, thread list/create/rename/delete, history, clear.
Usage & billing — GET /usage/me (plan bucket AI credits; wallet top-ups may appear separately in the dashboard).
Referrals — signup attribution and bonus credit hooks where enabled.
Real-time UI — GET /api/events (SSE) for async dashboard updates.

Browser sessions (/api/browser/*), integration status routes, and skill-specific connectors are documented in repo docs/API-REFERENCE.md and feature READMEs; some are omitted from the public OpenAPI surface.

Errors and limits

Common chat failures:

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 (AI credits, browser minutes, retention) come from plans.js — limits FAQ. Successful chat responses include usage.remaining / remainingTasks task-equivalent credits.

Architecture context

POST /chat hits the CloudyBot API first; an optional OpenClaw gateway runs the agent loop and tools. Memory is scoped per threadId, not globally per user. Flow diagram and data stores: architecture overview.

Related: /api-docs (canonical spec) · Developers hub · repo docs/API-REFERENCE.md · First task guide