Enterprise API reference

The Korta Enterprise manager exposes a JSON REST API for instances, roles, deployments, credentials, cloud settings, and operations. The API is part of the self-hosted Enterprise manager. The standalone core CLI connects to hosts over SSH and does not start an API server.

Before you begin

Start the manager and create a personal API token from your account in the web console, or use the administrator token configured for the manager. Requests use Authorization: Bearer <token>. A personal token has the permissions and scope of its user. Instance creation and cloud settings require global instance management permission. Role planning and approval have separate permissions.

The examples below use a local manager. Set KORTA_API to your own manager's URL and load KORTA_TOKEN securely in your shell. This helper passes the header through standard input instead of placing the token in a command-line argument:

export KORTA_API=http://127.0.0.1:8080
# Set KORTA_TOKEN securely for this shell before running these examples.
korta_api() {
  printf 'header = "Authorization: Bearer %s"\n' "$KORTA_TOKEN" |
    curl --config - --fail-with-body --silent --show-error "$@"
}

korta_api "$KORTA_API/api/session"

Use HTTPS when connecting across a network. Never put tokens, private keys, or secret values in a role, URL, command argument, or a file intended for source control. Secret and key values are write-only through their management APIs.

Responses and operations

Requests and responses use JSON. Send Content-Type: application/json for JSON bodies. A successful creation may return 201 Created; work that runs in the background returns 202 Accepted with an operation. Poll GET /api/operations/{id} until its status is succeeded or failed, and inspect its result, steps, and detail as applicable. A 202 response means the work was accepted, not that it succeeded. Some endpoints return an object containing an operation property rather than the operation directly.

Errors return a JSON object with an error message. Common statuses include 400 for invalid requests, 401 for missing or invalid authentication, 403 for insufficient permission, 404 for resources not found or not visible, and 409 when another operation is running.

Create, plan, and apply a role

This example configures an existing registered instance. Replace the instance ID with one visible to your account. Save the following as role.json:

{
  "name": "web-packages",
  "markdown": "# Packages\n- nginx\n\n# Services\n- nginx started, enabled\n",
  "targets": {"instanceIDs": ["ins_example"]}
}

Create the role, then use the returned role ID to start a plan:

korta_api -H 'Content-Type: application/json' \
  --data-binary @role.json "$KORTA_API/api/roles"

korta_api -X POST "$KORTA_API/api/roles/ROLE_ID/plan"

The plan response is an operation. Poll its id and review its result:

korta_api "$KORTA_API/api/operations/PLAN_OPERATION_ID"

After the plan succeeds and an authorized reviewer approves it, apply that exact plan by sending its operation ID as planID:

korta_api -H 'Content-Type: application/json' \
  --data-binary '{"planID":"PLAN_OPERATION_ID","approve":true}' \
  "$KORTA_API/api/roles/ROLE_ID/apply"

Poll the returned apply operation in the same way. The manager rejects stale, expired, or already-used plans. Roles containing custom scripts also require "confirmCommands": true. With four-eyes approval enabled, the person who last edited or planned the role cannot approve it, except for the audited administrator-token override.

A role can instead begin with an AWS or GCP instance section to create and then configure instances. Cloud provisioning requires global instance management permission; a new host's configuration cannot be inspected before it exists. See AWS provisioning and the Enterprise guide for the cloud workflow and prerequisites.

Endpoint reference

Paths are relative to the manager URL. {id} is the ID returned by the API. Operations and resources are visible only within the caller's permissions.

Session and health

Method and path	Purpose
GET /api/health	Liveness and storage availability. Does not require a token.
GET /api/session	Current user, permissions, and manager settings.
GET /api/types	Available deployment types.
GET /api/ca	Public CA certificate.
POST /api/login, POST /api/logout	Browser session sign-in and sign-out.

Instances and SSH keys

Method and path	Purpose
GET /api/instances	List instances visible to the caller.
POST /api/instances	Register an SSH host and start an initial check. Returns an instance and operation.
GET /api/instances/{id}	Inspect a registered instance.
PUT /api/instances/{id}	Update connection settings and labels. A connection change starts a check.
POST /api/instances/{id}/check	Check SSH access and detect the operating system.
POST /api/instances/{id}/trust-host-key	Trust a new host key after a known reinstall or key rotation.
DELETE /api/instances/{id}	Remove an instance from Korta, subject to resource ownership checks.
GET /api/instances/{id}/console	Open the SSH console WebSocket. Binary frames carry terminal data; text resize frames use {"type":"resize","cols":80,"rows":24}.
GET /api/ssh-keys	List SSH key metadata.
POST /api/ssh-keys	Store a private key and optional passphrase in the vault.
DELETE /api/ssh-keys/{id}	Delete a key that is no longer used.

Roles

Method and path	Purpose
GET /api/roles, GET /api/roles/{id}	List or inspect roles.
POST /api/roles/preview	Validate Markdown and preview compiled steps.
POST /api/roles	Create a role from Markdown or typed steps.
PUT /api/roles/{id}	Update a role; changed content creates a new version.
DELETE /api/roles/{id}	Delete a role once its owned resources have been handled.
POST /api/roles/{id}/plan	Plan without changing hosts. Send {"destroy":true} to plan supported AWS resource destruction.
POST /api/roles/{id}/apply	Approve a plan with planID and approve. Destruction also requires the role name in confirm.

Deployments

Method and path	Purpose
GET /api/deployments, GET /api/deployments/{id}	List or inspect deployments.
POST /api/deployments	Create and apply a deployment; returns a deployment and operation.
PUT /api/deployments/{id}/spec	Update a deployment specification.
POST /api/deployments/{id}/apply	Apply the current specification.
POST /api/deployments/{id}/actions/{action}	Run an action such as status, backup, restore, logs, or restart, depending on the deployment type.
GET /api/deployments/{id}/connection	Obtain connection details when authorized. The response can contain credentials; protect it.
DELETE /api/deployments/{id}	Delete a deployment.
POST /api/provision	Register or select an SSH host and start a deployment in one operation.

Secrets, operations, and audit

Method and path	Purpose
GET /api/secrets	List secret names and metadata, never values.
PUT /api/secrets/{name}	Set a secret value.
PUT /api/secrets/{name}/scope	Restrict a secret to matching instance labels.
DELETE /api/secrets/{name}	Delete an unused secret.
GET /api/operations, GET /api/operations/{id}	List or inspect operations.
GET /api/audit?target={id}	Read audit events, optionally filtered by target.

Cloud settings

Cloud settings require global instance management permission. Secrets are write-only; responses return metadata instead of credential values.

Method and path	Purpose
GET /api/aws	Check the manager's AWS environment.
GET /api/aws/accounts	List AWS account entries.
PUT /api/aws/accounts/{name}	Create or update an AWS account entry.
POST /api/aws/accounts/{name}/test	Test an AWS account entry.
DELETE /api/aws/accounts/{name}	Delete an unused AWS account entry.
GET /api/aws/networks, PUT /api/aws/networks/{name}, DELETE /api/aws/networks/{name}	List and manage AWS network presets.
GET /api/gcp/auth, PUT /api/gcp/auth	Read or update the manager's GCP authentication settings.
POST /api/gcp/auth/test	Test access to a GCP project.

Access and AI assistant

Method and path	Purpose
GET /api/access/levels	List access levels and permissions.
GET /api/users, POST /api/users, GET /api/users/{id}, PATCH /api/users/{id}, DELETE /api/users/{id}	Manage users and grants.
POST /api/users/{id}/reset, DELETE /api/users/{id}/tokens/{token}	Reset account setup or revoke a user's token.
GET /api/me, PUT /api/me/password	Inspect or change the current account.
POST /api/me/totp, POST /api/me/totp/confirm, POST /api/me/totp/remove	Configure or remove the current account's TOTP.
GET /api/me/tokens, POST /api/me/tokens, DELETE /api/me/tokens/{token}	Manage personal API tokens.
GET /api/assistant	Check whether role drafting is enabled.
POST /api/assistant/chats, POST /api/assistant/chats/{id}/messages, POST /api/assistant/chats/{id}/save	Draft, revise, and save a role.