API structure: paths and scope

How to read OpenAPI paths and understand request context.

Below is a map of the Shturval Backend API HTTP API based on the OpenAPI file (swagger.json): how path prefixes are structured, what the cluster_id parameter means, how platform and cluster operations differ, why the /tenants section exists, and where to find WebSocket endpoints.

Base path and transport #

• The specification defines basePath: /api/v1. The full REST operation URL is {scheme}://{host}/api/v1{path}, where path comes from Swagger (for example, /clusters, /platform/version).
• The specification lists http and https in schemes — the product typically uses HTTPS.

/clusters section and nested paths #

• The /clusters prefix covers cluster operations: list clusters, get information by cluster_id, kubeconfig, namespace resources, networking, policies, observability, and so on.
• /clusters/{cluster_id}/namespaces/{namespace_name}/...: requests in the context of a specific cluster and namespace (following the cluster → namespace → object model).
• Cluster creation and lifecycle (provisioning, templates) is covered further in Cluster Management API.

/platform section #

• The /platform prefix groups global platform settings and operations: authentication (for example, LDAP, OIDC), providers and integrations, profiles, permissions and roles, sessions, license, version information, kubeconfig lists, UI permissions, and so on.
• The /platform/swag path in the specification refers to the specification service output/wrapper (see the description in Swagger). For opening Swagger UI, see the Swagger section.

/tenants section #

• The /tenants prefix covers operations in the tenant model (creation, attributes) when multi-tenancy is enabled in your environment.

WebSocket and interactive use cases #

In addition to REST, OpenAPI includes paths under /websocket/...: for example, container log streaming and terminal access. These are not regular GET/POST calls with a JSON body in a single response — the client needs a WebSocket client (as in the UI or specialized utilities).

See authentication and pairing requirements for each operation in Swagger on the corresponding path.

Matching Swagger paths to the UI #

1. In Swagger, find the path (for example, /platform/providers).
2. Verify that the method specifies Bearer in the security block.
3. Build the final URL: {BACKENDPOINT}/api/v1 + path from step 1, substituting path parameters (cluster_id, namespace_name, and so on).

For token authorization, see Authorization and token.