QSCSCore HTTP API, Overview
On this page 1 sections
QSCSCore HTTP API
The QSCSCore HTTP API is the public, language-agnostic surface of the daemon. It exposes the cluster's identity service, replicated state engine, and origin-aware request handling over a single stable HTTP contract that every node in the cluster speaks identically. What one node can serve, every node can serve, including during partitions and origin outages.
This document covers the public HTTP API only, the routes and headers any client, browser, or service can rely on. The internal control-panel API and the encrypted inter-node replication protocol on :4443 are separate contracts and are not described here.
What the API gives you
Identity Gating
Issue a QSCS identity with a single POST /auth/login. The server returns an opaque identity UUID that the client sends back as a header on subsequent requests, there are no auth cookies, no Set-Cookie headers, and no browser-bound session state. Identities are cluster-replicated and can gate any upstream origin via Auth=identity; GET /api/identity/status lets services verify an identity by UUID without re-authenticating.
Cluster-wide state, by HTTP
Cache, identities, and session state converge across every node automatically. A request that lands on any node sees the same view, including identities or cache entries created on another continent seconds ago, the API itself is your read-and-write handle on that converged state.
Direct state manipulation
The same routes that serve traffic also let services read and mutate cache and identity state directly, you can run QSCSCore purely as a replicated state and identity engine and never use it as an HTTP origin proxy at all. The replication layer underneath is transport-agnostic, so deployments that prefer their own front-end (gRPC, raw TCP, message queue) can drive the cluster through the API and ignore the HTTP gateway entirely.
HEADLESS resilience
When an origin is unreachable, the API keeps serving the last known good response from any node in the mesh. Mutating requests receive a structured JSON soft-fail with retry guidance instead of a hard 502, so client code has a stable shape to handle regardless of upstream state.
Single-port ingress
One TCP port (default 8080) handles all public HTTP traffic, identity auth, OPTIONS / CORS preflight, and static asset delivery. No sidecars, no service mesh, no separate auth gateway in front.
Self-describing responses
Every response carries X-QSCS-* headers that expose cache mode, node identity, headless reason and timing, enough for a client to make routing, retry, and consistency decisions without a second round-trip. A loopback-only Prometheus exporter at /qscs/metrics mirrors the same signal in scrape form.
Adaptable by design
QSCSCore is built to fit the shape of your platform rather than the other way around. The HTTP API is the most direct way to talk to it, but the daemon underneath is a replicated state engine first and an HTTP gateway second, you can use as much or as little of the HTTP surface as suits your stack:
- Full gateway. Point public traffic at
:8080and let QSCSCore terminate, authenticate, cache, replicate, and proxy upstream. - Identity-only. Run QSCSCore as a federated, cookie-free identity service for an existing application stack, auth against
/auth/login, verify with/api/identity/status, ignore the proxy paths entirely. - State engine only. Use the API to read and write replicated state, treat the daemon as a key-value substrate that already solves replication, partition tolerance, and cross-region convergence for you, and ship traffic over whatever transport you prefer.
Stable wire contract
Route paths and the X-QSCS-* response header set are stable within a major version. New headers may be added; existing ones do not change meaning until the next major release. The encrypted inter-node replication protocol on :4443 is binary and intentionally not part of this HTTP API, applications and humans talk to :8080, peers talk to :4443.