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. Systemplane has no host or port of its own, and no dedicated admin port. The canonical prefix documented here is
/system, but it varies per application (see the applicability table below).
Applications register the routes programmatically, and no code generator emits them. They therefore 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 you turn on the SYSTEMPLANE_ENABLED setting. Otherwise the application runs in environment-variable-only mode and does not mount these routes.
Namespaces
Configuration lives in 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 has no type at the transport layer. Every registered key accepts its own JSON scalar, object, or array, and its own server-side validator checks the value. Not every setting is runtime-changeable. The application reads bootstrap-only settings once at startup. These settings do not appear in Systemplane and still require a restart to change.
Endpoints
All paths are relative to the application’s prefix (default
/system).
/system/-/catalog names a reserved metadata path. The application serves it before the namespace routes. The - segment is not a real namespace, and you cannot use it 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 after you configure an authorizer. Without an authorizer, the application denies every request. When you enable authentication, 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. The detail route GET /system/-/catalog/{namespace}/{key} returns one key’s full write contract. The contract covers 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. To read the current configured value, call GET /system/{namespace}/{key}.
Which products expose Systemplane
Systemplane is opt-in per product. The table below lists the products that mount it. For each product it gives the path prefix, the default HTTP port, and whether the product 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. You configure them through environment variables only.