API Reference
Discovery
Unauthenticated OpenAPI spec, Swagger UI, and health-check endpoints for the Kubeadapt Public API.
Six unauthenticated endpoints publish the API contract, an interactive UI, and service health. Three stay under /v1 — the OpenAPI 3.1 document in JSON, the same document in YAML, and an embedded Swagger UI. Three are root-level, outside /v1 entirely — the health-check routes.
Authentication
All six endpoints are unauthenticated. The Authorization: Bearer header is not required and is not validated.
Response shape
The OpenAPI/Swagger endpoints do not use the universal {data, meta, error} envelope; the health endpoints use a small envelope-free JSON shape of their own.
/v1/openapi.jsonand/v1/openapi.yamlreturn the OpenAPI 3.1 document directly./v1/docsreturns HTML./health,/health/live,/health/readyreturn envelope-free JSON (see below).
See API Overview for the envelope contract used on every other route.
OpenAPI spec (JSON)
GET /v1/openapi.json
Required scope: none, unauthenticated.
Returns the OpenAPI 3.1 document for the /v1 API. The document is the authoritative specification for the API contract and is the input for SDK generators (openapi-generator, oapi-codegen, swagger-codegen).
Example request
curl "https://public-api.kubeadapt.io/v1/openapi.json"Example response
1{
2 "openapi": "3.1.0",
3 "info": {
4 "title": "Kubeadapt Public API",
5 "version": "v1"
6 },
7 "servers": [
8 { "url": "https://public-api.kubeadapt.io" }
9 ],
10 "paths": { "...": "..." },
11 "components": { "...": "..." }
12}Common errors
| HTTP | When |
|---|---|
| 404 | The OpenAPI surface is disabled on this deployment. |
OpenAPI spec (YAML)
GET /v1/openapi.yaml
Required scope: none, unauthenticated.
Identical content to /v1/openapi.json, YAML-encoded.
Example request
curl "https://public-api.kubeadapt.io/v1/openapi.yaml"Example response
1openapi: 3.1.0
2info:
3 title: Kubeadapt Public API
4 version: v1
5servers:
6 - url: https://public-api.kubeadapt.io
7paths:
8 # ...
9components:
10 # ...Common errors
| HTTP | When |
|---|---|
| 404 | The OpenAPI surface is disabled on this deployment. |
Swagger UI
GET /v1/docs
Required scope: none, unauthenticated.
The embedded Swagger UI, served as an HTML page. The page loads /v1/openapi.json by default and renders the spec's servers block as a dropdown. The ?url=<spec-url> query parameter overrides the default spec URL.
Example request
Open in a browser:
https://public-api.kubeadapt.io/v1/docsOr fetch the HTML:
curl "https://public-api.kubeadapt.io/v1/docs"Example response
1<!DOCTYPE html>
2<html lang="en">
3<head>
4 <meta charset="UTF-8">
5 <title>Kubeadapt API v1: Swagger UI</title>
6 ...
7</head>
8<body>
9 <div id="swagger-ui"></div>
10 ...
11</body>
12</html>Common errors
| HTTP | When |
|---|---|
| 404 | The docs surface is disabled on this deployment. |
Health checks
Three unauthenticated health endpoints back load balancer and orchestrator health probes. None use the {data, meta, error} envelope.
GET /health
Liveness/build-identity check. Returns the running version string.
curl "https://public-api.kubeadapt.io/health"{ "status": "ok", "version": "main-205a0bf" }GET /health/live
Bare liveness check with no dependency probing.
curl "https://public-api.kubeadapt.io/health/live"{ "status": "ok" }GET /health/ready
Readiness check — probes the Postgres connection.
curl "https://public-api.kubeadapt.io/health/ready"{ "status": "ready", "checks": { "postgres": "ok" } }When Postgres is unreachable, this returns 503 with status: "not_ready" and a checks.postgres value describing the failure.
Common errors
| HTTP | When |
|---|---|
| 503 | /health/ready only — a dependency (Postgres) is unreachable. |
See also
- API Overview: the universal envelope used on every other route.
- Authentication: the Bearer-token model for authenticated endpoints.
- Error Handling: the catalog of error codes used on authenticated endpoints.