API Reference

The kubenest REST API is the interface used by the web console, CLI tools, and any automation you build on top of kubenest. Every action the UI performs is an API call — there is no privileged back channel. This page covers the conventions that apply across the API and indexes the public application and platform endpoints.

Base URL

All endpoints are prefixed with:

https://api.{your-domain}/api/v1

Replace {your-domain} with the domain you configured during installation. If you are running a local development instance, the default is http://localhost:8000/api/v1.

Authentication

Obtaining tokens

Authenticate by posting credentials to the login endpoint. Note that the login endpoint uses application/x-www-form-urlencoded (not JSON) to comply with the OAuth2 password flow convention:

curl -X POST https://api.your-domain.com/api/v1/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin@example.com&password=your-password" \
  -c cookies.txt

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

The login response also sets an HttpOnly refresh token cookie. Do not discard it — you need it to refresh the access token.

Using the access token

For an endpoint that requires authentication, include the access token in the Authorization header:

Authorization: Bearer {access_token}

Access tokens expire after 30 minutes by default; deployments can override that setting. An invalid or expired bearer token returns 401 Unauthorized with detail: "User not authenticated."; refresh the token (see below).

Refreshing the access token

The refresh endpoint reads the HttpOnly cookie set at login and issues a new access token without requiring you to re-enter your password. It does not rotate the refresh cookie:

curl -X POST https://api.your-domain.com/api/v1/refresh \
  -b cookies.txt

In a browser context, the browser sends the cookie automatically. In a script, save it at login with -c and send it on refresh and logout with -b.

Refresh tokens expire after 7 days by default; deployments can override that setting. After a refresh token expires, the user must log in again.

Logging out

curl -X POST https://api.your-domain.com/api/v1/logout \
  -H "Authorization: Bearer $TOKEN" \
  -b cookies.txt

Logout requires both the bearer access token and the refresh-token cookie. It blacklists both tokens and clears the refresh cookie.

Request conventions

Content-Type. JSON request bodies use Content-Type: application/json. POST /login uses application/x-www-form-urlencoded; POST /stack-templates/from-yaml uses multipart/form-data. Requests without a body do not need a content type.

Namespaced resources. Apps and stack templates are addressed by {namespace}/{name} rather than by UUID. The namespace maps to the project’s Kubernetes namespace, and the name is the App or template name you chose at create time. This makes URLs human-readable and stable.

Pagination. Paginated endpoints return pagination fields beside the data array:

{
  "data": [...],
  "total_count": 142,
  "page": 1,
  "items_per_page": 10
}

Pass ?page=2&items_per_page=50 where pagination is implemented. Most paginated endpoints default to 10 items and cap a page at 100; addon revision history defaults to 50 and caps at 200. Some list endpoints return only data and total_count.

Filtering. Filters are endpoint-specific. Unsupported query parameters are not a portable way to filter a response; use only the parameters listed for that route.

Response conventions

Success codes. Status codes are route-specific. Reads and updates generally return 200 OK, creates generally return 201 Created, and deletes that have no response body return 204 No Content. Cluster scale and provisioning-job retry return 202 Accepted because the infrastructure work continues asynchronously.

Asynchronous reconciliation. App and addon creates can return 201 Created, and app/addon updates can return 200 OK, before cluster reconciliation finishes. Track the resource phase through its read endpoint or SSE stream; do not use 202 alone as the signal that work is asynchronous.

Error format

4xx client errors use the FastAPI detail field. Many routes return a string:

{ "detail": "App 'my-app' not found in namespace 'my-project'" }

422 Unprocessable Entity (validation failures) returns a list of structured errors, one per invalid field:

{
  "detail": [
    {
      "loc": ["body", "components", 0, "workload_spec", "replicas"],
      "msg": "ensure this value is greater than 0",
      "type": "value_error.number.not_gt"
    }
  ]
}

The loc array identifies where validation failed, such as "body", "query", "path", or "cookie".

Some routes put a structured object in detail; for example, App 409 Conflict responses include a machine-readable code and context when a resource is in blocked_sync drift state or a component removal would break an exportRef dependency.

Hub- and operator-dependent endpoints can return 502, 503, or 504 when dispatch or the response fails. The exact status and detail are endpoint-specific.

Rate limits

The API is not rate limited, with two exceptions. Sign-in is throttled: POST /login counts attempts per submitted email and source address, and per source address; after 20 attempts within a minute, further attempts are refused with the same 401 a wrong password gets, for a window that doubles with persistence up to 15 minutes. A correct password clears its own count, and nothing locks an account permanently. One task endpoint is throttled: configurable per-tier, per-path limits are enforced only on POST /tasks/task, which requires an authenticated caller; with the defaults it allows ten requests per hour per caller. Every other endpoint is unthrottled. There is no endpoint for reading current usage, and responses carry no X-RateLimit-* headers — do not build a client that waits for them.

What exists is the configuration surface. A superuser can define per-tier, per-path limits:

Endpoint index

Control plane version

Which control plane you are talking to, in a form you can compare.

contract is deliberately not a semantic version and carries no compatibility promise. It says one thing: whether this control plane is at or after the point where some behaviour changed. Where a fix or an advisory records a floor, it records that floor as a contract number, so checking it is a single integer comparison and needs nothing but the response:

CONTRACT=$(curl -fsS -H "Authorization: Bearer $TOKEN" \
  "https://api.your-domain.com/api/v1/version" | jq -r .contract)
[ "$CONTRACT" -ge 1 ] && echo "at or after contract 1"

Do not compare build values. Two commit SHAs cannot be ordered without the repository they came from, which is why the orderable field is separate.

A control plane that answers 404 here predates the endpoint. That means the check is unavailable, not that the fix is absent — do not read a missing answer as a negative one.

Auth

Clusters

Bundles

The bundle catalog: the KubeNest Platform release manifests this control plane knows about. Manifests are authored in kubenest-contracts/bundles/ and validated against bundle-manifest.schema.json; the backend serves them read-only.

Projects

Apps

Every route below that contains {namespace}/{name} requires ?project_id=<UUID>, including reads, mutations, logs, metrics, addon attachment, deployment history, and rollback. Omitting it returns 422 Unprocessable Entity.

Stack Templates

Addon Instances

Addon Definitions

Organizations and users

Organizations are the top-level tenant boundary. Clusters, projects, and credentials all belong to one.

Provisioning jobs

Cloud cluster provisioning runs asynchronously. Creating a cluster with a cloud provider returns a job you poll or watch over SSE.

Events (SSE)

The SSE stream uses standard text/event-stream encoding. Each frame has an event name and a JSON data payload. install_stage_update carries the same install journal entry sent by the CLI: started makes the current stage move immediately, while completed and failed are terminal. A failed component stage includes the exact component key and puts the cluster in install_failed; the same stage and component remain readable from GET /clusters/{id}/bundle even after the live event has passed. Other event types include app, addon, cluster-status, drift, and build updates.

curl -N -H "Authorization: Bearer $TOKEN" \
  "https://api.your-domain.com/api/v1/events/stream?project_id=$PROJECT_ID&resource_type=app"

The connection is long-lived. Clients should reconnect with backoff if it drops. The endpoint does not implement Last-Event-ID replay; after reconnecting, refresh current state through the relevant read endpoint.

See also:

• Architecture Overview — how the API, hub, and operator relate
• Creating and Managing Apps — practical walkthroughs of the most common app API calls
• Managing Addons — addon instance API calls with real examples
• Local and staging OpenAPI UI: /docs