What Systemplane is
Systemplane is not a standalone service. Each application mounts the same route set onto its own HTTP host and port under an application-specific path prefix — there is no dedicated Systemplane host or port, and no dedicated admin port. The canonical prefix documented here is
/system, but it varies per application (see the applicability table below).
Because the routes are registered programmatically rather than emitted by a code generator, they do not appear in each product’s generated API reference. This reference documents the surface by hand so you can operate it consistently across products.
The whole surface is off by default. An application serves it only when the SYSTEMPLANE_ENABLED setting is turned on; otherwise the application runs in environment-variable-only mode and these routes are not mounted.
Namespaces
Configuration is organized into namespaces, each holding flat, string-keyed entries. Rails and plugins use three canonical namespaces:
Some applications register a single application-named namespace instead of these three. Matcher, for example, keeps all of its keys under a single
matcher namespace.
Each entry’s value is untyped at the transport layer: every registered key accepts its own JSON scalar, object, or array, validated by that key’s server-side validator. Not every setting is runtime-changeable — bootstrap-only settings are read once at startup, are not registered in Systemplane, and still require a restart to change.
Endpoints
All paths are relative to the application’s prefix (default
/system).
/system/-/catalog is a reserved metadata path served before the namespace routes — - is not a real namespace and cannot be used as one. Errors use a flat {"code": <int>, "title": "<string>", "message": "<string>"} envelope.Authentication and permissions
Authorization is deny-all by default. An application serves the surface only once it is configured with an authorizer; without one, every request is denied. When authentication is enabled, the application enforces per-namespace role-based access control on top of a valid, platform-scoped (non-tenant) identity. Reads require the namespace’s read permission and writes require the matching write permission:
The read action covers
GET; the write action covers PUT and DELETE. The catalog discovery endpoints require read permission for at least one namespace.
The exact permission strings can vary per application. Matcher, which uses a single namespace, protects its whole surface with the
system-runtime-config:admin permission (resource system-runtime-config, action admin) rather than the per-namespace strings above. Check the product’s own documentation for its authorization model.Discovering keys with the catalog
When an application opts into the catalog surface,
GET /system/-/catalog lists every key it registers, and GET /system/-/catalog/{namespace}/{key} returns one key’s full write contract — its kind, tenant scope, runtime class, redaction policy, JSON schema, validation rules, valid examples, default value, and the matching PUT path.
Use the catalog to learn what a service exposes before you change anything: the catalog describes the write contract, while the current configured value is read from GET /system/{namespace}/{key}.
Which products expose Systemplane
Systemplane is opt-in per product. The table below lists the products that mount it, the path prefix each uses, its default HTTP port, and whether it also serves the catalog discovery surface. The prefix and port are defaults — a deployment can override them.
Products not listed here do not mount Systemplane — they are configured through environment variables only.