Jellyfish API Reference

Jellyfish is the backend service that powers ClearBot’s water-cleaning robots. It exposes three independent APIs that share a single authentication model:

Surface	Path / URL	When to use
GraphQL	`POST /graphql` (`wss://…/graphql` for subscriptions)	Most dashboard & admin flows. Strongly typed schema, introspection, single round-trip queries.
REST	`/user/`, `/robot/`, `/cloud/`, `/dashboard/`, `/report/*`	Authentication (login, passkeys, password reset), robot telemetry ingest, S3 signed URLs, and PDF report generation.
WebSocket	`ws://<host>:4001/ws`	Live robot telemetry (`LiveStatus`, `BatteryStatus`, `LidarScan`, `HardwareStatus`, `DongleStatus`, `ePropulsionMotor`, `GenericDataChannelMessage`).

Every spec on this site is generated automatically from the source code on every deploy. If a change is shipped to main and the spec doesn’t update, open an issue.

Quick links

REST — Live Swagger UI, openapi.json (raw spec)
GraphQL — Schema reference (auto-generated), Apollo Sandbox embedded in non-production deployments
WebSocket — AsyncAPI viewer, asyncapi.yaml (raw spec)

Authentication overview

Users authenticate with a session token returned by /user/login (or /user/login-verify for passkeys). Send it as the Authorization header or as the session-token cookie.
Robots authenticate with a crat-… bearer token sent in the Authorization header — see /robot/*.
GraphQL uses the same Authorization header or session-token cookie.
AMQP (out of scope here) uses RABBITMQ_USERNAME / RABBITMQ_PASSWORD.

Project layout


src/
  routes/        Express routers  → REST API → OpenAPI
  resolvers/     TypeGraphQL      → GraphQL API → SDL
  socketserver/  raw ws messages  → WebSocket API → AsyncAPI
docs/            this site