PodWarden
API Reference

API Overview

PodWarden and PodWarden Hub REST API reference

Base URLs

ServiceURLDescription
PodWarden APIhttp://localhost:8000/api/v1Fleet management API
PodWarden Hubhttps://apps.podwarden.com/api/v1Catalog and account API

Authentication

All API requests require authentication via one of:

  • Bearer token (JWT) — Obtained via OIDC login flow
  • API key — For PodWarden Hub catalog access (Bearer pwc_...)
  • MCP token — For PodWarden API automation (Bearer mcp_...)

See Authentication for details.

PodWarden API Endpoints

Health

MethodPathDescription
GET/api/v1/healthHealth check with DB ping

Hosts

MethodPathDescription
GET/api/v1/hostsList hosts (filter by status, hostname)
GET/api/v1/hosts/:idGet host details
POST/api/v1/hostsCreate host manually (by IP/hostname)
PATCH/api/v1/hosts/:idUpdate host fields (display name, notes, network types)
POST/api/v1/hosts/:id/provisionProvision host via Ansible (install Docker, k3s-agent, GPU drivers)
POST/api/v1/hosts/:id/probeProbe host (gather facts: CPU, RAM, disk, GPU)
POST/api/v1/hosts/:id/wipeWipe host (uninstall k3s-agent, reset to discovered)
POST/api/v1/hosts/:id/provision-as-control-planeInstall K3s server (creates new cluster)
POST/api/v1/hosts/:id/register-clusterRegister detected K8s cluster from host
POST/api/v1/hosts/:id/detachDetach host from cluster (clear DB and/or wipe k3s-agent)
POST/api/v1/hosts/discoverTrigger manual Tailscale host discovery

Clusters

MethodPathDescription
GET/api/v1/clustersList clusters
GET/api/v1/clusters/:idGet cluster with member nodes and live info
GET/api/v1/clusters/:id/affectedPreview resources affected by cluster deletion
GET/api/v1/clusters/:id/extendedGet K8s version, namespaces, metrics, events
GET/api/v1/clusters/:id/storage-classesList available storage classes
POST/api/v1/clustersCreate cluster (manual kubeconfig or SSH fetch)
PUT/api/v1/clusters/:idUpdate cluster (name, env, namespace, kubeconfig)
DELETE/api/v1/clusters/:idDelete cluster (cascade: unprotect hosts, delete assignments)
DELETE/api/v1/clusters/:id/nodes/:nameDelete stale node from cluster

Stacks

MethodPathDescription
GET/api/v1/stacksList stacks
GET/api/v1/stacks/:idGet stack with all fields
POST/api/v1/stacksCreate stack
PUT/api/v1/stacks/:idUpdate stack
DELETE/api/v1/stacks/:idDelete stack

Deployments

MethodPathDescription
GET/api/v1/deploymentsList deployments (filter by cluster, stack)
GET/api/v1/deployments/:idGet deployment
POST/api/v1/deploymentsCreate deployment
PUT/api/v1/deployments/:idUpdate deployment
DELETE/api/v1/deployments/:idDelete deployment
POST/api/v1/deployments/:id/deployDeploy to cluster (generates K8s manifest, applies via kubectl)
POST/api/v1/deployments/:id/undeployUndeploy from cluster (delete deployment, optionally delete PVCs)
GET/api/v1/deployments/:id/check-networkPre-flight network compatibility check
GET/api/v1/deployments/:id/logsGet pod logs (with tail limit)

Deployments (CI/CD)

MethodPathDescription
GET/api/v1/deploymentsList deployments (filter by worker_type, environment)
GET/api/v1/deployments/:idGet deployment
POST/api/v1/deploymentsRecord deployment (from CI/CD pipeline)
POST/api/v1/deployments/:id/rollbackRollback to previous deployment image tag

Storage Connections

MethodPathDescription
GET/api/v1/storage-connectionsList storage connections
GET/api/v1/storage-connections/:idGet connection
POST/api/v1/storage-connectionsCreate connection (NFS or S3)
PUT/api/v1/storage-connections/:idUpdate connection
DELETE/api/v1/storage-connections/:idDelete connection
POST/api/v1/storage-connections/:id/testTest connectivity and speed

Provisioning Jobs

MethodPathDescription
GET/api/v1/provisioning-jobsList jobs (filter by host_id, status)
GET/api/v1/provisioning-jobs/:idGet job with stdout/stderr
POST/api/v1/provisioning-jobs/:id/cancelCancel running job

System Configuration

MethodPathDescription
GET/api/v1/system-configGet system config (SMTP, OIDC, Hub)
PUT/api/v1/system-configUpdate system config
POST/api/v1/system-config/test-smtpSend test email
POST/api/v1/system-config/test-oidcTest OIDC discovery

Users

MethodPathDescription
GET/api/v1/usersList users (filter by search, role, status)
GET/api/v1/users/:idGet user
POST/api/v1/usersCreate local user
PUT/api/v1/users/:idUpdate user (name, role, status)
DELETE/api/v1/users/:idDelete user
POST/api/v1/users/:id/set-passwordSet local user password

Secrets

MethodPathDescription
GET/api/v1/secretsList secret keys
GET/api/v1/secrets/:keyGet secret value
POST/api/v1/secretsCreate secret
PUT/api/v1/secrets/:keyUpdate secret
DELETE/api/v1/secrets/:keyDelete secret
POST/api/v1/secrets/generate-ssh-key-pairGenerate ed25519 SSH key pair
GET/api/v1/secrets/ssh-key-pairsList SSH key pairs
GET/api/v1/secrets/ssh-key-pairs-in-useList key pairs used by provisioned hosts

Tailscale Settings

MethodPathDescription
GET/api/v1/tailscale-settingsGet Tailscale config (tailnet, tags)
PUT/api/v1/tailscale-settingsSet Tailscale API key, tailnet, discovery tags

Registry Settings

MethodPathDescription
GET/api/v1/settingsGet default registry URL and image tag
PUT/api/v1/settingsUpdate default registry URL and image tag

Hub Integration

MethodPathDescription
GET/api/v1/hub/test-connectionTest Hub URL + API key connectivity
GET/api/v1/hub/catalog/categoriesProxy: list Hub categories
GET/api/v1/hub/catalog/templatesProxy: list Hub templates (search, category, tags, pagination)
GET/api/v1/hub/catalog/templates/:slugProxy: get single Hub template
POST/api/v1/hub/catalog/templates/:slug/importImport Hub template as local stack
GET/api/v1/hub/catalog/check-updatesCheck for newer versions of imported templates

MCP Tokens

MethodPathDescription
GET/api/v1/mcp-tokensList tokens
POST/api/v1/mcp-tokensCreate token (name, role, expiry_days)
POST/api/v1/mcp-tokens/:id/revokeRevoke token
POST/api/v1/mcp-tokens/:id/reissueReissue token (new key, same name/role)
GET/api/v1/mcp-tokens/:id/auditGet audit log for token
GET/api/v1/mcp-tokens/recent-auditGet recent audit across all tokens

PodWarden Hub API Endpoints

See Catalog API for the full Hub API reference.

Response Format

PodWarden API responses return JSON. Successful responses return the data directly. Error responses include an error message:

{
  "detail": "Description of what went wrong"
}

PodWarden Hub API wraps responses in a standard format:

{
  "templates": [...],
  "pagination": { "page": 1, "limit": 50, "total": 42, "totalPages": 1 }
}

Examples

Real-world examples of managing PodWarden infrastructure through AI assistants

Authentication

API authentication methods for PodWarden and PodWarden Hub

API Overview