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 entire API and indexes all available 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"

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

Include the access token in the Authorization header on every subsequent request:

Authorization: Bearer {access_token}

Access tokens expire after 30 minutes. When a request returns 401 Unauthorized with detail: "Token expired", 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 also rotates the refresh cookie:

curl -X POST https://api.your-domain.com/api/v1/refresh \
  -b cookies.txt \        # curl cookie jar that stores the refresh cookie
  -c cookies.txt

In a browser context, the browser sends the cookie automatically. In a script, manage the cookie jar explicitly with -b/-c.

Refresh tokens expire after 7 days. 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"

Logout invalidates the refresh token cookie and clears the server-side session. The access token itself cannot be invalidated (it is a signed JWT with no revocation list) — it will expire naturally after 30 minutes.

Request conventions

Content-Type. All endpoints except POST /login expect Content-Type: application/json. The login endpoint expects application/x-www-form-urlencoded.

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. List endpoints return a data array and a pagination object:

{
  "data": [...],
  "pagination": {
    "total": 142,
    "page": 1,
    "page_size": 20,
    "pages": 8
  }
}

Pass ?page=2&page_size=50 to paginate. The default page size is 20; the maximum is 100.

Filtering and sorting. Most list endpoints accept query parameters for filtering. Common ones: ?cluster_id=..., ?project_id=..., ?phase=running, ?name=prefix. Sorting: ?sort_by=created_at&sort_order=desc.

Response conventions

Success codes. 200 OK for reads and updates; 201 Created for creates; 202 Accepted for async operations that return before completion (the response body contains the initial state with phase: pending); 204 No Content for deletes.

Async responses. Operations that dispatch events to the operator (app create/patch/delete, addon install/upgrade) return 202 Accepted with the initial resource state. Subscribe to the SSE stream or poll the resource endpoint to track progress.

Error format

4xx client errors return a simple detail 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 is a path through the request body to the invalid field. The first element is always "body" for JSON request bodies or "query" for query parameters.

409 Conflict is returned when a write is attempted on a resource that is in blocked_sync drift state, or when a component removal would break an exportRef dependency.

503 Service Unavailable is returned when the target cluster is disconnected and the operation requires the operator to be reachable. The detail includes the cluster ID and last-seen timestamp.

Rate limits

API rate limits are applied per user. Check current usage:

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.your-domain.com/api/v1/rate-limits" | jq .

Response:

{
  "limits": {
    "requests_per_minute": 300,
    "remaining": 287,
    "reset_at": "2026-06-11T14:23:00Z"
  }
}

Rate limit headers are also included on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Endpoint index

Auth

Clusters

Projects

Apps

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 event has a type field and a JSON data payload. Event types include app.status, addon.status, cluster.status, drift.detected, and build.log.

curl -N -H "Authorization: Bearer $TOKEN" \
  "https://api.your-domain.com/api/v1/events/stream?namespace=my-project&name=my-app"

The connection is long-lived. Clients should implement reconnection with a backoff if the connection drops. The Last-Event-ID header is supported — pass the last received event ID to resume from where you left off.

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
• Interactive Swagger UI: https://api.{your-domain}/docs