REST API

Authenticate to the Kowan REST API with an API key or sign-in token, and find the endpoints for hosts, containers, deployments, webhooks and more.

Everything the Kowan web console does goes through its REST API, so you can script any of it. The API is served by your Kowan server under /api/v1, speaks JSON, and applies the same roles and permissions as the console.

curl -H "X-API-Key: $KOWAN_API_KEY" https://kowan.example.com/api/v1/hosts

[
  {
    "id": "local",
    "name": "local",
    "type": "local",
    "mode": "agent",
    "address": "",
    "online": true,
    "lastSeen": "2026-10-30T22:13:44Z",
    "createdAt": "2026-10-30T22:13:43Z"
  }
]

Authentication

Every endpoint under /api/v1 needs a credential, except the few public endpoints. Use an API key for scripts and integrations, or a sign-in token to act as a user.

API keys

An admin creates API keys in Settings > API keys, or with kowanctl apikey create. A key has a role, and can be limited to a team or to specific hosts. Its secret starts with pk_ and is shown only once. See API keys.

Send the key in the X-API-Key header:

curl -H "X-API-Key: pk_..." https://kowan.example.com/api/v1/deployments

The Authorization header works too, as Authorization: Bearer pk_....

Sign-in tokens

Sign in with a username and password to get a token for that user:

curl -X POST https://kowan.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "..."}'

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "d0d2c837-4fa4-4da4-ba7d-9fdda549442a",
    "username": "alice",
    "role": "operator",
    "email": "",
    "authSource": "local",
    "createdAt": "2026-10-30T22:13:43Z"
  }
}

Send the token as Authorization: Bearer <token>. It is valid for 24 hours. POST /api/v1/auth/logout revokes it earlier. Changing the user's password or role, or deleting the user, also ends it.

Too many failed sign-ins return 429 with a Retry-After header. In SSO-only mode, only the break-glass account can sign in with a password: use an API key instead. See Single sign-on.

WebSocket connections

Live logs, container terminals, live stats and Docker events are WebSocket endpoints. Browsers cannot set headers on a WebSocket handshake, so these also accept the credential as a token query parameter: wss://kowan.example.com/api/v1/hosts/local/containers/web/logs?token=pk_.... Plain REST requests never read credentials from the URL.

Roles

The role of the user or API key decides what it can call. Admins can call everything.

A user who belongs to a team, or an API key bound to a team or to scopes, only reaches what its grants cover, never more than its role. Lists leave out what it cannot see. See Users, roles and teams.

Requests and responses

• Request and response bodies are JSON. Send Content-Type: application/json. A JSON request body can be up to 1 MiB.
• Field names are camelCase: createdAt, hostId, lastSeen.
• Times are RFC 3339 timestamps in UTC, such as 2026-10-30T22:13:44Z.
• Objects Kowan stores, such as deployments, workflows and users, have UUIDs. The server Kowan runs on is the host with ID local. Containers, images, volumes and networks keep their Docker IDs and names.
• Endpoints may reject a field they do not know with a 400, so send only the fields you mean to set.
• Long operations, such as a deploy, are queued: the request returns 202 and the work continues in the background.

Errors

An error has an HTTP status and a JSON body with an error message:

{"error": "host not found"}

Endpoints

Paths below are relative to /api/v1. {hostId} is a host ID and {id} the ID of the object. Every change you make through the API is recorded in the audit log.

Account

Hosts

Any role can read hosts. Adding, renaming and removing them needs an admin.

See Adding servers.

Containers

Listing, inspecting, logs and stats need any role. Actions, terminals, reading or changing files, and removal need an operator.

curl -X POST -H "X-API-Key: $KOWAN_API_KEY" \
  https://kowan.example.com/api/v1/hosts/local/containers/web/restart

Images, volumes and networks

Listing and inspecting need any role. Changes, and browsing volume files, need an operator.

Deployments

Reading needs any role. Creating, changing and running deployments needs an operator. See Deployments.

A container deployment on the local host, then its deploy:

curl -X POST https://kowan.example.com/api/v1/deployments \
  -H "X-API-Key: $KOWAN_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "whoami", "type": "container", "strategy": "standalone",
       "targets": ["local"], "spec": {"image": "traefik/whoami:latest"}}'

curl -X POST -H "X-API-Key: $KOWAN_API_KEY" \
  https://kowan.example.com/api/v1/deployments/<id>/deploy

Automation

Reading needs any role, except workflow runs. Creating, changing and running need an operator.

See Workflows and webhooks and Schedules.

Monitoring

Reading needs any role. Changes need an operator.

A {workload} is written as the console writes it: dep~<deployment id>, stack~<host id>~<compose project> or ctr~<host id>~<container name>.

Administration

These need an admin.

Public endpoints

These need no credential.

/health and the /hooks/ paths are not limited by the web console allowlist (KOWAN_UI_ALLOW_CIDRS), since CI systems and Git hosts call them from addresses you do not control.

Webhooks

The token in a webhook URL is its secret: anyone who has the URL can call it. Rotate it from the console or the API if it leaks. An unknown token returns 404.

/hooks/deploy/{token}

Queues a redeploy and returns 202 with {"status": "redeploying", "deployment": "<id>"}. On a Git deployment, the same URL accepts push webhooks from GitHub, Gitea and GitLab. Kowan checks their signature, then redeploys only when auto-deploy is on and the push is to the deployment's branch. When the payload lists the changed files, at least one must be in the Compose file's folder. Pushes to other branches feed its previews.

/hooks/workflow/{token}

Starts a run and returns 202 with {"runId": "<id>", "workflow": "<id>"}. The webhook trigger decides which HTTP method it accepts (POST by default). The request body, headers and query parameters reach the workflow's steps.

curl -X POST https://kowan.example.com/hooks/deploy/3f9c...

See Workflows and webhooks and GitOps.

Related

• Command line: kowanctl wraps the most common calls.
• AI assistants (MCP): the same permissions, as tools for AI assistants.