API reference
Your instance exposes an HTTP + WebSocket API under /.cial/api. The web UI runs on it, cial-cli wraps it for the agent, and you can call it directly. REST lives under /.cial/api/v1/*; live chat and team activity flow over a single WebSocket.
Prefer cial-cli for scripting — it carries auth for you and covers every route (cial-cli sessions list, cial-cli self deploy, …). The agent gets a short-lived per-turn bearer (cial_at_…); browser calls are authenticated as the instance owner by the Citadel edge. The self-edit + recovery routes are additionally loopback-guarded. The full contract is downloadable as OpenAPI 3.1 — import it into Postman, Insomnia, or a codegen client.
Sessions
Create, list and drive chat sessions, their message history, and the background tasks a turn spawns. REST-created sessions broadcast over the WS so they appear live in the sidebar.
Knowledges
Instance-wide, filesystem-backed knowledge bases with per-knowledge instructions and a files tree, injected as harness context.
Tools & vault
Two-tier tool/secret vault — instance-wide and per-owner env-var, MCP, and markdown tools whose secret config is masked in responses and only readable via the manage-gated config endpoint.
Uploads
Store and retrieve per-owner attachment files in a sandboxed on-disk uploads directory.
Skills
Enumerates the instance's on-disk `.claude/skills` and `.claude/commands` catalog for the composer's slash-command autocomplete.
Model accounts
Manage the Anthropic and Kimi model-provider credentials (API keys and Anthropic OAuth) the harness uses, scoped per-user or instance-wide.
Discovery
Per-user feature visibility (Cial Discovery): the surface registry plus each user's resolved on/off state, with live re-broadcast on toggle.
Profile
Reads the owner's full managed identity (name, avatar, contact, team and billing/trial) from the cial-app control plane, degrading to an unmanaged fallback off-platform.
Billing
Display-only tier view for the in-instance billing badge, resolved control-plane side from the cial-app managed-instance API.
Push notifications
Web Push subscription management and VAPID public-key discovery for owner-authed devices.
Channel media
Instance-side proxy that fronts the Citadel blob plane so channel message images can be uploaded and re-served per member instance.
Binding
Discover, create, grant and delete the binding repos this instance can switch its code line to, proxied server-side to the cial-app control plane.
Self-edit
Loopback-only self-edit API the agent's CLI skills curl to rebuild, restart, roll back, and commit the instance's own source.
Recovery
Bundle-independent client-failure recovery page and served-dist rollback for a white-screened-but-authenticated instance.
System & health
Liveness and resource-usage telemetry for this instance container — CPU, memory and data-volume metrics plus a runtime liveness probe.
Realtime
One socket carries everything live — turns and their streaming output, the team channel, presence, and shared sessions.
Live: the WebSocket
One socket — wss://{slug}.cial.app/.cial/api/ws — carries everything live: sending turns and streaming their output, the team channel, presence, and shared sessions. It is a real instance-content channel, so on a managed instance the upgrade is rejected unless it presents the verified owner identity. The typed client lives in the SDK; see Sessions & harnesses and Collaboration.