openapi

• Route: QUERY /api/v2/system/openapi, and GET as well
• Category: system
• Authentication: none, the route is public
• Answer: an OpenAPI 3.2 document in JSON, not wrapped in an envelope

The definition describes every route of the v2 API that the server serves, this one included: its method, its request body, its answers with their schemas, including the error codes the route can report, and the status codes it documents. Use it to generate client code, to explore the API, or to load it into tools such as Postman or Swagger UI, see OpenAPI Specification. The definition of the deprecated v1 API remains available as YAML at /.well-known/openapi.

Request#

The route takes no body, and ignores one that is sent. Besides QUERY, it answers GET, which API tools and code generators send:

curl \
  http://localhost:3000/api/v2/system/openapi

Answer#

The answer is the OpenAPI document, with the content type application/json. Its paths are relative to the server URL /api/v2, which the document names in servers, and its info names the version of the server. Its routes are grouped by their category, as tags. The routes of the ui category, which serve the management UI only, appear only while the management UI is enabled.

Shortened to the description of this very route for GET, and without its info, components, and tags, the request above is answered with:

{
  "openapi": "3.2.0",
  "servers": [
    {
      "url": "/api/v2"
    }
  ],
  "paths": {
    "/system/openapi": {
      "get": {
        "summary": "Describes the v2 API as an OpenAPI document.",
        "tags": [
          "System"
        ],
        "responses": {
          "200": {
            "description": "The OpenAPI document of the v2 API.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {},
                  "required": [],
                  "description": "An OpenAPI 3.2 document.",
                  "additionalProperties": true
                }
              }
            }
          },
          "429": {
            "description": "The request exceeded the rate limit.",
            "headers": {
              "Retry-After": {
                "description": "The number of seconds to wait before sending the request again.",
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "The request caused an internal server error."
          },
          "503": {
            "description": "The server is shutting down."
          }
        }
      }
    }
  }
}

Status Codes#

The server answers with a status code other than 200 where it cannot take the request at all, as described in Errors:

• 429: Too many requests were sent; the answer says when to try again.
• 500: The server failed unexpectedly.
• 503: The server is shutting down.