Swagger: reference and examples

Where to open Swagger and how to read endpoint descriptions.

Swagger (OpenAPI 2.0) is the source of truth for Shturval Backend API operations, request parameters, response schemas, and error codes. Site documentation does not duplicate hundreds of paths; accuracy is maintained through the specification (swagger.json in the backend delivery, API version in the info.version field, for example 2.14.0, and base path /api/v1).

Swagger in the GUI

Interactive API documentation is available in the platform GUI:

  1. Open About the system in the top menu.
  2. Click Swagger to open the documentation.

Swagger UI lists all paths, methods, parameters, and example requests that match the current swagger.json.

Reading security and permissions

  • Many operations include the Bearer scheme in the security block: pass Authorization: Bearer <token> in API requests (see Authorization and token).
  • A valid token does not guarantee success: permissions for the specific operation are checked in cluster or platform context.
  • Response codes 401 and 403 indicate typical authentication failure or insufficient permissions — compare with role settings in your organization.

swagger.json contains many tags grouped by operation type (cluster, namespace, provider, observability, and so on). A practical approach:

  1. Identify the path prefix from API structure (/clusters/..., /platform/..., /tenants/..., or WebSocket).
  2. In Swagger UI, use search within the specification.
  3. Open the specific path and method — review Responses and the example body at the bottom.
← API structure: paths and scope
What to do if you don't have enough access rights? →