HTTP API Overview & Requests
On this page 13 sections
- QSCSCore HTTP API
- Base URL and transport
- Endpoint index
- Origin resource requests
- Methods and request requirements
- Routing and authentication
- Cache and representation rules
- Ordinary JSON and negotiated deltas
- GET /{api-path} with streaming
- Request example
- Response and compatibility rules
- GET /qscs/metrics
- Integration sequence
QSCSCore HTTP API
Reference for the current QSCSCore HTTP listener: authentication, origin traffic, response metadata, browser runtime files and failure handling. Backends may use any language. Examples marked HTTP show wire formats; shell/curl examples are terminal commands. Browser JavaScript helpers are optional client implementations.
Base URL and transport
Use your configured origin, for example https://app.example.com. Preserve its public hostname, path and query through the reverse proxy. The daemon’s default HTTP port is 8080; provide HTTPS at the public edge. Each origin has its own routing and identity policy. There is no universal /api/v1 prefix.
Shell / curl — runtime configuration on a registered origin
curl -i 'https://app.example.com/.qscs/browser/config.json'
Example HTTP response — selected headers
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{"enabled":true,"version":1}
Endpoint index
| Method and path | Purpose | Authentication / result |
|---|---|---|
POST /auth/login | Register a client key after account authentication. | Signed with the public key supplied in the JSON body; HTTP 200 with ok. |
POST /auth/logout | Remove the current origin binding. | Signed with the existing key; HTTP 200 with ok and erased on success. |
GET /auth/status | Inspect the caller’s origin binding. | UUID header; lookup only. HTTP 200 JSON or conditional 304. |
GET /auth/federation | Discover managed API recipients for this issuer. | Public; HTTP 200 JSON. |
GET /api/identity/status?uuid=… | Inspect a record in this node’s identity store. | Public diagnostic lookup; HTTP 200 JSON, including lookup errors. |
GET /api/identity/federated-binding?audience=… | Issuer lookup used by recipient nodes. | Original recipient-bound request proof and explicit federation policy; see authentication reference. |
GET /{application-path} | Read an origin resource; optionally negotiate deltas or API streaming. | Origin policy applies; status and body depend on the route. |
POST /{application-path} | Forward an application operation. | Origin policy applies; live upstream request. |
GET /.qscs/… | Read exact reserved browser runtime/helper paths. | Public on registered origins; see runtime endpoint table. |
OPTIONS /{path} | Browser CORS preflight. | No identity required; 200 with an empty body. |
GET /qscs/metrics | Read Prometheus metrics. | Loopback TCP peer only; remote peers receive 404. |
Origin resource requests
Application URLs are routed by their public Host to the configured origin. The application defines its resource paths, request JSON and business responses. QSCS adds identity enforcement and eligible cache, delta or streaming delivery.
Methods and request requirements
| Method | Behaviour |
|---|---|
GET | Read a resource. Origin policy, identity and representation headers determine live or cached delivery. |
HEAD | Accepted for resource metadata; runtime assets explicitly return headers only. Use GET for JSON auth/status routes; they are dispatched by method, not inferred from HEAD. |
POST | Forward the operation live. Core login/logout use their own handlers. |
OPTIONS | Return CORS preflight without contacting the backend. |
PUT, PATCH, DELETE and other methods | Not supported by this listener. The method check returns 400; a protected route may reject missing proof with 401 first. |
Send a valid public Host and preserve the exact request target. Use an explicit Content-Length for request bodies; request-side chunked uploads are not a documented integration path. The listener reads headers up to a 64 KiB guard and returns 400 for incomplete or oversized headers.
Routing and authentication
- OPTIONS and supported core routes are handled directly. Reserved runtime GET/HEAD paths are served on registered origins.
- For protected application routes, the identity gate verifies the origin binding and request signature before delivery.
- Eligible federated reads may use the explicitly configured account-partitioned response cache or API Boost.
- POST, cookie/Authorization requests, header-selected application representations and
Proxy=alluse the live proxy path, subject to the explicit federated cache policy. - Other registered-origin reads use the cache/replication pipeline. Failed origin access may enter HEADLESS fallback.
- For an unregistered host, GET tries local static files, then bootstrap cache, then returns
200 text/plainwithok. POST without an origin returns 502. The health response does not prove a resource exists.
Protected origins have public bootstrap exceptions. The root, selected asset paths/extensions and configured public files can bypass the gate. Authentication & Signing lists these exceptions; do not put private data on them.
Cache and representation rules
Ordinary representations are selected by origin and complete URI, including the query. Federated cache entries also include the verified issuer, subject and policy. Delta baselines are additionally client-specific and require an exact matching URL and baseline hash. A client-supplied account ID is never a cache authorization boundary.
Cookies, bearer credentials, ranges, conditional requests, application-specific headers and unsafe Vary responses affect eligibility. Origin settings such as Proxy=all, PersistCache and explicit federated cache policies also matter. Do not infer that every GET is cached or that a browser no-store header disables an explicitly configured QSCS account cache. Configure those policies through Configuring Origins and API Acceleration.
POST is not a cached read and does not automatically invalidate related cached GET responses. Use the configured invalidation mechanism after source changes. An upstream redirect keeps its Location; it is not a successful JSON baseline.
Ordinary JSON and negotiated deltas
A client that does not advertise delta capability receives an ordinary response body. For supported delta clients, X-QSCS-Delta: 1 enables the legacy decoder path; 2 also permits JSON byte deltas. Send X-QSCS-Base-Hash only for the exact bytes held for this URL. Missing, mismatched or unusable baselines cause a full response.
| Response | Client action |
|---|---|
| Full body with its original Content-Type | Read normally and retain a baseline only if your client supports it. |
X-QSCS-Mode: nochange, negotiated response with an empty body | Reuse the verified matching baseline. This is HTTP 200, distinct from HTTP 304. |
Content-Type: application/x-qscs-delta, X-QSCS-Encoding: base64 | Decode the base64 QSCS delta with a compatible decoder, apply it to the matching baseline, then parse the reconstructed representation. |
Inspect content type, encoding and your negotiated state together. Some diagnostic mode values describe origin/peer processing while the caller still receives a full body. The header reference lists those values. The packaged browser helper reconstructs responses for you.
GET /{api-path} with streaming
Streaming uses the same protected GET URL, not a separate WebSocket endpoint. Configure API Boost for the trusted recipient path. Send a fresh signed GET with X-QSCS-Stream: 1. A warm eligible entry can return 200 text/event-stream and X-QSCS-Stream: 1; a cold or non-streaming path can return ordinary JSON. Always check Content-Type.
| Event | Data / handling |
|---|---|
snapshot | Complete JSON text. Rejoin SSE data lines with LF before validating and parsing. |
snapshot-base64 | Base64-encoded complete payload, used when plain SSE would alter bytes. Decode before validating and parsing JSON. |
unchanged | Data is {}. Reuse a retained baseline only when its SHA-256 equals the event id. |
delta | Opt-in with X-QSCS-Stream-Delta: 2. JSON contains base (previous SHA-256) and delta (base64 QSCS delta). Requires a compatible decoder. |
Each event id is the lowercase SHA-256 of the complete resulting payload bytes. Validate it before accepting a new baseline. To resume, send that retained hash as X-QSCS-Stream-Base; an SSE Last-Event-ID header is not the QSCS resume mechanism. If validation fails, discard the baseline and reconnect without a resume hash.
SSE example — id hashes the exact JSON bytes
event: snapshot
id: 0c07187ea6d064441225b3cba26a7b1e8bc702fcf332b457dae8e26892ba68a6
data: {"count":3}
: keepalive
Comments provide heartbeats about every 5 seconds. Connections normally renew after about 20 seconds, with a hard 60-second bound while output finishes. Sign every reconnect with a new timestamp and nonce. A closed connection is not an ordered event-log checkpoint: this stream delivers current state, may skip intermediate revisions, and has no historical replay guarantee.
Access is rechecked during delivery. On 401/403, revalidate the issuer account before deciding whether to end the session. Capacity rejection can return 503 with {"error":"stream_busy","retry":true} and Retry-After: 2. Reconnect with bounded backoff; keep only bounded baselines and queued output.
Updates arrive when an upstream refresh or replication supplies newer state. The configured Boost refresh interval governs backend queries; streaming does not subscribe directly to your database. Preserve text/event-stream, disable proxy buffering, and allow heartbeats. Use qscs.subscribe in the browser integration guide for automatic signing, reconstruction and renewal.
Request example
Shell / curl — ordinary public GET
curl -i 'https://app.example.com/public/report'
For a protected request, add the four signature headers from Authentication & Signing. Do not add delta headers to a plain curl client that cannot reconstruct the response.
Response and compatibility rules
Check HTTP status and Content-Type before decoding a body. Authentication operations also require an explicit ok:true; HTTP 200 alone is insufficient. Upstream errors and several core failures use plain text or HTML. A mode header describes delivery and does not prove authorization or freshness.
State replication is asynchronous. Handle propagation delays, revoked bindings, cold caches and full-response fallbacks. Tolerate additional JSON fields and unfamiliar diagnostic header values. This reference describes the current implementation; it does not promise identical state at every node or a generic key-value API.
The control-panel management API and encrypted peer protocol on port 4443 are separate interfaces. Application clients should use the documented HTTP endpoints, not peer messages.
GET /qscs/metrics
Returns HTTP 200 with Content-Type: text/plain; version=0.0.4. Access is checked against the direct TCP peer, not forwarded IP headers. Keep this route private at any front proxy that connects over loopback.
Shell / curl — run on the node
curl -i 'http://127.0.0.1:8080/qscs/metrics'
Metric meanings are listed in Metrics & Health.
Integration sequence
- Register the origin and make its backend reachable from QSCS.
- For protected APIs, configure your account verifier and require signed identity. Restrict backend ingress to trusted QSCS nodes.
- Use the packaged browser session controller, or implement the HTTP signing contract in a native/service client.
- Check login’s JSON result, then verify a protected account read before requesting private application data.
- Start with ordinary JSON. Enable delta or stream negotiation only when the client can process the corresponding response formats.
Configuring Gated Identity supplies the deployment procedure. API Acceleration covers cache and streaming configuration.