Skip to main content

Public API reference

The node serves a curated public API as a standard OpenAPI document with an interactive browser:

  • OpenAPI document: GET /api/public/v1/openapi.json
  • Interactive reference (Swagger UI): GET /api/public/v1/docs

Both are served from the same deny-by-default gateway described on the REST & OpenAPI page. A client on the outside has one address to reach and one gate to pass.

Direction: inbound. System9 is the server. Status: Live, the document is served and browsable; individual operations carry their own status (below).

Deny-by-default curation​

The served document is not the whole route tree. It is a curated projection: an operation appears only if it carries at least one tag and every tag it carries is on an explicit allowlist. Anything untagged, or tagged with a family outside the allowlist, is never served, so operator-only, internal, and security-sensitive families are excluded by construction rather than by redaction.

Publishing the document grants no access. Every served operation still passes the full gate (authentication, authorization, and per-credential scope) before it runs. The document describes what a suitably authorized caller can reach; it is not itself a grant.

Figure: the curation gate. An operation reaches the served document only when it has a tag and every tag is allowlisted; publication is not access, each served operation is still authenticated, authorized, and scope-checked at call time.

Table equivalent

ConditionResult
Operation has no tagNot served
Operation has any tag outside the allowlistNot served
Operation has ≥1 tag and every tag is allowlistedServed in the public OpenAPI, carrying a per-operation status
A served operation is calledStill gated: authentication + authorization + per-credential scope + rate limits

Reading a per-operation status​

Each served operation carries a status that maps onto the same honest register used across the interface reference:

  • Live: the operation is served and backed by a working implementation. The reference describes the mechanism; it never certifies it.
  • Partial (named slice): the operation is served but only part of the headline capability is wired. Only the named slice may be relied on.

Capabilities that do not carry data end to end today are Planned and are not served at all, they never appear in the document. A green response from a connect or health surface is never evidence that an interface carries data end to end.

What the surface covers​

The served families span the programmatic-access and data/AI surfaces a caller uses without a console, among them identity and credentials, catalog and data products, clean rooms, storage, streams, jobs, and the data exchange. Two areas have their own detailed guides:

  • Programmatic authentication: scoped API keys and OAuth 2.1 (how a caller obtains and presents a credential). Detailed guide forthcoming.
  • Jobs API: running and observing jobs over HTTP. Detailed guide forthcoming.

For the data-access protocols that keep their own per-database credentials, PostgreSQL wire, Arrow Flight SQL, and open table formats. See their own reference pages; the public API is where a caller mints and rotates those credentials, not a replacement for them.