Skip to main content
Base URL: https://<first-master-ip>:31007 (see k7 api status / k7 api endpoint).

​
Transport

The NodePort is served over HTTPS by default. On the default install the certificate is signed by a playbook-minted cluster CA at /etc/k7/tls/ca.crt on the node — copy it to your client and trust it (curl --cacert ca.crt …, Client(..., verify_ssl="ca.crt"), k7 config set api.ca ca.crt). Clusters installed with --api-hostname present a Let’s Encrypt certificate; --api-tls-cert/--api-tls-key an operator-supplied one; --api-insecure-http serves plain http://. Disabling verification on an https:// URL is rejected by the CLI and SDK. See Security model.

​
Authentication

Send your API key via either header:
All endpoints return standard HTTP codes. 401 Unauthorized if the key is missing/invalid/expired. 403 Forbidden if a namespace-scoped key is used against another namespace, an all-namespaces operation, or a cluster-scoped read such as GET /api/v1/nodes/storage. Keys created with k7 generate-api-key NAME -n <ns> are scoped; omit -n for unrestricted access.

​
Response envelope

Successful responses:
Errors:
Common error codes:
  • BadRequest (400): Invalid input or missing parameters
  • Unauthorized (401): Missing or invalid API key
  • Forbidden (403): Namespace-scoped key used outside its allowlist
  • NotFound (404): Resource was not found
  • Conflict (409): Resource already exists
  • UnprocessableEntity (422): Validation failed
  • InternalServerError (500): Unhandled error

​
Headers

Required headers for requests with body:
Authentication headers (either):

​
Resources

  • Sandboxes: create, list, get, delete, delete-all, pause, resume, fork
  • Exec: run a command in a sandbox and get stdout/stderr/exit_code
  • Metrics: CPU and memory usage per sandbox

​
Endpoints at a glance

Health endpoints:
  • GET / → basic API info
  • GET /health → health check