# Kapten Docs > Deploy applications, jobs and databases to your own Kubernetes clusters with Kapten. # Kapten documentation Source: https://docs.kapten.io/ Kapten deploys your applications, jobs and databases to Kubernetes clusters that run in **your own cloud account**. You connect a cluster once, then deploy from a GitHub repository or a container image without writing Kubernetes manifests. Your workloads and data never leave your infrastructure. **[Quickstart](/quickstart)** Connect a cluster and deploy your first service in a few minutes. **[How Kapten works](/concepts)** Organizations, projects, environments, clusters and components. **[Guides](/guides)** Step-by-step instructions for common tasks. **[Reference](/reference)** Resource units, limits and the exact behavior of every setting. ## What you can run | Component | What it is | Typical use | | --- | --- | --- | | [Application](/concepts/components#applications) | A long-running service, built from a GitHub repository or pulled from a container image | Web apps, APIs, workers | | [Job](/concepts/components#jobs) | A container that runs to completion, once or on a cron schedule | Migrations, reports, cleanups | | [Database](/concepts/components#databases) | PostgreSQL, MySQL, MongoDB or Redis, inside your cluster or provisioned by your cloud provider | Application data, caches | Each environment gets its own copy of these components, its own [variables and secrets](/concepts/variables-and-secrets), and can be deployed in order with a [pipeline](/concepts/pipelines). ## Use these docs with an AI assistant These docs are built to be read by coding agents as well as people: - [`/llms.txt`](/llms.txt) lists every page with a one-line summary, and [`/llms-full.txt`](/llms-full.txt) holds the whole documentation in one file. - Every page is available as Markdown: append `.md` to its URL, or use **Copy as Markdown** at the top of the page. - An MCP server at `https://docs.kapten.io/mcp` lets Claude Code, Cursor, VS Code or Codex search and read the docs directly: ```bash claude mcp add --transport http kapten-docs https://docs.kapten.io/mcp ``` --- # API overview Source: https://docs.kapten.io/api Everything the console does goes through two HTTP APIs, which you can call from your own scripts and CI. | API | Base URL | What it manages | | --- | --- | --- | | [Platform API](/api/platform) | `https://api.kapten.io` | Projects, environments, applications, jobs, databases, pipelines, clusters, variables and secrets | | [Auth API](/api/auth) | `https://auth.kapten.io` | Organizations, members, invitations, Roles, OAuth applications, single sign-on and billing | Both take and return JSON, and every request needs an access token. ## Authentication A script authenticates as an OAuth application: a machine client of your organization, with its own Roles. It exchanges its credentials for a short-lived access token with the OAuth 2.0 client credentials grant, then sends that token with every request. 1. **Create an OAuth application** In the [Kapten console](https://app.kapten.io), open **Settings**, then **OAuth applications**, and create an application with a client secret. Give it only the Roles the script needs: its tokens can do what those Roles allow, in your organization only. Copy the client ID and the secret. The secret is shown once. 2. **Get an access token** ```bash curl -s https://auth.kapten.io/token \ -u "$KAPTEN_CLIENT_ID:$KAPTEN_CLIENT_SECRET" \ -d grant_type=client_credentials ``` The response holds the token in `access_token`, and its lifetime in seconds in `expires_in`. Request a new one when it expires: the client credentials grant has no refresh token. 3. **Call the API** Send the token in the `Authorization` header: ```bash curl -s https://api.kapten.io/project \ -H "Authorization: Bearer $KAPTEN_TOKEN" ``` The token endpoint also accepts the client ID and secret as `client_id` and `client_secret` form fields, and a signed JWT assertion (`private_key_jwt`) in place of a secret, for applications you register a public key for. The authorization server's [discovery document](/api/auth/oauth/get-openid-configuration) lists the endpoints and methods it supports. ## Errors A request without a valid token gets `401 Unauthorized`. A token whose Roles do not allow the operation gets `403 Forbidden`. Each operation page lists the responses it can return and their bodies. --- # Auth API Source: https://docs.kapten.io/api/auth Manage organizations, members, invitations, Roles, OAuth applications, single sign-on and billing. Every request carries an access token: see [Authentication](/api#authentication). Version 1.0.0 Base URL: `https://auth.kapten.io` ## Organizations Organizations the caller belongs to. - [`GET /organizations`](/api/auth/organizations/list-organizations) — List the caller's organizations. - [`POST /organizations`](/api/auth/organizations/create-organization) — Create an organization. - [`GET /organizations/{organizationId}`](/api/auth/organizations/get-organization) — Get an organization. - [`PATCH /organizations/{organizationId}`](/api/auth/organizations/update-organization) — Update an organization. - [`DELETE /organizations/{organizationId}`](/api/auth/organizations/delete-organization) — Delete an organization. ## Members Members of an organization and their Roles. - [`GET /organizations/{organizationId}/members`](/api/auth/members/list-members) — List members. - [`DELETE /organizations/{organizationId}/members/{userId}`](/api/auth/members/remove-member) — Remove a member. - [`PUT /organizations/{organizationId}/members/{userId}`](/api/auth/members/set-member-roles) — Set a member's Roles. ## Invitations Invitations to join an organization. - [`GET /organizations/{organizationId}/invitations`](/api/auth/invitations/list-invitations) — List pending invitations. - [`POST /organizations/{organizationId}/invitations`](/api/auth/invitations/create-invitation) — Invite someone by email. - [`DELETE /organizations/{organizationId}/invitations/{invitationId}`](/api/auth/invitations/cancel-invitation) — Cancel a pending invitation. - [`POST /invitations/accept`](/api/auth/invitations/accept-invitation) — Accept an invitation. ## Roles and permissions Roles, their scoped grants, and permission checks. - [`GET /organizations/{organizationId}/roles`](/api/auth/roles/list-roles) — List Roles. - [`POST /organizations/{organizationId}/roles`](/api/auth/roles/create-role) — Create a custom Role. - [`PATCH /organizations/{organizationId}/roles/{roleId}`](/api/auth/roles/update-role) — Rename a custom Role or replace its Grants. - [`DELETE /organizations/{organizationId}/roles/{roleId}`](/api/auth/roles/delete-role) — Delete a custom Role. - [`POST /organizations/{organizationId}/permission-checks`](/api/auth/roles/check-permissions) — Check the caller's Permissions. - [`GET /permissions`](/api/auth/roles/get-permission-catalog) — Get the Permission catalog. ## OAuth applications Machine clients of an organization, using the client credentials grant. - [`GET /organizations/{organizationId}/oauth-clients`](/api/auth/oauth-clients/list-o-auth-clients) — List OAuth applications. - [`POST /organizations/{organizationId}/oauth-clients`](/api/auth/oauth-clients/create-o-auth-client) — Create an OAuth application. - [`GET /organizations/{organizationId}/oauth-clients/{clientId}`](/api/auth/oauth-clients/get-o-auth-client) — Get an OAuth application. - [`PATCH /organizations/{organizationId}/oauth-clients/{clientId}`](/api/auth/oauth-clients/update-o-auth-client) — Update an OAuth application. - [`DELETE /organizations/{organizationId}/oauth-clients/{clientId}`](/api/auth/oauth-clients/revoke-o-auth-client) — Revoke an OAuth application. - [`POST /organizations/{organizationId}/oauth-clients/{clientId}/keys`](/api/auth/oauth-clients/add-o-auth-client-key) — Register a public key. - [`DELETE /organizations/{organizationId}/oauth-clients/{clientId}/keys/{keyId}`](/api/auth/oauth-clients/revoke-o-auth-client-key) — Revoke a public key. - [`POST /organizations/{organizationId}/oauth-clients/{clientId}/secrets`](/api/auth/oauth-clients/add-o-auth-client-secret) — Create a client secret. - [`DELETE /organizations/{organizationId}/oauth-clients/{clientId}/secrets/{secretId}`](/api/auth/oauth-clients/revoke-o-auth-client-secret) — Revoke a client secret. ## Single sign-on The organization's OpenID Connect identity provider. - [`GET /organizations/{organizationId}/sso`](/api/auth/sso/get-sso-connection) — Get the organization's identity provider. - [`PUT /organizations/{organizationId}/sso`](/api/auth/sso/configure-sso-connection) — Create or replace the organization's identity provider. - [`DELETE /organizations/{organizationId}/sso`](/api/auth/sso/delete-sso-connection) — Remove the organization's identity provider. - [`POST /organizations/{organizationId}/sso/domains/{domain}/verify`](/api/auth/sso/verify-sso-domain) — Verify an email domain of the identity provider. ## Billing The organization's subscription. - [`GET /organizations/{organizationId}/billing/plans`](/api/auth/billing/list-billing-plans) — List the subscription plans. - [`GET /organizations/{organizationId}/billing/subscription`](/api/auth/billing/get-billing-subscription) — Get the organization's current subscription. - [`POST /organizations/{organizationId}/billing/subscription/cancel`](/api/auth/billing/cancel-billing-subscription) — Cancel the subscription. - [`POST /organizations/{organizationId}/billing/subscription/resume`](/api/auth/billing/resume-billing-subscription) — Undo a scheduled cancellation. - [`POST /organizations/{organizationId}/billing/preview`](/api/auth/billing/preview-billing) — Estimate the recurring invoice. - [`POST /organizations/{organizationId}/billing/checkout`](/api/auth/billing/create-billing-checkout) — Subscribe, or change the plan or seats. - [`POST /organizations/{organizationId}/billing/portal`](/api/auth/billing/create-billing-portal) — Open the Stripe Customer Portal. ## Passkeys The caller's passkeys. - [`GET /passkeys`](/api/auth/passkeys/list-passkeys) — List the caller's passkeys. - [`PATCH /passkeys/{passkeyId}`](/api/auth/passkeys/rename-passkey) — Rename a passkey. - [`DELETE /passkeys/{passkeyId}`](/api/auth/passkeys/revoke-passkey) — Revoke a passkey. ## Audit log Changes made to the organization, its members and Roles. - [`GET /organizations/{organizationId}/audit-events`](/api/auth/audit/list-audit-events) — List audit events. ## Discovery OpenID Connect discovery document of the authorization server. - [`GET /.well-known/openid-configuration`](/api/auth/oauth/get-openid-configuration) — Get the authorization server metadata. ## Token keys Public keys that verify access tokens. - [`GET /.well-known/jwks.json`](/api/auth/tokens/get-jwks) — Get token verification keys. --- # List audit events Source: https://docs.kapten.io/api/auth/audit/list-audit-events Requires audit:read. Events about Roles, memberships, invitations, OAuth applications, single sign-on and sign-ins, newest first, including denials and their origin. The Platform API serves the events about projects, environments, components and clusters with the same schema and filters. `GET /organizations/{organizationId}/audit-events` **Responses** - `200` — A page of events. - `default` — The request failed. Response example, 200: ```json { "events": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "source": "auth", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "occurred_at": "2019-08-24T14:15:22Z", "action": "string", "actor": { "type": "user", "id": "string", "email": "string", "name": "string" }, "targets": [ { "type": "string", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "relation": "primary" } ], "affected_user": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "email": "string", "name": "string" }, "outcome": "allowed", "denial_reason": "string", "changed_fields": [ "string" ], "changes": { "before": {}, "after": {} }, "metadata": {}, "origin": { "ip": "string", "user_agent": "string", "entry_point": "http", "request_id": "string" } } ], "next_cursor": "string" } ``` --- # Cancel the subscription Source: https://docs.kapten.io/api/auth/billing/cancel-billing-subscription Requires organization:update. Returns the URL of the Stripe Customer Portal's cancellation page. Answers 404 without a current subscription, and 409 when it is already set to be canceled. `POST /organizations/{organizationId}/billing/subscription/cancel` **Request body** (`application/json`, required) - `return_url` (string, required) — A console URL Stripe returns to. Request body example: ```json { "return_url": "http://example.com" } ``` **Responses** - `200` — The Stripe page to open. - `default` — The request failed. Response example, 200: ```json { "url": "http://example.com" } ``` --- # Subscribe, or change the plan or seats Source: https://docs.kapten.io/api/auth/billing/create-billing-checkout Requires organization:update. Without a current subscription, returns a Stripe Checkout URL. With one, returns a Stripe Customer Portal URL to confirm the change. Asking for the plan and seats already active answers 409. A plan billed per environment minute takes no seats, and the minutes used are billed at the end of each period. The subscription changes once Stripe confirms it, not when the browser returns. `POST /organizations/{organizationId}/billing/checkout` **Request body** (`application/json`, required) - `plan` (string) — A plan name; the default plan when omitted. - `seats` (integer) — Licensed environments, required by a plan priced per seat. A plan billed per environment minute ignores it. - `return_url` (string, required) — A console URL Stripe returns to, whether the change completes or not. Request body example: ```json { "plan": "string", "seats": 1, "return_url": "http://example.com" } ``` **Responses** - `200` — The Stripe page to open. - `default` — The request failed. Response example, 200: ```json { "url": "http://example.com" } ``` --- # Open the Stripe Customer Portal Source: https://docs.kapten.io/api/auth/billing/create-billing-portal Returns the URL of the Stripe Customer Portal, for invoices and payment methods. Requires organization:update. Answers 404 before the organization's first checkout. `POST /organizations/{organizationId}/billing/portal` **Request body** (`application/json`, required) - `return_url` (string, required) — A console URL Stripe returns to. Request body example: ```json { "return_url": "http://example.com" } ``` **Responses** - `200` — The Stripe page to open. - `default` — The request failed. Response example, 200: ```json { "url": "http://example.com" } ``` --- # Get the organization's current subscription Source: https://docs.kapten.io/api/auth/billing/get-billing-subscription Requires organization:update. Answers 404 when the organization has no active or trialing subscription, which means it is on the free plan. `GET /organizations/{organizationId}/billing/subscription` **Responses** - `200` — The active or trialing subscription. - `default` — The request failed. Response example, 200: ```json { "id": "string", "plan": "string", "status": "string", "seats": 0, "current_period_start": "2019-08-24T14:15:22Z", "current_period_end": "2019-08-24T14:15:22Z", "cancel_at_period_end": true, "cancel_at": "2019-08-24T14:15:22Z", "canceled_at": "2019-08-24T14:15:22Z", "ended_at": "2019-08-24T14:15:22Z", "trial_start": "2019-08-24T14:15:22Z", "trial_end": "2019-08-24T14:15:22Z" } ``` --- # List the subscription plans Source: https://docs.kapten.io/api/auth/billing/list-billing-plans Requires being a member. Answers 503 when billing is not configured, and 502 when Stripe cannot give the price of a plan. `GET /organizations/{organizationId}/billing/plans` **Responses** - `200` — The plans, the default first. - `default` — The request failed. Response example, 200: ```json [ { "name": "string", "usage": { "currency": "string", "included_minutes": 0, "minute_amount": "string" } } ] ``` --- # Estimate the recurring invoice Source: https://docs.kapten.io/api/auth/billing/preview-billing Estimates the recurring invoice for a plan and a number of seats. Requires being a member. With a current subscription, the estimate replaces its plan with the one asked for. A plan billed per environment minute takes no seats, and the estimate leaves out the usage billed at the end of the period. Answers 502 when Stripe fails. `POST /organizations/{organizationId}/billing/preview` **Request body** (`application/json`, required) - `plan` (string) — A plan name; the default plan when omitted. - `seats` (integer) — Licensed environments, required by a plan priced per seat. A plan billed per environment minute ignores it. Request body example: ```json { "plan": "string", "seats": 1 } ``` **Responses** - `200` — The estimate. - `default` — The request failed. Response example, 200: ```json { "currency": "string", "subtotal": 0, "tax": 0, "total": 0 } ``` --- # Undo a scheduled cancellation Source: https://docs.kapten.io/api/auth/billing/resume-billing-subscription Requires organization:update. Answers 404 without a current subscription and 409 when it is not set to be canceled. `POST /organizations/{organizationId}/billing/subscription/resume` **Responses** - `200` — The subscription, no longer set to be canceled. - `default` — The request failed. Response example, 200: ```json { "id": "string", "plan": "string", "status": "string", "seats": 0, "current_period_start": "2019-08-24T14:15:22Z", "current_period_end": "2019-08-24T14:15:22Z", "cancel_at_period_end": true, "cancel_at": "2019-08-24T14:15:22Z", "canceled_at": "2019-08-24T14:15:22Z", "ended_at": "2019-08-24T14:15:22Z", "trial_start": "2019-08-24T14:15:22Z", "trial_end": "2019-08-24T14:15:22Z" } ``` --- # Accept an invitation Source: https://docs.kapten.io/api/auth/invitations/accept-invitation Makes the caller a member with the invitation's Role. The caller's verified email must be the invited address (403 otherwise); an unknown, expired, canceled or already accepted invitation answers 410. `POST /invitations/accept` **Request body** (`application/json`, required) - `token` (string, required) — The secret from the invitation link, {ui\_url}/invitations/{token}. Request body example: ```json { "token": "string" } ``` **Responses** - `200` — The organization joined. - `default` — The request failed. Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "slug": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Cancel a pending invitation Source: https://docs.kapten.io/api/auth/invitations/cancel-invitation Requires invitation:cancel. `DELETE /organizations/{organizationId}/invitations/{invitationId}` **Responses** - `204` — The invitation can no longer be accepted. - `default` — The request failed. --- # Invite someone by email Source: https://docs.kapten.io/api/auth/invitations/create-invitation Requires invitation:create, and being an owner to invite an owner. Emails the invited address a single-use link to accept the invitation in the console. `POST /organizations/{organizationId}/invitations` **Request body** (`application/json`, required) - `email` (string, required) - `role` (string, required) — Name of an organization Role, such as owner, admin or member. Inviting an owner requires being an owner. Request body example: ```json { "email": "user@example.com", "role": "string" } ``` **Responses** - `201` — The invitation was created and emailed. - `default` — The request failed. Response example, 201: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "email": "string", "role": "string", "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z" } ``` --- # List pending invitations Source: https://docs.kapten.io/api/auth/invitations/list-invitations Requires invitation:create or invitation:cancel. `GET /organizations/{organizationId}/invitations` **Responses** - `200` — The invitations that are neither accepted, canceled nor expired. - `default` — The request failed. Response example, 200: ```json [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "email": "string", "role": "string", "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z" } ] ``` --- # List members Source: https://docs.kapten.io/api/auth/members/list-members Requires being a member of the organization. `GET /organizations/{organizationId}/members` **Responses** - `200` — The members and their Roles. - `default` — The request failed. Response example, 200: ```json [ { "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5", "email": "string", "roles": [ "string" ] } ] ``` --- # Remove a member Source: https://docs.kapten.io/api/auth/members/remove-member Takes every Role of the organization away from the user. Members may remove themselves; removing someone else requires member:delete, and removing an owner requires being an owner. The last owner cannot be removed (409). `DELETE /organizations/{organizationId}/members/{userId}` **Responses** - `204` — The user is no longer a member. - `default` — The request failed. --- # Set a member's Roles Source: https://docs.kapten.io/api/auth/members/set-member-roles Replaces the Roles the member holds; requires member:update. Giving or taking a Role that grants organization:delete, such as owner, also requires organization:delete. The last owner keeps the owner Role (409). To take every Role away, remove the member. `PUT /organizations/{organizationId}/members/{userId}` **Request body** (`application/json`, required) - `roles` (string[], required) — Names of the organization Roles the member holds. Request body example: ```json { "roles": [ "string" ] } ``` **Responses** - `200` — The member and their Roles. - `default` — The request failed. Response example, 200: ```json { "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5", "email": "string", "roles": [ "string" ] } ``` --- # Register a public key Source: https://docs.kapten.io/api/auth/oauth-clients/add-o-auth-client-key Registers a public key the application signs its token requests with (`private_key_jwt`), for example to rotate keys. Requires organization:update. A key already registered for the application, even revoked, is refused (409), as are more than 5 active keys. `POST /organizations/{organizationId}/oauth-clients/{clientId}/keys` **Request body** (`application/json`, required) - `jwk` (public_jwk, required) — A public signing key (RFC 7517) - EC P-256, P-384 or P-521, Ed25519 (OKP), or RSA of 2048 bits or more. Private members are refused; use, when present, must be sig. Request body example: ```json { "jwk": {} } ``` **Responses** - `201` — The registered key. - `default` — The request failed. Response example, 201: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "kid": "string", "jwk": {}, "created_at": "2019-08-24T14:15:22Z", "revoked_at": "2019-08-24T14:15:22Z" } ``` --- # Create a client secret Source: https://docs.kapten.io/api/auth/oauth-clients/add-o-auth-client-secret Creates a secret for the application, to start using secrets or to rotate them. Requires organization:update. Only this response holds the secret. An application holds at most 5 active secrets (409). `POST /organizations/{organizationId}/oauth-clients/{clientId}/secrets` **Request body** (`application/json`, required) - `expires_at` (string) — When the secret stops authenticating the client, in the future. Without it the secret does not expire. Request body example: ```json { "expires_at": "2019-08-24T14:15:22Z" } ``` **Responses** - `201` — The new secret, with its value. - `default` — The request failed. Response example, 201: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "secret": "string", "hint": "string", "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "revoked_at": "2019-08-24T14:15:22Z" } ``` --- # Create an OAuth application Source: https://docs.kapten.io/api/auth/oauth-clients/create-o-auth-client Requires organization:update; giving the application a Role that grants organization:delete also requires organization:delete. Unknown Role names and invalid keys are refused (400). With `secret`, the response holds the first client secret, which cannot be read again. `POST /organizations/{organizationId}/oauth-clients` **Request body** (`application/json`, required) - `name` (string, required) — Trimmed; 1 to 100 characters. - `scopes` (string[]) - `roles` (string[]) — Role names the client holds. - `keys` (public_jwk[]) — Public keys to register; more can be added later. - `secret` (boolean) — Create a first client secret, returned once in the response's secrets. A client needs a secret or a key to get tokens. - `secret_expires_at` (string) — The first secret's expiry, in the future; only with secret. Without it the secret does not expire. Request body example: ```json { "name": "string", "scopes": [ "string" ], "roles": [ "string" ], "keys": [ {} ], "secret": true, "secret_expires_at": "2019-08-24T14:15:22Z" } ``` **Responses** - `201` — The created client. - `default` — The request failed. Response example, 201: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "client_id": "string", "name": "string", "scopes": [ "string" ], "roles": [ "string" ], "keys": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "kid": "string", "jwk": {}, "created_at": "2019-08-24T14:15:22Z", "revoked_at": "2019-08-24T14:15:22Z" } ], "secrets": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "secret": "string", "hint": "string", "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "revoked_at": "2019-08-24T14:15:22Z" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "revoked_at": "2019-08-24T14:15:22Z" } ``` --- # Get an OAuth application Source: https://docs.kapten.io/api/auth/oauth-clients/get-o-auth-client Requires being a member. `GET /organizations/{organizationId}/oauth-clients/{clientId}` **Responses** - `200` — The client. - `default` — The request failed. Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "client_id": "string", "name": "string", "scopes": [ "string" ], "roles": [ "string" ], "keys": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "kid": "string", "jwk": {}, "created_at": "2019-08-24T14:15:22Z", "revoked_at": "2019-08-24T14:15:22Z" } ], "secrets": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "secret": "string", "hint": "string", "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "revoked_at": "2019-08-24T14:15:22Z" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "revoked_at": "2019-08-24T14:15:22Z" } ``` --- # List OAuth applications Source: https://docs.kapten.io/api/auth/oauth-clients/list-o-auth-clients Requires being a member. Revoked applications are listed with `revoked_at`. `GET /organizations/{organizationId}/oauth-clients` **Responses** - `200` — The clients, oldest first. - `default` — The request failed. Response example, 200: ```json [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "client_id": "string", "name": "string", "scopes": [ "string" ], "roles": [ "string" ], "keys": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "kid": "string", "jwk": {}, "created_at": "2019-08-24T14:15:22Z", "revoked_at": "2019-08-24T14:15:22Z" } ], "secrets": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "secret": "string", "hint": "string", "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "revoked_at": "2019-08-24T14:15:22Z" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "revoked_at": "2019-08-24T14:15:22Z" } ] ``` --- # Revoke an OAuth application Source: https://docs.kapten.io/api/auth/oauth-clients/revoke-o-auth-client Requires organization:update, and organization:delete when the application holds a Role that grants it. The application gets no new token and loses its Roles; tokens already issued expire on their own. Revoking cannot be undone. `DELETE /organizations/{organizationId}/oauth-clients/{clientId}` **Responses** - `204` — The client is revoked. - `default` — The request failed. --- # Revoke a public key Source: https://docs.kapten.io/api/auth/oauth-clients/revoke-o-auth-client-key Requires organization:update. Token requests signed with the key are refused from then on. `DELETE /organizations/{organizationId}/oauth-clients/{clientId}/keys/{keyId}` **Responses** - `204` — The key is revoked. - `default` — The request failed. --- # Revoke a client secret Source: https://docs.kapten.io/api/auth/oauth-clients/revoke-o-auth-client-secret Requires organization:update. Token requests with the secret are refused from then on. `DELETE /organizations/{organizationId}/oauth-clients/{clientId}/secrets/{secretId}` **Responses** - `204` — The secret is revoked. - `default` — The request failed. --- # Update an OAuth application Source: https://docs.kapten.io/api/auth/oauth-clients/update-o-auth-client Renames an application, or replaces its scopes or Roles. Requires organization:update; adding or removing a Role that grants organization:delete also requires organization:delete. A revoked application cannot change (409). `PATCH /organizations/{organizationId}/oauth-clients/{clientId}` **Request body** (`application/json`, required) - `name` (string) - `scopes` (string[]) — Replaces the allowed scopes. Tokens already issued keep theirs until they expire. - `roles` (string[]) — Replaces the Roles the client holds. Request body example: ```json { "name": "string", "scopes": [ "string" ], "roles": [ "string" ] } ``` **Responses** - `200` — The updated client. - `default` — The request failed. Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "client_id": "string", "name": "string", "scopes": [ "string" ], "roles": [ "string" ], "keys": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "kid": "string", "jwk": {}, "created_at": "2019-08-24T14:15:22Z", "revoked_at": "2019-08-24T14:15:22Z" } ], "secrets": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "secret": "string", "hint": "string", "created_at": "2019-08-24T14:15:22Z", "expires_at": "2019-08-24T14:15:22Z", "revoked_at": "2019-08-24T14:15:22Z" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "revoked_at": "2019-08-24T14:15:22Z" } ``` --- # Get the authorization server metadata Source: https://docs.kapten.io/api/auth/oauth/get-openid-configuration Returns the issuer, the endpoints and the supported values that OAuth clients discover. The authorization, token and logout endpoints it lists take browser redirects and form posts, as OAuth 2.0 defines them, and are not part of this JSON API. `GET /.well-known/openid-configuration` **Responses** - `200` — The authorization server metadata. Response example, 200: ```json { "issuer": "string", "authorization_endpoint": "string", "token_endpoint": "string", "end_session_endpoint": "string", "device_authorization_endpoint": "string", "jwks_uri": "string", "scopes_supported": [ "string" ], "response_types_supported": [ "string" ], "response_modes_supported": [ "string" ], "grant_types_supported": [ "string" ], "token_endpoint_auth_methods_supported": [ "string" ], "token_endpoint_auth_signing_alg_values_supported": [ "string" ], "code_challenge_methods_supported": [ "string" ], "dpop_signing_alg_values_supported": [ "string" ], "authorization_response_iss_parameter_supported": true } ``` --- # Create an organization Source: https://docs.kapten.io/api/auth/organizations/create-organization Creates an organization with the owner, admin and member Roles, and makes the caller its owner. To act in it, get a token for it with the token endpoint's `organization_id` parameter. `POST /organizations` **Request body** (`application/json`, required) - `name` (string, required) - `slug` (string, required) Request body example: ```json { "name": "string", "slug": "string" } ``` **Responses** - `201` — The new organization. - `default` — The request failed. Response example, 201: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "slug": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Delete an organization Source: https://docs.kapten.io/api/auth/organizations/delete-organization Requires organization:delete. Refused with 409 while the organization still owns projects, clusters or integrations: delete them first. `DELETE /organizations/{organizationId}` **Responses** - `204` — The organization, its Roles, Memberships and invitations are deleted. - `default` — The request failed. --- # Get an organization Source: https://docs.kapten.io/api/auth/organizations/get-organization Requires being a member of the organization. `GET /organizations/{organizationId}` **Responses** - `200` — The organization. - `default` — The request failed. Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "slug": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # List the caller's organizations Source: https://docs.kapten.io/api/auth/organizations/list-organizations Returns the organizations the caller is a member of, oldest first. `GET /organizations` **Responses** - `200` — The caller's organizations. - `default` — The request failed. Response example, 200: ```json [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "slug": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ] ``` --- # Update an organization Source: https://docs.kapten.io/api/auth/organizations/update-organization Requires organization:update. `PATCH /organizations/{organizationId}` **Request body** (`application/json`, required) - `name` (string) - `slug` (string) Request body example: ```json { "name": "string", "slug": "string" } ``` **Responses** - `200` — The updated organization. - `default` — The request failed. Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "slug": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # List the caller's passkeys Source: https://docs.kapten.io/api/auth/passkeys/list-passkeys Returns the caller's passkeys, oldest first. `GET /passkeys` **Responses** - `200` — The caller's passkeys. - `default` — The request failed. Response example, 200: ```json [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "provider": "string", "synced": true, "backed_up": true, "transports": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "last_used_at": "2019-08-24T14:15:22Z" } ] ``` --- # Rename a passkey Source: https://docs.kapten.io/api/auth/passkeys/rename-passkey Renames one of the caller's passkeys. `PATCH /passkeys/{passkeyId}` **Request body** (`application/json`, required) - `name` (string, required) — 1 to 64 characters, trimmed. Request body example: ```json { "name": "string" } ``` **Responses** - `200` — The renamed passkey. - `default` — The request failed. Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "provider": "string", "synced": true, "backed_up": true, "transports": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "last_used_at": "2019-08-24T14:15:22Z" } ``` --- # Revoke a passkey Source: https://docs.kapten.io/api/auth/passkeys/revoke-passkey The passkey can no longer sign in; the sessions it started stay. The passkey provider learns of it the next time the user opens their account page or signs in with another passkey (WebAuthn signal API). Revoking cannot be undone. `DELETE /passkeys/{passkeyId}` **Responses** - `204` — The passkey is revoked. - `default` — The request failed. --- # Check the caller's Permissions Source: https://docs.kapten.io/api/auth/roles/check-permissions Answers each check for the caller, for example to show only the actions they may take. Requires being a member. Organization Permissions (organization, member, invitation, team, ac, audit) take no context. Permissions on Platform API resources are checked on the resource named by its own context ID, on the project for an environment check with only `project_id`, or else on the organization; a read without context is allowed when the caller can read any resource of that type in the organization. Resources outside the organization answer false. `POST /organizations/{organizationId}/permission-checks` **Request body** (`application/json`, required) - `checks` (permission_check[], required) Request body example: ```json { "checks": [ { "permission": "string", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "integration_id": "55d7337e-1d0a-49fc-9826-925ba40df035" } ] } ``` **Responses** - `200` — One answer per check, in order. - `default` — The request failed. Response example, 200: ```json { "allowed": [ true ] } ``` --- # Create a custom Role Source: https://docs.kapten.io/api/auth/roles/create-role Requires ac:create; granting organization:delete also requires organization:delete. Built-in names are reserved, names are unique within the organization (409), and every resource a Grant selects must belong to the organization (400). `POST /organizations/{organizationId}/roles` **Request body** (`application/json`, required) - `name` (string, required) — Trimmed and lower-cased; 1 to 64 characters, not a built-in name. - `grants` (grant_document, required) — A Role's Grants as scoped statements. Statements add together. Responses are canonical, one statement per scope instance. Request body example: ```json { "name": "string", "grants": { "version": 1, "statements": [ { "scope": { "type": "organization", "ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "all": true }, "permissions": [ "string" ] } ] } } ``` **Responses** - `201` — The created Role. - `default` — The request failed. Response example, 201: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "builtin": true, "grants": { "version": 1, "statements": [ { "scope": { "type": "organization", "ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "all": true }, "permissions": [ "string" ] } ] }, "created_at": "2019-08-24T14:15:22Z" } ``` --- # Delete a custom Role Source: https://docs.kapten.io/api/auth/roles/delete-role Requires ac:delete, and organization:delete for a Role that grants it. Deletes the Role's Grants, Memberships and pending invitations; members holding no other Role leave the organization. Built-in Roles cannot be deleted (409). `DELETE /organizations/{organizationId}/roles/{roleId}` **Responses** - `204` — The Role is deleted. - `default` — The request failed. --- # Get the Permission catalog Source: https://docs.kapten.io/api/auth/roles/get-permission-catalog Every Permission a Grant can give, and for each scope the Permissions it can hold, for example to build a Role editor. The catalog is the same for every organization. `GET /permissions` **Responses** - `200` — The catalog. - `default` — The request failed. Response example, 200: ```json { "resources": [ { "resource": "string", "label": "string", "operations": [ "string" ] } ], "scopes": [ { "type": "organization", "description": "string", "all": true, "permissions": [ { "permission": "string", "label": "string", "description": "string", "requires_all": true } ] } ] } ``` --- # List Roles Source: https://docs.kapten.io/api/auth/roles/list-roles Requires ac:read. The built-in Roles (owner, admin, member) are listed with their fixed Grants. `GET /organizations/{organizationId}/roles` **Responses** - `200` — The Roles and their Grants, oldest first. - `default` — The request failed. Response example, 200: ```json [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "builtin": true, "grants": { "version": 1, "statements": [ { "scope": { "type": "organization", "ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "all": true }, "permissions": [ "string" ] } ] }, "created_at": "2019-08-24T14:15:22Z" } ] ``` --- # Rename a custom Role or replace its Grants Source: https://docs.kapten.io/api/auth/roles/update-role Requires ac:update; replacing the Grants of a Role that grants, or would grant, organization:delete also requires organization:delete. Grants, when present, replace every Grant of the Role. Built-in Roles cannot change (409). `PATCH /organizations/{organizationId}/roles/{roleId}` **Request body** (`application/json`, required) - `name` (string) — Trimmed and lower-cased; 1 to 64 characters, not a built-in name. - `grants` (grant_document) — A Role's Grants as scoped statements. Statements add together. Responses are canonical, one statement per scope instance. Request body example: ```json { "name": "string", "grants": { "version": 1, "statements": [ { "scope": { "type": "organization", "ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "all": true }, "permissions": [ "string" ] } ] } } ``` **Responses** - `200` — The updated Role. - `default` — The request failed. Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "builtin": true, "grants": { "version": 1, "statements": [ { "scope": { "type": "organization", "ids": [ "497f6eca-6276-4993-bfeb-53cbbbba6f08" ], "all": true }, "permissions": [ "string" ] } ] }, "created_at": "2019-08-24T14:15:22Z" } ``` --- # Create or replace the organization's identity provider Source: https://docs.kapten.io/api/auth/sso/configure-sso-connection Requires organization:update. Kapten fetches the issuer's discovery document first, and refuses (400) one it cannot fetch or whose issuer differs. New domains start unverified; domains kept keep their verification. Changing the issuer ends the sessions the former provider started. The provisioning Role must exist and must not grant organization:delete. `PUT /organizations/{organizationId}/sso` **Request body** (`application/json`, required) - `issuer` (string, required) — An https URL (plain http only when auth itself runs on http, in development). - `client_id` (string, required) - `client_secret` (string) — Required to create a connection; omit it to keep the current secret. Stored encrypted and never returned. - `domains` (string[], required) - `enforced` (boolean, required) - `provisioning_role` (string) — Name of a Role to give on first SSO login; omit or leave empty to turn just-in-time provisioning off. Request body example: ```json { "issuer": "string", "client_id": "string", "client_secret": "string", "domains": [ "string" ], "enforced": true, "provisioning_role": "string" } ``` **Responses** - `200` — The saved connection. - `default` — The request failed. Response example, 200: ```json { "issuer": "string", "client_id": "string", "redirect_uri": "string", "domains": [ { "domain": "string", "record_name": "string", "record_value": "string", "verified_at": "2019-08-24T14:15:22Z" } ], "enforced": true, "provisioning_role": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Remove the organization's identity provider Source: https://docs.kapten.io/api/auth/sso/delete-sso-connection Requires organization:update. Members sign in with email links and passkeys again, and the sessions the provider started end; identities linked through it stay with their users but no longer sign in. `DELETE /organizations/{organizationId}/sso` **Responses** - `204` — The connection is removed. - `default` — The request failed. --- # Get the organization's identity provider Source: https://docs.kapten.io/api/auth/sso/get-sso-connection Requires organization:update. Answers 404 when the organization has none. `GET /organizations/{organizationId}/sso` **Responses** - `200` — The connection, without its client secret. - `default` — The request failed. Response example, 200: ```json { "issuer": "string", "client_id": "string", "redirect_uri": "string", "domains": [ { "domain": "string", "record_name": "string", "record_value": "string", "verified_at": "2019-08-24T14:15:22Z" } ], "enforced": true, "provisioning_role": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Verify an email domain of the identity provider Source: https://docs.kapten.io/api/auth/sso/verify-sso-domain Requires organization:update. Kapten looks up the domain's TXT record: 400 when it does not hold the expected value, 409 when another organization verified the domain first, 404 for a domain the connection does not have. Verifying a verified domain changes nothing. `POST /organizations/{organizationId}/sso/domains/{domain}/verify` **Responses** - `200` — The connection, with the domain verified. - `default` — The request failed. Response example, 200: ```json { "issuer": "string", "client_id": "string", "redirect_uri": "string", "domains": [ { "domain": "string", "record_name": "string", "record_value": "string", "verified_at": "2019-08-24T14:15:22Z" } ], "enforced": true, "provisioning_role": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Get token verification keys Source: https://docs.kapten.io/api/auth/tokens/get-jwks Returns the public keys that verify access tokens, including retired keys whose tokens have not expired yet. `GET /.well-known/jwks.json` **Responses** - `200` — The JSON Web Key Set. Response example, 200: ```json { "keys": [ { "kty": "EC", "crv": "P-256", "x": "string", "y": "string", "kid": "string", "use": "sig", "alg": "ES256" } ] } ``` --- # Platform API Source: https://docs.kapten.io/api/platform Manage projects, environments, applications, jobs, databases, pipelines, clusters and their configuration. Every request carries an access token from the [Auth API](/api/auth): see [Authentication](/api#authentication). Version 1.0.0 Base URL: `https://api.kapten.io` ## Environments Environments run components on one cluster. - [`POST /project/{project_id}/environment/{environment_id}/logs`](/api/platform/environment/query-environment-logs) — Query environment logs. ## Components Every component of an environment, and their logs. - [`POST /project/{project_id}/environment/{environment_id}/component/{component_id}/logs`](/api/platform/component/query-component-logs) — Query component logs. ## Pipelines Deploy several components in ordered stages. - [`GET /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/stages`](/api/platform/pipeline/list-pipeline-stages) — List pipeline stages. - [`POST /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/stages`](/api/platform/pipeline/create-pipeline-stage) — Create a pipeline stage. - [`PUT /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/stages/reorder`](/api/platform/pipeline/reorder-pipeline-stages) — Reorder pipeline stages. - [`PUT /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/stages/{pipeline_stage_id}`](/api/platform/pipeline/update-pipeline-stage) — Update a pipeline stage. - [`DELETE /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/stages/{pipeline_stage_id}`](/api/platform/pipeline/delete-pipeline-stage) — Delete a pipeline stage. - [`GET /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/stages/{pipeline_stage_id}/components`](/api/platform/pipeline/list-pipeline-stage-components) — List pipeline stage components. - [`POST /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/stages/{pipeline_stage_id}/components`](/api/platform/pipeline/create-pipeline-stage-component) — Add a component to a pipeline stage. - [`PUT /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/stages/{pipeline_stage_id}/components/{pipeline_stage_component_id}`](/api/platform/pipeline/update-pipeline-stage-component) — Update a pipeline stage component. - [`DELETE /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/stages/{pipeline_stage_id}/components/{pipeline_stage_component_id}`](/api/platform/pipeline/delete-pipeline-stage-component) — Remove a component from a pipeline stage. ## Project variables Variables shared by every environment of a project. - [`GET /project/{project_id}/variable`](/api/platform/project-variables/list-project-variables) — List project variables. - [`POST /project/{project_id}/variable`](/api/platform/project-variables/create-project-variable) — Create a project variable. - [`DELETE /project/{project_id}/variable/{variable_id}`](/api/platform/project-variables/delete-project-variable) — Delete a project variable. - [`PATCH /project/{project_id}/variable/{variable_id}`](/api/platform/project-variables/update-project-variable) — Update a project variable. ## Project secrets Secrets shared by every environment of a project. - [`GET /project/{project_id}/secret`](/api/platform/project-secret/list-project-secrets) — List project secrets. - [`POST /project/{project_id}/secret`](/api/platform/project-secret/create-project-secret) — Create a project secret. - [`DELETE /project/{project_id}/secret/{variable_id}`](/api/platform/project-secret/delete-project-secret) — Delete a project secret. - [`PATCH /project/{project_id}/secret/{variable_id}`](/api/platform/project-secret/update-project-secret) — Update a project secret. ## Environment variables Variables shared by every component of an environment. - [`GET /project/{project_id}/environment/{environment_id}/variable`](/api/platform/environment-variables/list-environment-variables) — List environment variables. - [`POST /project/{project_id}/environment/{environment_id}/variable`](/api/platform/environment-variables/create-environment-variable) — Create an environment variable. - [`DELETE /project/{project_id}/environment/{environment_id}/variable/{variable_id}`](/api/platform/environment-variables/delete-environment-variable) — Delete an environment variable. - [`PATCH /project/{project_id}/environment/{environment_id}/variable/{variable_id}`](/api/platform/environment-variables/update-environment-variable) — Update an environment variable. ## Environment secrets Secrets shared by every component of an environment. - [`GET /project/{project_id}/environment/{environment_id}/secret`](/api/platform/environment-secret/list-environment-secrets) — List environment secrets. - [`POST /project/{project_id}/environment/{environment_id}/secret`](/api/platform/environment-secret/create-environment-secret) — Create an environment secret. - [`DELETE /project/{project_id}/environment/{environment_id}/secret/{variable_id}`](/api/platform/environment-secret/delete-environment-secret) — Delete an environment secret. - [`PATCH /project/{project_id}/environment/{environment_id}/secret/{variable_id}`](/api/platform/environment-secret/update-environment-secret) — Update an environment secret. ## Component variables Variables of one component. - [`GET /project/{project_id}/environment/{environment_id}/component/variable`](/api/platform/component-variables/list-component-variables) — List component variables. - [`POST /project/{project_id}/environment/{environment_id}/component/variable`](/api/platform/component-variables/create-component-variable) — Create a component variable. - [`DELETE /project/{project_id}/environment/{environment_id}/component/variable/{variable_id}`](/api/platform/component-variables/delete-component-variable) — Delete a component variable. - [`PATCH /project/{project_id}/environment/{environment_id}/component/variable/{variable_id}`](/api/platform/component-variables/update-component-variable) — Update a component variable. ## Component secrets Secrets of one component. - [`GET /project/{project_id}/environment/{environment_id}/component/secret`](/api/platform/component-secret/list-component-secrets) — List component secrets. - [`POST /project/{project_id}/environment/{environment_id}/component/secret`](/api/platform/component-secret/create-component-secret) — Create a component secret. - [`DELETE /project/{project_id}/environment/{environment_id}/component/secret/{variable_id}`](/api/platform/component-secret/delete-component-secret) — Delete a component secret. - [`PATCH /project/{project_id}/environment/{environment_id}/component/secret/{variable_id}`](/api/platform/component-secret/update-component-secret) — Update a component secret. ## Clusters Kubernetes clusters connected to the organization. - [`POST /cluster/{cluster_id}/sync`](/api/platform/cluster/sync-cluster) — Sync a cluster. ## Container registries Registries Kapten pulls images from and pushes builds to. - [`GET /container-registry`](/api/platform/container-registry/list-container-registries) — List container registries. - [`POST /container-registry`](/api/platform/container-registry/create-container-registry) — Create a container registry. - [`GET /container-registry/{container_registry_id}`](/api/platform/container-registry/get-container-registry) — Get a container registry. - [`PUT /container-registry/{container_registry_id}`](/api/platform/container-registry/update-container-registry) — Update a container registry. - [`DELETE /container-registry/{container_registry_id}`](/api/platform/container-registry/delete-container-registry) — Delete a container registry. ## GitHub GitHub App installations, their repositories and branches. - [`POST /integration/github/connection-sessions`](/api/platform/github/create-git-hub-connection-session) — Start connecting GitHub. - [`GET /integration/github/installations`](/api/platform/github/list-git-hub-installations) — List GitHub installations. - [`DELETE /integration/github/installations/{installation_id}`](/api/platform/github/disconnect-git-hub-installation) — Disconnect a GitHub installation. - [`GET /integration/github/installations/{installation_id}/repositories`](/api/platform/github/list-git-hub-repositories) — List installation repositories. - [`GET /integration/github/installations/{installation_id}/repositories/{repository_id}/branches`](/api/platform/github/list-git-hub-repository-branches) — List repository branches. ## Authorization Resource names to use in Role grants. - [`GET /authorization/resources`](/api/platform/authorization/list-authorization-resources) — List resources for Role grants. ## Audit log Changes made to the organization's resources. - [`GET /audit-events`](/api/platform/audit/list-audit-events) — List audit events. ## Usage Environment usage, metered per minute. - [`GET /usage/environments`](/api/platform/usage/get-environment-usage) — Get environment usage. ## clusters - [`GET /cluster`](/api/platform/clusters/list-clusters) — List clusters. - [`POST /cluster`](/api/platform/clusters/create-cluster) — Connect a cluster. - [`GET /cluster/{cluster_id}`](/api/platform/clusters/get-cluster) — Get a cluster. - [`PUT /cluster/{cluster_id}`](/api/platform/clusters/update-cluster) — Update a cluster. - [`DELETE /cluster/{cluster_id}`](/api/platform/clusters/delete-cluster) — Delete a cluster. ## projects - [`GET /project`](/api/platform/projects/list-projects) — List projects. - [`POST /project`](/api/platform/projects/create-project) — Create a project. - [`GET /project/{project_id}`](/api/platform/projects/get-project) — Get a project. - [`PUT /project/{project_id}`](/api/platform/projects/update-project) — Update a project. - [`DELETE /project/{project_id}`](/api/platform/projects/delete-project) — Delete a project. ## environments - [`GET /project/{project_id}/environment`](/api/platform/environments/list-environments) — List environments. - [`POST /project/{project_id}/environment`](/api/platform/environments/create-environment) — Create an environment. - [`GET /project/{project_id}/environment/{environment_id}`](/api/platform/environments/get-environment) — Get an environment. - [`PUT /project/{project_id}/environment/{environment_id}`](/api/platform/environments/update-environment) — Update an environment. - [`DELETE /project/{project_id}/environment/{environment_id}`](/api/platform/environments/delete-environment) — Delete an environment. ## components - [`GET /project/{project_id}/environment/{environment_id}/components`](/api/platform/components/list-environment-components) — List environment components. ## pipelines - [`GET /project/{project_id}/environment/{environment_id}/pipelines`](/api/platform/pipelines/list-pipelines) — List pipelines. - [`POST /project/{project_id}/environment/{environment_id}/pipelines`](/api/platform/pipelines/create-pipeline) — Create a pipeline. - [`GET /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}`](/api/platform/pipelines/get-pipeline) — Get a pipeline. - [`PUT /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}`](/api/platform/pipelines/update-pipeline) — Update a pipeline. - [`DELETE /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}`](/api/platform/pipelines/delete-pipeline) — Delete a pipeline. - [`POST /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/run`](/api/platform/pipelines/run-pipeline) — Run a pipeline. - [`GET /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/runs`](/api/platform/pipelines/list-pipeline-runs) — List pipeline runs. - [`GET /project/{project_id}/environment/{environment_id}/pipeline-runs/{pipeline_run_id}`](/api/platform/pipelines/get-pipeline-run) — Get a pipeline run. ## jobs - [`POST /project/{project_id}/environment/{environment_id}/job`](/api/platform/jobs/create-job) — Create a job. - [`GET /project/{project_id}/environment/{environment_id}/job/{job_id}`](/api/platform/jobs/get-job) — Get a job. - [`PUT /project/{project_id}/environment/{environment_id}/job/{job_id}`](/api/platform/jobs/update-job) — Update a job. - [`POST /project/{project_id}/environment/{environment_id}/job/{job_id}/deploy`](/api/platform/jobs/deploy-job) — Deploy a job. - [`GET /project/{project_id}/environment/{environment_id}/job/{job_id}/runs`](/api/platform/jobs/list-job-runs) — List job runs. - [`GET /project/{project_id}/environment/{environment_id}/job/{job_id}/runs/{component_run_id}`](/api/platform/jobs/get-job-run) — Get a job run. - [`POST /project/{project_id}/environment/{environment_id}/job/{job_id}/runs/{component_run_id}/logs`](/api/platform/jobs/query-job-run-logs) — Query job run logs. ## applications - [`POST /project/{project_id}/environment/{environment_id}/application`](/api/platform/applications/create-application) — Create an application. - [`GET /project/{project_id}/environment/{environment_id}/application/{application_id}`](/api/platform/applications/get-application) — Get an application. - [`PUT /project/{project_id}/environment/{environment_id}/application/{application_id}`](/api/platform/applications/update-application) — Update an application. - [`POST /project/{project_id}/environment/{environment_id}/application/{application_id}/deploy`](/api/platform/applications/deploy-application) — Deploy an application. - [`GET /project/{project_id}/environment/{environment_id}/application/{application_id}/runs`](/api/platform/applications/list-application-runs) — List application runs. - [`GET /project/{project_id}/environment/{environment_id}/application/{application_id}/runs/{component_run_id}`](/api/platform/applications/get-application-run) — Get an application run. - [`POST /project/{project_id}/environment/{environment_id}/application/{application_id}/runs/{component_run_id}/logs`](/api/platform/applications/query-application-run-logs) — Query application run logs. ## databases - [`POST /project/{project_id}/environment/{environment_id}/database/postgresql`](/api/platform/databases/create-postgresql-database) — Create a PostgreSQL database. - [`GET /project/{project_id}/environment/{environment_id}/database/postgresql/{database_id}`](/api/platform/databases/get-postgresql-database) — Get a PostgreSQL database. - [`PUT /project/{project_id}/environment/{environment_id}/database/postgresql/{database_id}`](/api/platform/databases/update-postgresql-database) — Update a PostgreSQL database. - [`POST /project/{project_id}/environment/{environment_id}/database/mysql`](/api/platform/databases/create-mysql-database) — Create a MySQL database. - [`GET /project/{project_id}/environment/{environment_id}/database/mysql/{database_id}`](/api/platform/databases/get-mysql-database) — Get a MySQL database. - [`PUT /project/{project_id}/environment/{environment_id}/database/mysql/{database_id}`](/api/platform/databases/update-mysql-database) — Update a MySQL database. - [`POST /project/{project_id}/environment/{environment_id}/database/mongodb`](/api/platform/databases/create-mongodb-database) — Create a MongoDB database. - [`GET /project/{project_id}/environment/{environment_id}/database/mongodb/{database_id}`](/api/platform/databases/get-mongodb-database) — Get a MongoDB database. - [`PUT /project/{project_id}/environment/{environment_id}/database/mongodb/{database_id}`](/api/platform/databases/update-mongodb-database) — Update a MongoDB database. - [`POST /project/{project_id}/environment/{environment_id}/database/redis`](/api/platform/databases/create-redis-database) — Create a Redis database. - [`GET /project/{project_id}/environment/{environment_id}/database/redis/{database_id}`](/api/platform/databases/get-redis-database) — Get a Redis database. - [`PUT /project/{project_id}/environment/{environment_id}/database/redis/{database_id}`](/api/platform/databases/update-redis-database) — Update a Redis database. - [`DELETE /project/{project_id}/environment/{environment_id}/database/{database_id}`](/api/platform/databases/delete-database) — Delete a database. - [`POST /project/{project_id}/environment/{environment_id}/database/{database_id}/deploy`](/api/platform/databases/deploy-database) — Deploy a database. - [`GET /project/{project_id}/environment/{environment_id}/database/{database_id}/runs`](/api/platform/databases/list-database-runs) — List database runs. - [`GET /project/{project_id}/environment/{environment_id}/database/{database_id}/runs/{component_run_id}`](/api/platform/databases/get-database-run) — Get a database run. - [`POST /project/{project_id}/environment/{environment_id}/database/{database_id}/runs/{component_run_id}/logs`](/api/platform/databases/query-database-run-logs) — Query database run logs. --- # Create an application Source: https://docs.kapten.io/api/platform/applications/create-application Creates a long-running application in an environment, built from a GitHub repository or deployed from a container image. `POST /project/{project_id}/environment/{environment_id}/application` **Request body** (`application/json`, required) - `name` (string, required) — Name of the application component. - `description` (string) - `configuration` (object, required) Request body example: ```json { "name": "string", "description": "string", "configuration": { "cpu_limit_in_milli": "2000m", "ram_limit_in_mib": "2048Mi", "cpu_request_in_milli": "1000m", "ram_request_in_mib": "1024Mi", "gpu_limit": 0, "min_running_instances": 1, "max_running_instances": 1, "source": { "type": "container", "image_name": "string", "tag": "string" }, "healthchecks": { "readiness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 }, "liveness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 } }, "ports": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "is_default": true, "internal_port": 1, "external_port": 1, "protocol": "HTTP" } ], "storages": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "mount_path": "string", "size_in_gib": 1, "storage_type": "string" } ], "entrypoint": "string", "arguments": [ "string" ] } } ``` **Responses** - `200` — Application created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "name": "string", "description": "string", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "configuration": { "cpu_limit_in_milli": "2000m", "ram_limit_in_mib": "2048Mi", "cpu_request_in_milli": "1000m", "ram_request_in_mib": "1024Mi", "gpu_limit": 0, "min_running_instances": 1, "max_running_instances": 1, "source": { "type": "container", "image_name": "string", "tag": "string" }, "healthchecks": { "readiness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 }, "liveness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 } }, "ports": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "is_default": true, "internal_port": 1, "external_port": 1, "protocol": "HTTP" } ], "storages": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "mount_path": "string", "size_in_gib": 1, "storage_type": "string" } ], "entrypoint": "string", "arguments": [ "string" ] } } ``` --- # Deploy an application Source: https://docs.kapten.io/api/platform/applications/deploy-application Starts a deployment of the application. `POST /project/{project_id}/environment/{environment_id}/application/{application_id}/deploy` **Responses** - `200` — Application deployment run created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "component_name": "string", "component_sid": "string", "action": "deploy", "trigger": "manual", "status": "QUEUED", "pipeline_context": { "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "pipeline_run_id": "54f73fac-6036-4081-9795-457321f22c71", "stage_run_id": "c6c7d692-4cdb-4e1f-9d55-db374c0d6d91", "pipeline_component_run_id": "63b3c0d9-c480-488a-860f-86e87cc881ec", "stage_component_id": "72d6951a-769e-47ac-a30e-c5b161d3f1fd", "required": true, "timeout_seconds": 0 }, "github_build": { "installation_id": "91166175-c6a9-4caf-88e9-3147ffc9c934", "repository_id": "string", "repository_full_name": "string", "branch": "string", "commit_sha": "string", "trigger": "manual", "image_reference": "string", "image_tag": "string", "index_digest": "string", "platforms": [ "linux/amd64" ] }, "workflow_id": "string", "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "message": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Get an application Source: https://docs.kapten.io/api/platform/applications/get-application Returns an application. `GET /project/{project_id}/environment/{environment_id}/application/{application_id}` **Responses** - `200` — Application retrieved successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "name": "string", "description": "string", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "configuration": { "cpu_limit_in_milli": "2000m", "ram_limit_in_mib": "2048Mi", "cpu_request_in_milli": "1000m", "ram_request_in_mib": "1024Mi", "gpu_limit": 0, "min_running_instances": 1, "max_running_instances": 1, "source": { "type": "container", "image_name": "string", "tag": "string" }, "healthchecks": { "readiness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 }, "liveness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 } }, "ports": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "is_default": true, "internal_port": 1, "external_port": 1, "protocol": "HTTP" } ], "storages": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "mount_path": "string", "size_in_gib": 1, "storage_type": "string" } ], "entrypoint": "string", "arguments": [ "string" ] } } ``` --- # Get an application run Source: https://docs.kapten.io/api/platform/applications/get-application-run Returns one deployment run of the application. `GET /project/{project_id}/environment/{environment_id}/application/{application_id}/runs/{component_run_id}` **Responses** - `200` — Application run retrieved successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "component_name": "string", "component_sid": "string", "action": "deploy", "trigger": "manual", "status": "QUEUED", "pipeline_context": { "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "pipeline_run_id": "54f73fac-6036-4081-9795-457321f22c71", "stage_run_id": "c6c7d692-4cdb-4e1f-9d55-db374c0d6d91", "pipeline_component_run_id": "63b3c0d9-c480-488a-860f-86e87cc881ec", "stage_component_id": "72d6951a-769e-47ac-a30e-c5b161d3f1fd", "required": true, "timeout_seconds": 0 }, "github_build": { "installation_id": "91166175-c6a9-4caf-88e9-3147ffc9c934", "repository_id": "string", "repository_full_name": "string", "branch": "string", "commit_sha": "string", "trigger": "manual", "image_reference": "string", "image_tag": "string", "index_digest": "string", "platforms": [ "linux/amd64" ] }, "workflow_id": "string", "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "message": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # List application runs Source: https://docs.kapten.io/api/platform/applications/list-application-runs Returns the application's deployment runs, a page at a time. `GET /project/{project_id}/environment/{environment_id}/application/{application_id}/runs` **Responses** - `200` — Application runs retrieved successfully - `default` — Error Response example, 200: ```json { "records": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "component_name": "string", "component_sid": "string", "action": "deploy", "trigger": "manual", "status": "QUEUED", "pipeline_context": { "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "pipeline_run_id": "54f73fac-6036-4081-9795-457321f22c71", "stage_run_id": "c6c7d692-4cdb-4e1f-9d55-db374c0d6d91", "pipeline_component_run_id": "63b3c0d9-c480-488a-860f-86e87cc881ec", "stage_component_id": "72d6951a-769e-47ac-a30e-c5b161d3f1fd", "required": true, "timeout_seconds": 0 }, "github_build": { "installation_id": "91166175-c6a9-4caf-88e9-3147ffc9c934", "repository_id": "string", "repository_full_name": "string", "branch": "string", "commit_sha": "string", "trigger": "manual", "image_reference": "string", "image_tag": "string", "index_digest": "string", "platforms": [ "linux/amd64" ] }, "workflow_id": "string", "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "message": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "pagination": { "total_records": 100, "current_page": 1, "total_pages": 10, "next_page": 2, "prev_page": null } } ``` --- # Query application run logs Source: https://docs.kapten.io/api/platform/applications/query-application-run-logs Returns the deployment logs of one application run: what Kapten and the image build did while deploying it, and what its agent on the cluster did. For the application's own output, use the component logs. Without `from` or `to`, the window spans the run, from its start to its end. Logs follow the retention of the log backend, so the logs of an old run may be gone, and runs from before run logs existed return an empty list. `POST /project/{project_id}/environment/{environment_id}/application/{application_id}/runs/{component_run_id}/logs` **Request body** (`application/json`, required) - `view` (string) — Which run log projection to return. - `from` (string) — Inclusive lower bound for the run log time range. - `to` (string) — Inclusive upper bound for the run log time range. - `limit` (integer) — Maximum number of most recent raw backend records to query. - `levels` (string[]) — Optional log levels to include. - `source` (string[]) — Optional timeline event sources to include. - `text` (string) — Optional phrase to search in the log message. Request body example, Timeline only: ```json { "view": "timeline", "limit": 200, "source": [ "control_plane", "agent", "builder" ] } ``` Request body example, Raw run-scoped records only: ```json { "view": "raw", "levels": [ "info", "warn", "error" ], "text": "helm" } ``` Request body example, Timeline and raw records: ```json { "view": "both", "from": "2026-07-03T10:00:00Z", "to": "2026-07-03T10:30:00Z", "limit": 500 } ``` **Responses** - `200` — Application run logs retrieved successfully - `default` — Error Response example, 200: ```json { "timeline": [ { "time": "string", "level": "string", "source": "string", "step": "string", "phase": "string", "backend": "string", "backend_step": "string", "message": "string", "metadata": {}, "duration_ms": 0, "run_status": "string", "error_kind": "string", "event": "kapten.build.phase", "event_version": 0, "platform": "linux/amd64", "publication": "child_manifest" } ], "logs": [ { "msg": {}, "time": "string", "level": "string", "project_id": "string", "environment_id": "string", "component_id": "string", "component_type": "string", "component_run_id": "string", "component_kind": "string", "source": "control_plane", "step": "string", "phase": "string", "backend": "string", "backend_step": "string", "run_status": "string", "duration_ms": 0, "error_kind": "string", "metadata": {}, "event": "kapten.build.phase", "event_version": 0, "platform": "linux/amd64", "publication": "child_manifest" } ], "meta": { "component_run_id": "6037affb-fb72-4f94-b0fb-f75a6be340e1", "logs_backend": "victoria_logs", "default_time_range_applied": true, "details_available": true, "details_unavailable_reason": "string", "pipeline_context": { "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "pipeline_run_id": "54f73fac-6036-4081-9795-457321f22c71", "stage_run_id": "c6c7d692-4cdb-4e1f-9d55-db374c0d6d91", "pipeline_component_run_id": "63b3c0d9-c480-488a-860f-86e87cc881ec", "stage_component_id": "72d6951a-769e-47ac-a30e-c5b161d3f1fd", "required": true, "timeout_seconds": 0 } } } ``` --- # Update an application Source: https://docs.kapten.io/api/platform/applications/update-application Updates an application. Fields left out keep their value. `PUT /project/{project_id}/environment/{environment_id}/application/{application_id}` **Request body** (`application/json`, required) - `name` (string) — Updated application name. - `description` (string) — Updated application description. - `configuration` (object) Request body example: ```json { "name": "string", "description": "string", "configuration": { "cpu_limit_in_milli": "string", "ram_limit_in_mib": "string", "cpu_request_in_milli": "string", "ram_request_in_mib": "string", "gpu_limit": 0, "min_running_instances": 1, "max_running_instances": 1, "source": { "type": "container", "image_name": "string", "tag": "string" }, "healthchecks": { "readiness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 }, "liveness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 } }, "ports": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "is_default": true, "internal_port": 1, "external_port": 1, "protocol": "HTTP" } ], "storages": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "mount_path": "string", "size_in_gib": 1, "storage_type": "string" } ], "entrypoint": "string", "arguments": [ "string" ] } } ``` **Responses** - `200` — Application updated successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "name": "string", "description": "string", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "configuration": { "cpu_limit_in_milli": "2000m", "ram_limit_in_mib": "2048Mi", "cpu_request_in_milli": "1000m", "ram_request_in_mib": "1024Mi", "gpu_limit": 0, "min_running_instances": 1, "max_running_instances": 1, "source": { "type": "container", "image_name": "string", "tag": "string" }, "healthchecks": { "readiness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 }, "liveness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 } }, "ports": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "is_default": true, "internal_port": 1, "external_port": 1, "protocol": "HTTP" } ], "storages": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "mount_path": "string", "size_in_gib": 1, "storage_type": "string" } ], "entrypoint": "string", "arguments": [ "string" ] } } ``` --- # List audit events Source: https://docs.kapten.io/api/platform/audit/list-audit-events Events recorded in the token's organization about projects, environments, components, variables, pipelines, clusters and integrations, newest first. Without a target filter it requires audit:read on the organization and returns every event, including denials and their origin. With `target_type` `project` or `environment` and a `target_id`, the read Permission on that resource is enough: the events about it and everything it contains are returned, without denials or origin. The Auth API serves the organization's own events (members, Roles, OAuth applications, sign-ins) with the same schema and filters. `GET /audit-events` **Responses** - `200` — A page of events. - `default` — Error Response example, 200: ```json { "events": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "source": "auth", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "occurred_at": "2019-08-24T14:15:22Z", "action": "string", "actor": { "type": "user", "id": "string", "email": "string", "name": "string" }, "targets": [ { "type": "string", "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "relation": "primary" } ], "affected_user": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "email": "string", "name": "string" }, "outcome": "allowed", "denial_reason": "string", "changed_fields": [ "string" ], "changes": { "before": {}, "after": {} }, "metadata": {}, "origin": { "ip": "string", "user_agent": "string", "entry_point": "http", "request_id": "string" } } ], "next_cursor": "string" } ``` --- # List resources for Role grants Source: https://docs.kapten.io/api/platform/authorization/list-authorization-resources Names and IDs of the organization's resources that a Role grant can target. Requires the Permission to create or update Roles. Returns no secret. `GET /authorization/resources` **Responses** - `200` — Up to 100 identities; request the next offset until fewer than 100 records are returned. - `400` — Invalid request - `403` — Permission denied - `503` — Authorization or resource catalog unavailable Response example, 200: ```json { "records": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "parentName": "string" } ] } ``` --- # Sync a cluster Source: https://docs.kapten.io/api/platform/cluster/sync-cluster Runs the cluster's setup again, as when it was connected. `POST /cluster/{cluster_id}/sync` **Responses** - `200` — Cluster sync scheduled successfully - `default` — Error Response example, 200: ```json { "cloud_provider": "aws", "created_at": "2025-06-10T22:16:02Z", "deleted_at": "2025-06-10T22:16:02Z", "id": "7362e0d0-72ed-c77b-5c42-f9af9d52fd5f", "name": "zKC", "organization_id": "7a60f26d-0106-02f5-ccf5-98b7c4cdc513", "state": "INITIALIZED", "update_at": "2025-06-10T22:16:02Z" } ``` --- # Connect a cluster Source: https://docs.kapten.io/api/platform/clusters/create-cluster Connects a Kubernetes cluster from its kubeconfig. Kapten then installs its agent on the cluster. `POST /cluster` **Request body** (`application/json`, required) - `name` (string, required) — The name of the cluster. - `cloud_provider` (cloud_provider, required) — The cloud provider for the cluster. - `kube_config` (string, required) — The base64-encoded Kubernetes configuration for the cluster. Request body example: ```json { "name": "my-production-cluster", "cloud_provider": "aws", "kube_config": "YXBpVmVyc2lvbjogdjEKY2x1c3RlcnM6Ci0gY2x1c3RlcjoKICAgIGNlcnRpZmljYXRlLWF1dGhvcml0eS1kYXRhOiBMUzB0TFMwdENrMUZUa1JEUXk1c2NITUtMUzB0TFMwPQogICAgc2VydmVyOiBodHRwczovL2t1YmVybmV0ZXMuZXhhbXBsZS5jb20KICBuYW1lOiBleGFtcGxlLWNsdXN0ZXIK" } ``` **Responses** - `200` — Cluster created successfully - `default` — Error Response example, 200: ```json { "cloud_provider": "aws", "created_at": "2025-06-10T22:16:02Z", "deleted_at": "2025-06-10T22:16:02Z", "id": "7362e0d0-72ed-c77b-5c42-f9af9d52fd5f", "name": "zKC", "organization_id": "7a60f26d-0106-02f5-ccf5-98b7c4cdc513", "state": "INITIALIZED", "update_at": "2025-06-10T22:16:02Z" } ``` --- # Delete a cluster Source: https://docs.kapten.io/api/platform/clusters/delete-cluster Removes a cluster from the organization. `DELETE /cluster/{cluster_id}` **Responses** - `204` — Cluster deleted successfully - `default` — Error --- # Get a cluster Source: https://docs.kapten.io/api/platform/clusters/get-cluster Returns a cluster. `GET /cluster/{cluster_id}` **Responses** - `200` — Cluster retrieved successfully - `default` — Error Response example, 200: ```json { "cloud_provider": "aws", "created_at": "2025-06-10T22:16:02Z", "deleted_at": "2025-06-10T22:16:02Z", "id": "7362e0d0-72ed-c77b-5c42-f9af9d52fd5f", "name": "zKC", "organization_id": "7a60f26d-0106-02f5-ccf5-98b7c4cdc513", "state": "INITIALIZED", "update_at": "2025-06-10T22:16:02Z" } ``` --- # List clusters Source: https://docs.kapten.io/api/platform/clusters/list-clusters Returns the organization's clusters, a page at a time. `GET /cluster` **Responses** - `200` — List of clusters retrieved successfully - `default` — Error Response example, 200: ```json { "records": [ { "cloud_provider": "aws", "created_at": "2025-06-10T22:16:02Z", "deleted_at": "2025-06-10T22:16:02Z", "id": "7362e0d0-72ed-c77b-5c42-f9af9d52fd5f", "name": "zKC", "organization_id": "7a60f26d-0106-02f5-ccf5-98b7c4cdc513", "state": "INITIALIZED", "update_at": "2025-06-10T22:16:02Z" } ], "pagination": { "total_records": 100, "current_page": 1, "total_pages": 10, "next_page": 2, "prev_page": null } } ``` --- # Update a cluster Source: https://docs.kapten.io/api/platform/clusters/update-cluster Updates a cluster's settings. `PUT /cluster/{cluster_id}` **Request body** (`application/json`, required) - `name` (string) — The name of the cluster. - `kube_config` (string) — The base64-encoded Kubernetes configuration for the cluster. Request body example: ```json { "name": "my-production-cluster", "kube_config": "YXBpVmVyc2lvbjogdjEKY2x1c3RlcnM6Ci0gY2x1c3RlcjoKICAgIGNlcnRpZmljYXRlLWF1dGhvcml0eS1kYXRhOiBMUzB0TFMxQ1JVZEpUaUJEUlZKVVNVWkpRMEZVUlMwdExTMHQ=" } ``` **Responses** - `200` — Cluster updated successfully - `default` — Error Response example, 200: ```json { "cloud_provider": "aws", "created_at": "2025-06-10T22:16:02Z", "deleted_at": "2025-06-10T22:16:02Z", "id": "7362e0d0-72ed-c77b-5c42-f9af9d52fd5f", "name": "zKC", "organization_id": "7a60f26d-0106-02f5-ccf5-98b7c4cdc513", "state": "INITIALIZED", "update_at": "2025-06-10T22:16:02Z" } ``` --- # Create a component secret Source: https://docs.kapten.io/api/platform/component-secret/create-component-secret Sets a secret on the component, as a key-value pair or a file. `POST /project/{project_id}/environment/{environment_id}/component/secret` **Request body** (`application/json`, required) - `component_kind` (component_kind, required) — Component kind for component-scoped variables - `component_id` (uuid, required) — A universally unique identifier (UUID) string - `key` (string, required) — Secret key identifier. - `var_type` (variable_type, required) — Variable value type - `value` (string, required) — Secret value to store in Vault. - `file_path` (string) — Required when var\_type is file. Must be an absolute path. Request body example: ```json { "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "key": "string", "var_type": "key_value", "value": "string", "file_path": "string" } ``` **Responses** - `200` — Secret created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "visibility": "project", "var_type": "key_value", "key": "string", "is_secret": true, "managed": true, "value": "string", "file_path": "string", "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Delete a component secret Source: https://docs.kapten.io/api/platform/component-secret/delete-component-secret Deletes a secret from the component. `DELETE /project/{project_id}/environment/{environment_id}/component/secret/{variable_id}` **Responses** - `204` — Secret deleted successfully - `default` — Error --- # List component secrets Source: https://docs.kapten.io/api/platform/component-secret/list-component-secrets Returns the secrets set on the component, a page at a time. `GET /project/{project_id}/environment/{environment_id}/component/secret` **Responses** - `200` — List of secrets retrieved successfully - `default` — Error Response example, 200: ```json { "records": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "visibility": "project", "var_type": "key_value", "key": "string", "is_secret": true, "managed": true, "value": "string", "file_path": "string", "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "pagination": { "total_records": 100, "current_page": 1, "total_pages": 10, "next_page": 2, "prev_page": null } } ``` --- # Update a component secret Source: https://docs.kapten.io/api/platform/component-secret/update-component-secret Updates a secret's key, value or type. `PATCH /project/{project_id}/environment/{environment_id}/component/secret/{variable_id}` **Request body** (`application/json`, required) - `key` (string) — Updated secret key. - `value` (string) — Updated secret value. - `var_type` (variable_type) — Variable value type Request body example: ```json { "key": "string", "value": "string", "var_type": "key_value" } ``` **Responses** - `200` — Secret updated successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "visibility": "project", "var_type": "key_value", "key": "string", "is_secret": true, "managed": true, "value": "string", "file_path": "string", "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Create a component variable Source: https://docs.kapten.io/api/platform/component-variables/create-component-variable Sets a variable on the component, as a key-value pair or a file. `POST /project/{project_id}/environment/{environment_id}/component/variable` **Request body** (`application/json`, required) - `component_kind` (component_kind, required) — Component kind for component-scoped variables - `component_id` (uuid, required) — A universally unique identifier (UUID) string - `key` (string, required) — Variable key identifier. - `var_type` (variable_type, required) — Variable value type - `value` (string, required) — Variable value. - `file_path` (string) — Required when var\_type is file. Must be an absolute path. Request body example: ```json { "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "key": "string", "var_type": "key_value", "value": "string", "file_path": "string" } ``` **Responses** - `200` — Variable created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "visibility": "project", "var_type": "key_value", "key": "string", "is_secret": true, "managed": true, "value": "string", "file_path": "string", "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Delete a component variable Source: https://docs.kapten.io/api/platform/component-variables/delete-component-variable Deletes a variable from the component. `DELETE /project/{project_id}/environment/{environment_id}/component/variable/{variable_id}` **Responses** - `204` — Variable deleted successfully - `default` — Error --- # List component variables Source: https://docs.kapten.io/api/platform/component-variables/list-component-variables Returns the variables set on the component, a page at a time. `GET /project/{project_id}/environment/{environment_id}/component/variable` **Responses** - `200` — List of variables retrieved successfully - `default` — Error Response example, 200: ```json { "records": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "visibility": "project", "var_type": "key_value", "key": "string", "is_secret": true, "managed": true, "value": "string", "file_path": "string", "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "pagination": { "total_records": 100, "current_page": 1, "total_pages": 10, "next_page": 2, "prev_page": null } } ``` --- # Update a component variable Source: https://docs.kapten.io/api/platform/component-variables/update-component-variable Updates a variable's key, value or type. `PATCH /project/{project_id}/environment/{environment_id}/component/variable/{variable_id}` **Request body** (`application/json`, required) - `key` (string) — Updated variable key. - `value` (string) — Updated variable value. - `var_type` (variable_type) — Variable value type Request body example: ```json { "key": "string", "value": "string", "var_type": "key_value" } ``` **Responses** - `200` — Variable updated successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "visibility": "project", "var_type": "key_value", "key": "string", "is_secret": true, "managed": true, "value": "string", "file_path": "string", "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Query component logs Source: https://docs.kapten.io/api/platform/component/query-component-logs Returns the component's log entries that match the query, read through Kapten's agent on its cluster. `POST /project/{project_id}/environment/{environment_id}/component/{component_id}/logs` **Request body** (`application/json`, required) - `query` (string, required) — The user-provided LogsQL query fragment. - `limit` (integer) — Maximum number of most recent log entries to return. Request body example: ```json { "query": "string", "limit": 200 } ``` **Responses** - `200` — Component logs retrieved successfully - `default` — Error Response example, 200: ```json { "records": [ { "msg": {}, "time": "string", "level": "string", "project_id": "string", "environment_id": "string", "component_id": "string", "component_type": "string", "component_run_id": "string", "component_kind": "string", "source": "control_plane", "step": "string", "phase": "string", "backend": "string", "backend_step": "string", "run_status": "string", "duration_ms": 0, "error_kind": "string", "metadata": {}, "event": "kapten.build.phase", "event_version": 0, "platform": "linux/amd64", "publication": "child_manifest" } ] } ``` --- # List environment components Source: https://docs.kapten.io/api/platform/components/list-environment-components Returns the applications, jobs and databases of an environment, a page at a time. `GET /project/{project_id}/environment/{environment_id}/components` **Responses** - `200` — Environment components retrieved successfully - `default` — Error Response example, 200: ```json { "records": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "s_id": "string", "name": "string", "description": "string", "kind": "Kjob", "subtype": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "resource_state": "OUT_OF_DATE" } ], "pagination": { "total_records": 100, "current_page": 1, "total_pages": 10, "next_page": 2, "prev_page": null } } ``` --- # Create a container registry Source: https://docs.kapten.io/api/platform/container-registry/create-container-registry Adds a container registry to the organization, with the credentials Kapten uses to pull and push images. `POST /container-registry` **Request body** (`application/json`, required) Request body example: ```json { "name": "string", "description": "string", "type": "STANDARD", "url": "string", "username": "string", "password": "string" } ``` **Responses** - `200` — Container registry created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "s_id": "string", "name": "string", "description": "string", "type": "STANDARD", "configuration": { "url": "string", "region": "string", "role_arn": "string" }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z" } ``` --- # Delete a container registry Source: https://docs.kapten.io/api/platform/container-registry/delete-container-registry Removes a container registry and deletes its stored credentials. `DELETE /container-registry/{container_registry_id}` **Responses** - `204` — Container registry deleted successfully - `default` — Error --- # Get a container registry Source: https://docs.kapten.io/api/platform/container-registry/get-container-registry Returns a container registry. `GET /container-registry/{container_registry_id}` **Responses** - `200` — Container registry retrieved successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "s_id": "string", "name": "string", "description": "string", "type": "STANDARD", "configuration": { "url": "string", "region": "string", "role_arn": "string" }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z" } ``` --- # List container registries Source: https://docs.kapten.io/api/platform/container-registry/list-container-registries Returns the organization's container registries, a page at a time. `GET /container-registry` **Responses** - `200` — Container registries retrieved successfully - `default` — Error Response example, 200: ```json { "records": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "s_id": "string", "name": "string", "description": "string", "type": "STANDARD", "configuration": { "url": "string", "region": "string", "role_arn": "string" }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z" } ], "pagination": { "total_records": 100, "current_page": 1, "total_pages": 10, "next_page": 2, "prev_page": null } } ``` --- # Update a container registry Source: https://docs.kapten.io/api/platform/container-registry/update-container-registry Updates a container registry and its credentials. `PUT /container-registry/{container_registry_id}` **Request body** (`application/json`, required) - `name` (string) — Updated container registry name. - `description` (string) — Updated container registry description. - `url` (string) — Updated registry URL. - `username` (string) — Updated standard registry username. - `password` (string) — Updated standard registry password. - `access_key_id` (string) — Updated access key identifier. - `secret_access_key` (string) — Updated secret access key. - `region` (string) — Updated registry region. - `role_arn` (string) — Updated AWS role ARN. - `json_credentials` (string) — Updated GCP Artifact Registry JSON credentials. Request body example: ```json { "name": "string", "description": "string", "url": "string", "username": "string", "password": "string", "access_key_id": "string", "secret_access_key": "string", "region": "string", "role_arn": "string", "json_credentials": "string" } ``` **Responses** - `200` — Container registry updated successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "s_id": "string", "name": "string", "description": "string", "type": "STANDARD", "configuration": { "url": "string", "region": "string", "role_arn": "string" }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z" } ``` --- # Create a MongoDB database Source: https://docs.kapten.io/api/platform/databases/create-mongodb-database Creates a MongoDB database in an environment. `POST /project/{project_id}/environment/{environment_id}/database/mongodb` **Request body** (`application/json`, required) Request body example: ```json { "name": "string", "description": "string", "version": "string", "accessibility": "PRIVATE", "provisioning": "IN_CLUSTER", "configuration": { "database_name": "string", "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0 } } } ``` **Responses** - `200` — MongoDB database created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "s_id": "string", "name": "string", "description": "string", "type": "POSTGRESQL", "version": "string", "provisioning": "IN_CLUSTER", "accessibility": "PRIVATE", "configuration": { "database_name": "string", "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0, "database_instance_tier": "string", "database_disk_type": "string", "database_disk_iops": 0 } }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "resource_state": "OUT_OF_DATE" } ``` --- # Create a MySQL database Source: https://docs.kapten.io/api/platform/databases/create-mysql-database Creates a MySQL database in an environment. `POST /project/{project_id}/environment/{environment_id}/database/mysql` **Request body** (`application/json`, required) Request body example: ```json { "name": "string", "description": "string", "version": "string", "accessibility": "PRIVATE", "provisioning": "IN_CLUSTER", "configuration": { "database_name": "string", "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0 } } } ``` **Responses** - `200` — MySQL database created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "s_id": "string", "name": "string", "description": "string", "type": "POSTGRESQL", "version": "string", "provisioning": "IN_CLUSTER", "accessibility": "PRIVATE", "configuration": { "database_name": "string", "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0, "database_instance_tier": "string", "database_disk_type": "string", "database_disk_iops": 0 } }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "resource_state": "OUT_OF_DATE" } ``` --- # Create a PostgreSQL database Source: https://docs.kapten.io/api/platform/databases/create-postgresql-database Creates a PostgreSQL database in an environment. `POST /project/{project_id}/environment/{environment_id}/database/postgresql` **Request body** (`application/json`, required) Request body example: ```json { "name": "string", "description": "string", "version": "string", "accessibility": "PRIVATE", "provisioning": "IN_CLUSTER", "configuration": { "database_name": "string", "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0 } } } ``` **Responses** - `200` — PostgreSQL database created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "s_id": "string", "name": "string", "description": "string", "type": "POSTGRESQL", "version": "string", "provisioning": "IN_CLUSTER", "accessibility": "PRIVATE", "configuration": { "database_name": "string", "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0, "database_instance_tier": "string", "database_disk_type": "string", "database_disk_iops": 0 } }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "resource_state": "OUT_OF_DATE" } ``` --- # Create a Redis database Source: https://docs.kapten.io/api/platform/databases/create-redis-database Creates a Redis database in an environment. `POST /project/{project_id}/environment/{environment_id}/database/redis` **Request body** (`application/json`, required) Request body example: ```json { "name": "string", "description": "string", "version": "string", "accessibility": "PRIVATE", "provisioning": "IN_CLUSTER", "configuration": { "database_name": "string", "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0 } } } ``` **Responses** - `200` — Redis database created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "s_id": "string", "name": "string", "description": "string", "type": "POSTGRESQL", "version": "string", "provisioning": "IN_CLUSTER", "accessibility": "PRIVATE", "configuration": { "database_name": "string", "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0, "database_instance_tier": "string", "database_disk_type": "string", "database_disk_iops": 0 } }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "resource_state": "OUT_OF_DATE" } ``` --- # Delete a database Source: https://docs.kapten.io/api/platform/databases/delete-database Deletes a database, with the variables and secrets Kapten created for it. `DELETE /project/{project_id}/environment/{environment_id}/database/{database_id}` **Responses** - `204` — Database deleted successfully - `default` — Error --- # Deploy a database Source: https://docs.kapten.io/api/platform/databases/deploy-database Starts a deployment of the database. `POST /project/{project_id}/environment/{environment_id}/database/{database_id}/deploy` **Responses** - `200` — Database deployment run queued successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "component_name": "string", "component_sid": "string", "action": "deploy", "trigger": "manual", "status": "QUEUED", "pipeline_context": { "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "pipeline_run_id": "54f73fac-6036-4081-9795-457321f22c71", "stage_run_id": "c6c7d692-4cdb-4e1f-9d55-db374c0d6d91", "pipeline_component_run_id": "63b3c0d9-c480-488a-860f-86e87cc881ec", "stage_component_id": "72d6951a-769e-47ac-a30e-c5b161d3f1fd", "required": true, "timeout_seconds": 0 }, "github_build": { "installation_id": "91166175-c6a9-4caf-88e9-3147ffc9c934", "repository_id": "string", "repository_full_name": "string", "branch": "string", "commit_sha": "string", "trigger": "manual", "image_reference": "string", "image_tag": "string", "index_digest": "string", "platforms": [ "linux/amd64" ] }, "workflow_id": "string", "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "message": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Get a database run Source: https://docs.kapten.io/api/platform/databases/get-database-run Returns one deployment run of the database. `GET /project/{project_id}/environment/{environment_id}/database/{database_id}/runs/{component_run_id}` **Responses** - `200` — Database run retrieved successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "component_name": "string", "component_sid": "string", "action": "deploy", "trigger": "manual", "status": "QUEUED", "pipeline_context": { "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "pipeline_run_id": "54f73fac-6036-4081-9795-457321f22c71", "stage_run_id": "c6c7d692-4cdb-4e1f-9d55-db374c0d6d91", "pipeline_component_run_id": "63b3c0d9-c480-488a-860f-86e87cc881ec", "stage_component_id": "72d6951a-769e-47ac-a30e-c5b161d3f1fd", "required": true, "timeout_seconds": 0 }, "github_build": { "installation_id": "91166175-c6a9-4caf-88e9-3147ffc9c934", "repository_id": "string", "repository_full_name": "string", "branch": "string", "commit_sha": "string", "trigger": "manual", "image_reference": "string", "image_tag": "string", "index_digest": "string", "platforms": [ "linux/amd64" ] }, "workflow_id": "string", "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "message": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Get a MongoDB database Source: https://docs.kapten.io/api/platform/databases/get-mongodb-database Returns a MongoDB database. `GET /project/{project_id}/environment/{environment_id}/database/mongodb/{database_id}` **Responses** - `200` — MongoDB database retrieved successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "s_id": "string", "name": "string", "description": "string", "type": "POSTGRESQL", "version": "string", "provisioning": "IN_CLUSTER", "accessibility": "PRIVATE", "configuration": { "database_name": "string", "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0, "database_instance_tier": "string", "database_disk_type": "string", "database_disk_iops": 0 } }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "resource_state": "OUT_OF_DATE" } ``` --- # Get a MySQL database Source: https://docs.kapten.io/api/platform/databases/get-mysql-database Returns a MySQL database. `GET /project/{project_id}/environment/{environment_id}/database/mysql/{database_id}` **Responses** - `200` — MySQL database retrieved successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "s_id": "string", "name": "string", "description": "string", "type": "POSTGRESQL", "version": "string", "provisioning": "IN_CLUSTER", "accessibility": "PRIVATE", "configuration": { "database_name": "string", "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0, "database_instance_tier": "string", "database_disk_type": "string", "database_disk_iops": 0 } }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "resource_state": "OUT_OF_DATE" } ``` --- # Get a PostgreSQL database Source: https://docs.kapten.io/api/platform/databases/get-postgresql-database Returns a PostgreSQL database. `GET /project/{project_id}/environment/{environment_id}/database/postgresql/{database_id}` **Responses** - `200` — PostgreSQL database retrieved successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "s_id": "string", "name": "string", "description": "string", "type": "POSTGRESQL", "version": "string", "provisioning": "IN_CLUSTER", "accessibility": "PRIVATE", "configuration": { "database_name": "string", "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0, "database_instance_tier": "string", "database_disk_type": "string", "database_disk_iops": 0 } }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "resource_state": "OUT_OF_DATE" } ``` --- # Get a Redis database Source: https://docs.kapten.io/api/platform/databases/get-redis-database Returns a Redis database. `GET /project/{project_id}/environment/{environment_id}/database/redis/{database_id}` **Responses** - `200` — Redis database retrieved successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "s_id": "string", "name": "string", "description": "string", "type": "POSTGRESQL", "version": "string", "provisioning": "IN_CLUSTER", "accessibility": "PRIVATE", "configuration": { "database_name": "string", "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0, "database_instance_tier": "string", "database_disk_type": "string", "database_disk_iops": 0 } }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "resource_state": "OUT_OF_DATE" } ``` --- # List database runs Source: https://docs.kapten.io/api/platform/databases/list-database-runs Returns the database's deployment runs, a page at a time. `GET /project/{project_id}/environment/{environment_id}/database/{database_id}/runs` **Responses** - `200` — Database runs retrieved successfully - `default` — Error Response example, 200: ```json { "records": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "component_name": "string", "component_sid": "string", "action": "deploy", "trigger": "manual", "status": "QUEUED", "pipeline_context": { "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "pipeline_run_id": "54f73fac-6036-4081-9795-457321f22c71", "stage_run_id": "c6c7d692-4cdb-4e1f-9d55-db374c0d6d91", "pipeline_component_run_id": "63b3c0d9-c480-488a-860f-86e87cc881ec", "stage_component_id": "72d6951a-769e-47ac-a30e-c5b161d3f1fd", "required": true, "timeout_seconds": 0 }, "github_build": { "installation_id": "91166175-c6a9-4caf-88e9-3147ffc9c934", "repository_id": "string", "repository_full_name": "string", "branch": "string", "commit_sha": "string", "trigger": "manual", "image_reference": "string", "image_tag": "string", "index_digest": "string", "platforms": [ "linux/amd64" ] }, "workflow_id": "string", "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "message": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "pagination": { "total_records": 100, "current_page": 1, "total_pages": 10, "next_page": 2, "prev_page": null } } ``` --- # Query database run logs Source: https://docs.kapten.io/api/platform/databases/query-database-run-logs Returns the deployment logs of one database run: what Kapten did while deploying it, and what its agent on the cluster did. For the database's own output, use the component logs. Without `from` or `to`, the window spans the run, from its start to its end. Logs follow the retention of the log backend, so the logs of an old run may be gone, and runs from before run logs existed return an empty list. `POST /project/{project_id}/environment/{environment_id}/database/{database_id}/runs/{component_run_id}/logs` **Request body** (`application/json`, required) - `view` (string) — Which run log projection to return. - `from` (string) — Inclusive lower bound for the run log time range. - `to` (string) — Inclusive upper bound for the run log time range. - `limit` (integer) — Maximum number of most recent raw backend records to query. - `levels` (string[]) — Optional log levels to include. - `source` (string[]) — Optional timeline event sources to include. - `text` (string) — Optional phrase to search in the log message. Request body example, Timeline only: ```json { "view": "timeline", "limit": 200, "source": [ "control_plane", "agent" ] } ``` Request body example, Raw run-scoped records only: ```json { "view": "raw", "levels": [ "info", "warn", "error" ], "text": "helm" } ``` Request body example, Timeline and raw records: ```json { "view": "both", "from": "2026-07-03T10:00:00Z", "to": "2026-07-03T10:30:00Z", "limit": 500 } ``` **Responses** - `200` — Database run logs retrieved successfully - `default` — Error Response example, 200: ```json { "timeline": [ { "time": "string", "level": "string", "source": "string", "step": "string", "phase": "string", "backend": "string", "backend_step": "string", "message": "string", "metadata": {}, "duration_ms": 0, "run_status": "string", "error_kind": "string", "event": "kapten.build.phase", "event_version": 0, "platform": "linux/amd64", "publication": "child_manifest" } ], "logs": [ { "msg": {}, "time": "string", "level": "string", "project_id": "string", "environment_id": "string", "component_id": "string", "component_type": "string", "component_run_id": "string", "component_kind": "string", "source": "control_plane", "step": "string", "phase": "string", "backend": "string", "backend_step": "string", "run_status": "string", "duration_ms": 0, "error_kind": "string", "metadata": {}, "event": "kapten.build.phase", "event_version": 0, "platform": "linux/amd64", "publication": "child_manifest" } ], "meta": { "component_run_id": "6037affb-fb72-4f94-b0fb-f75a6be340e1", "logs_backend": "victoria_logs", "default_time_range_applied": true, "details_available": true, "details_unavailable_reason": "string", "pipeline_context": { "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "pipeline_run_id": "54f73fac-6036-4081-9795-457321f22c71", "stage_run_id": "c6c7d692-4cdb-4e1f-9d55-db374c0d6d91", "pipeline_component_run_id": "63b3c0d9-c480-488a-860f-86e87cc881ec", "stage_component_id": "72d6951a-769e-47ac-a30e-c5b161d3f1fd", "required": true, "timeout_seconds": 0 } } } ``` --- # Update a MongoDB database Source: https://docs.kapten.io/api/platform/databases/update-mongodb-database Updates a MongoDB database's settings. Its provisioning and `database_name` cannot change. `PUT /project/{project_id}/environment/{environment_id}/database/mongodb/{database_id}` **Request body** (`application/json`, required) - `name` (string) — Updated database name. - `description` (string) — Updated database description. - `version` (string) — Updated database engine version. - `accessibility` (database_accessibility) — Updated database network accessibility. - `configuration` (object) Request body example: ```json { "name": "string", "description": "string", "version": "string", "accessibility": "PRIVATE", "configuration": { "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0, "database_instance_tier": "string", "database_disk_type": "string", "database_disk_iops": 0 } } } ``` **Responses** - `200` — MongoDB database updated successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "s_id": "string", "name": "string", "description": "string", "type": "POSTGRESQL", "version": "string", "provisioning": "IN_CLUSTER", "accessibility": "PRIVATE", "configuration": { "database_name": "string", "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0, "database_instance_tier": "string", "database_disk_type": "string", "database_disk_iops": 0 } }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "resource_state": "OUT_OF_DATE" } ``` --- # Update a MySQL database Source: https://docs.kapten.io/api/platform/databases/update-mysql-database Updates a MySQL database's settings. Its provisioning and `database_name` cannot change. `PUT /project/{project_id}/environment/{environment_id}/database/mysql/{database_id}` **Request body** (`application/json`, required) - `name` (string) — Updated database name. - `description` (string) — Updated database description. - `version` (string) — Updated database engine version. - `accessibility` (database_accessibility) — Updated database network accessibility. - `configuration` (object) Request body example: ```json { "name": "string", "description": "string", "version": "string", "accessibility": "PRIVATE", "configuration": { "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0, "database_instance_tier": "string", "database_disk_type": "string", "database_disk_iops": 0 } } } ``` **Responses** - `200` — MySQL database updated successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "s_id": "string", "name": "string", "description": "string", "type": "POSTGRESQL", "version": "string", "provisioning": "IN_CLUSTER", "accessibility": "PRIVATE", "configuration": { "database_name": "string", "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0, "database_instance_tier": "string", "database_disk_type": "string", "database_disk_iops": 0 } }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "resource_state": "OUT_OF_DATE" } ``` --- # Update a PostgreSQL database Source: https://docs.kapten.io/api/platform/databases/update-postgresql-database Updates a PostgreSQL database's settings. Its provisioning and `database_name` cannot change. `PUT /project/{project_id}/environment/{environment_id}/database/postgresql/{database_id}` **Request body** (`application/json`, required) - `name` (string) — Updated database name. - `description` (string) — Updated database description. - `version` (string) — Updated database engine version. - `accessibility` (database_accessibility) — Updated database network accessibility. - `configuration` (object) Request body example: ```json { "name": "string", "description": "string", "version": "string", "accessibility": "PRIVATE", "configuration": { "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0, "database_instance_tier": "string", "database_disk_type": "string", "database_disk_iops": 0 } } } ``` **Responses** - `200` — PostgreSQL database updated successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "s_id": "string", "name": "string", "description": "string", "type": "POSTGRESQL", "version": "string", "provisioning": "IN_CLUSTER", "accessibility": "PRIVATE", "configuration": { "database_name": "string", "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0, "database_instance_tier": "string", "database_disk_type": "string", "database_disk_iops": 0 } }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "resource_state": "OUT_OF_DATE" } ``` --- # Update a Redis database Source: https://docs.kapten.io/api/platform/databases/update-redis-database Updates a Redis database's settings. Its provisioning and `database_name` cannot change. `PUT /project/{project_id}/environment/{environment_id}/database/redis/{database_id}` **Request body** (`application/json`, required) - `name` (string) — Updated database name. - `description` (string) — Updated database description. - `version` (string) — Updated database engine version. - `accessibility` (database_accessibility) — Updated database network accessibility. - `configuration` (object) Request body example: ```json { "name": "string", "description": "string", "version": "string", "accessibility": "PRIVATE", "configuration": { "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0, "database_instance_tier": "string", "database_disk_type": "string", "database_disk_iops": 0 } } } ``` **Responses** - `200` — Redis database updated successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "s_id": "string", "name": "string", "description": "string", "type": "POSTGRESQL", "version": "string", "provisioning": "IN_CLUSTER", "accessibility": "PRIVATE", "configuration": { "database_name": "string", "encrypt_disk": true, "activate_high_availability": true, "activate_backups": true, "resources": { "cpu_request_in_milli": 0, "cpu_limit_in_milli": 0, "ram_request_in_mib": 0, "ram_limit_in_mib": 0, "disk_size_in_gib": 0, "database_instance_tier": "string", "database_disk_type": "string", "database_disk_iops": 0 } }, "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "resource_state": "OUT_OF_DATE" } ``` --- # Create an environment secret Source: https://docs.kapten.io/api/platform/environment-secret/create-environment-secret Sets a secret on the environment, as a key-value pair or a file. `POST /project/{project_id}/environment/{environment_id}/secret` **Request body** (`application/json`, required) - `key` (string, required) — Secret key identifier. - `var_type` (variable_type, required) — Variable value type - `value` (string, required) — Secret value to store in Vault. - `file_path` (string) — Required when var\_type is file. Must be an absolute path. Request body example: ```json { "key": "string", "var_type": "key_value", "value": "string", "file_path": "string" } ``` **Responses** - `200` — Secret created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "visibility": "project", "var_type": "key_value", "key": "string", "is_secret": true, "managed": true, "value": "string", "file_path": "string", "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Delete an environment secret Source: https://docs.kapten.io/api/platform/environment-secret/delete-environment-secret Deletes a secret from the environment. `DELETE /project/{project_id}/environment/{environment_id}/secret/{variable_id}` **Responses** - `204` — Secret deleted successfully - `default` — Error --- # List environment secrets Source: https://docs.kapten.io/api/platform/environment-secret/list-environment-secrets Returns the secrets set on the environment, a page at a time. `GET /project/{project_id}/environment/{environment_id}/secret` **Responses** - `200` — List of secrets retrieved successfully - `default` — Error Response example, 200: ```json { "records": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "visibility": "project", "var_type": "key_value", "key": "string", "is_secret": true, "managed": true, "value": "string", "file_path": "string", "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "pagination": { "total_records": 100, "current_page": 1, "total_pages": 10, "next_page": 2, "prev_page": null } } ``` --- # Update an environment secret Source: https://docs.kapten.io/api/platform/environment-secret/update-environment-secret Updates a secret's key, value or type. `PATCH /project/{project_id}/environment/{environment_id}/secret/{variable_id}` **Request body** (`application/json`, required) - `key` (string) — Updated secret key. - `value` (string) — Updated secret value. - `var_type` (variable_type) — Variable value type Request body example: ```json { "key": "string", "value": "string", "var_type": "key_value" } ``` **Responses** - `200` — Secret updated successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "visibility": "project", "var_type": "key_value", "key": "string", "is_secret": true, "managed": true, "value": "string", "file_path": "string", "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Create an environment variable Source: https://docs.kapten.io/api/platform/environment-variables/create-environment-variable Sets a variable on the environment, as a key-value pair or a file. `POST /project/{project_id}/environment/{environment_id}/variable` **Request body** (`application/json`, required) - `key` (string, required) — Variable key identifier. - `var_type` (variable_type, required) — Variable value type - `value` (string, required) — Variable value. - `file_path` (string) — Required when var\_type is file. Must be an absolute path. Request body example: ```json { "key": "string", "var_type": "key_value", "value": "string", "file_path": "string" } ``` **Responses** - `200` — Variable created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "visibility": "project", "var_type": "key_value", "key": "string", "is_secret": true, "managed": true, "value": "string", "file_path": "string", "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Delete an environment variable Source: https://docs.kapten.io/api/platform/environment-variables/delete-environment-variable Deletes a variable from the environment. `DELETE /project/{project_id}/environment/{environment_id}/variable/{variable_id}` **Responses** - `204` — Variable deleted successfully - `default` — Error --- # List environment variables Source: https://docs.kapten.io/api/platform/environment-variables/list-environment-variables Returns the variables set on the environment, a page at a time. `GET /project/{project_id}/environment/{environment_id}/variable` **Responses** - `200` — List of variables retrieved successfully - `default` — Error Response example, 200: ```json { "records": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "visibility": "project", "var_type": "key_value", "key": "string", "is_secret": true, "managed": true, "value": "string", "file_path": "string", "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "pagination": { "total_records": 100, "current_page": 1, "total_pages": 10, "next_page": 2, "prev_page": null } } ``` --- # Update an environment variable Source: https://docs.kapten.io/api/platform/environment-variables/update-environment-variable Updates a variable's key, value or type. `PATCH /project/{project_id}/environment/{environment_id}/variable/{variable_id}` **Request body** (`application/json`, required) - `key` (string) — Updated variable key. - `value` (string) — Updated variable value. - `var_type` (variable_type) — Variable value type Request body example: ```json { "key": "string", "value": "string", "var_type": "key_value" } ``` **Responses** - `200` — Variable updated successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "visibility": "project", "var_type": "key_value", "key": "string", "is_secret": true, "managed": true, "value": "string", "file_path": "string", "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Query environment logs Source: https://docs.kapten.io/api/platform/environment/query-environment-logs Returns the environment's log entries that match the query, read through Kapten's agent on its cluster. `POST /project/{project_id}/environment/{environment_id}/logs` **Request body** (`application/json`, required) - `query` (string, required) — The user-provided LogsQL query fragment. - `limit` (integer) — Maximum number of most recent log entries to return. Request body example: ```json { "query": "string", "limit": 200 } ``` **Responses** - `200` — Environment logs retrieved successfully - `default` — Error Response example, 200: ```json { "records": [ { "msg": {}, "time": "string", "level": "string", "project_id": "string", "environment_id": "string", "component_id": "string", "component_type": "string", "component_run_id": "string", "component_kind": "string", "source": "control_plane", "step": "string", "phase": "string", "backend": "string", "backend_step": "string", "run_status": "string", "duration_ms": 0, "error_kind": "string", "metadata": {}, "event": "kapten.build.phase", "event_version": 0, "platform": "linux/amd64", "publication": "child_manifest" } ] } ``` --- # Create an environment Source: https://docs.kapten.io/api/platform/environments/create-environment Creates an environment in a project, on one of the organization's clusters. `POST /project/{project_id}/environment` **Request body** (`application/json`, required) - `cluster_id` (uuid, required) — A universally unique identifier (UUID) string - `name` (string, required) — The name of the environment. - `type` (environment_type, required) — The type of the environment. Request body example: ```json { "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "name": "string", "type": "development" } ``` **Responses** - `200` — Environment created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "name": "string", "type": "development", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z" } ``` --- # Delete an environment Source: https://docs.kapten.io/api/platform/environments/delete-environment Deletes an environment, with its variables and secrets. This cannot be undone. `DELETE /project/{project_id}/environment/{environment_id}` **Responses** - `204` — Environment deleted successfully - `default` — Error --- # Get an environment Source: https://docs.kapten.io/api/platform/environments/get-environment Returns an environment. `GET /project/{project_id}/environment/{environment_id}` **Responses** - `200` — Environment retrieved successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "name": "string", "type": "development", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z" } ``` --- # List environments Source: https://docs.kapten.io/api/platform/environments/list-environments Returns a project's environments, a page at a time. `GET /project/{project_id}/environment` **Responses** - `200` — List of environments retrieved successfully - `default` — Error Response example, 200: ```json { "records": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "name": "string", "type": "development", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z" } ], "pagination": { "total_records": 100, "current_page": 1, "total_pages": 10, "next_page": 2, "prev_page": null } } ``` --- # Update an environment Source: https://docs.kapten.io/api/platform/environments/update-environment Updates an environment. Fields left out keep their value. `PUT /project/{project_id}/environment/{environment_id}` **Request body** (`application/json`, required) - `name` (string) — The updated name of the environment. Request body example: ```json { "name": "string" } ``` **Responses** - `200` — Environment updated successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "name": "string", "type": "development", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z" } ``` --- # Start connecting GitHub Source: https://docs.kapten.io/api/platform/github/create-git-hub-connection-session Starts installing Kapten's GitHub App for the organization. Returns the GitHub URL to send the user to; GitHub sends them back to Kapten once the app is installed. `POST /integration/github/connection-sessions` **Request body** (`application/json`, required) - `return_target` (string, required) - `kapplication_id` (string | null) Request body example: ```json { "return_target": "organization_settings", "kapplication_id": "f175e330-5cbe-4cb3-93cb-ec786e7bd8af" } ``` **Responses** - `200` — GitHub connection session created - `default` — Error Response example, 200: ```json { "setup_url": "http://example.com", "expires_at": "2019-08-24T14:15:22Z" } ``` --- # Disconnect a GitHub installation Source: https://docs.kapten.io/api/platform/github/disconnect-git-hub-installation Disconnects a GitHub installation from the organization. The app stays installed on GitHub: uninstall it there to revoke its access. `DELETE /integration/github/installations/{installation_id}` **Responses** - `204` — GitHub installation disconnected - `default` — Error --- # List GitHub installations Source: https://docs.kapten.io/api/platform/github/list-git-hub-installations Returns the organization's GitHub App installations. `GET /integration/github/installations` **Responses** - `200` — GitHub installations retrieved - `default` — Error Response example, 200: ```json { "records": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "installation_id": "string", "account_id": "string", "account_login": "string", "account_type": "Organization", "repository_selection": "all", "permissions": { "metadata": "string", "contents": "string" }, "events": [ "string" ], "status": "active", "installed_at": "2019-08-24T14:15:22Z", "suspended_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z", "last_synchronized_at": "2019-08-24T14:15:22Z" } ], "pagination": { "total_records": 100, "current_page": 1, "total_pages": 10, "next_page": 2, "prev_page": null } } ``` --- # List installation repositories Source: https://docs.kapten.io/api/platform/github/list-git-hub-repositories Returns the repositories the GitHub installation can read now. `GET /integration/github/installations/{installation_id}/repositories` **Responses** - `200` — Live GitHub repositories retrieved - `422` — Installation is inactive or inaccessible - `503` — GitHub is temporarily unavailable - `default` — Error Response example, 200: ```json { "records": [ { "id": "string", "owner": "string", "name": "string", "full_name": "string", "private": true, "default_branch": "string", "archived": true } ], "page": 1, "per_page": 1, "total_count": 0, "next_page": 1 } ``` --- # List repository branches Source: https://docs.kapten.io/api/platform/github/list-git-hub-repository-branches Returns a repository's branches, read from GitHub, once the installation is checked to still have access to the repository. `GET /integration/github/installations/{installation_id}/repositories/{repository_id}/branches` **Responses** - `200` — Live GitHub branches retrieved - `422` — Installation or repository is inactive or inaccessible - `503` — GitHub is temporarily unavailable - `default` — Error Response example, 200: ```json { "records": [ { "name": "string", "head_sha": "string", "protected": true } ], "page": 1, "per_page": 1, "next_page": 1 } ``` --- # Create a job Source: https://docs.kapten.io/api/platform/jobs/create-job Creates a cron or one-off job in an environment. `POST /project/{project_id}/environment/{environment_id}/job` **Request body** (`application/json`, required) - `name` (string, required) — Name of the job - `description` (string) - `timezone` (string) — Specifies the timezone for the cron job. Defaults to UTC. - `cron` (string) — Specifies the job schedule using standard cron format (minute hour day month weekday). Does not include seconds field - follows the traditional 5-field cron syntax. - `configuration` (object, required) Request body example: ```json { "name": "string", "description": "string", "timezone": "string", "cron": "string", "configuration": { "cpu_limit_in_milli": "2000m", "ram_limit_in_mib": "2048Mi", "cpu_request_in_milli": "1000m", "ram_request_in_mib": "1024Mi", "max_nb_restart": 0, "max_duration_seconds": 0, "default_port": null, "source": { "image_name": "string", "tag": "string" }, "healthchecks": { "readiness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 }, "liveness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 } }, "entrypoint": "string", "arguments": [ "string" ] } } ``` **Responses** - `200` — Job created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "name": "string", "description": "string", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "type": "cron", "timezone": "string", "cron": "string", "configuration": { "cpu_limit_in_milli": "2000m", "ram_limit_in_mib": "2048Mi", "cpu_request_in_milli": "1000m", "ram_request_in_mib": "1024Mi", "max_nb_restart": 0, "max_duration_seconds": 0, "default_port": null, "source": { "image_name": "string", "tag": "string" }, "healthchecks": { "readiness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 }, "liveness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 } }, "entrypoint": "string", "arguments": [ "string" ] } } ``` --- # Deploy a job Source: https://docs.kapten.io/api/platform/jobs/deploy-job Starts a deployment of the job. `POST /project/{project_id}/environment/{environment_id}/job/{job_id}/deploy` **Responses** - `200` — Job deployment run created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "component_name": "string", "component_sid": "string", "action": "deploy", "trigger": "manual", "status": "QUEUED", "pipeline_context": { "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "pipeline_run_id": "54f73fac-6036-4081-9795-457321f22c71", "stage_run_id": "c6c7d692-4cdb-4e1f-9d55-db374c0d6d91", "pipeline_component_run_id": "63b3c0d9-c480-488a-860f-86e87cc881ec", "stage_component_id": "72d6951a-769e-47ac-a30e-c5b161d3f1fd", "required": true, "timeout_seconds": 0 }, "github_build": { "installation_id": "91166175-c6a9-4caf-88e9-3147ffc9c934", "repository_id": "string", "repository_full_name": "string", "branch": "string", "commit_sha": "string", "trigger": "manual", "image_reference": "string", "image_tag": "string", "index_digest": "string", "platforms": [ "linux/amd64" ] }, "workflow_id": "string", "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "message": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Get a job Source: https://docs.kapten.io/api/platform/jobs/get-job Returns a job. `GET /project/{project_id}/environment/{environment_id}/job/{job_id}` **Responses** - `200` — Job retrieved successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "name": "string", "description": "string", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "type": "cron", "timezone": "string", "cron": "string", "configuration": { "cpu_limit_in_milli": "2000m", "ram_limit_in_mib": "2048Mi", "cpu_request_in_milli": "1000m", "ram_request_in_mib": "1024Mi", "max_nb_restart": 0, "max_duration_seconds": 0, "default_port": null, "source": { "image_name": "string", "tag": "string" }, "healthchecks": { "readiness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 }, "liveness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 } }, "entrypoint": "string", "arguments": [ "string" ] } } ``` --- # Get a job run Source: https://docs.kapten.io/api/platform/jobs/get-job-run Returns one deployment run of the job. `GET /project/{project_id}/environment/{environment_id}/job/{job_id}/runs/{component_run_id}` **Responses** - `200` — Job run retrieved successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "component_name": "string", "component_sid": "string", "action": "deploy", "trigger": "manual", "status": "QUEUED", "pipeline_context": { "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "pipeline_run_id": "54f73fac-6036-4081-9795-457321f22c71", "stage_run_id": "c6c7d692-4cdb-4e1f-9d55-db374c0d6d91", "pipeline_component_run_id": "63b3c0d9-c480-488a-860f-86e87cc881ec", "stage_component_id": "72d6951a-769e-47ac-a30e-c5b161d3f1fd", "required": true, "timeout_seconds": 0 }, "github_build": { "installation_id": "91166175-c6a9-4caf-88e9-3147ffc9c934", "repository_id": "string", "repository_full_name": "string", "branch": "string", "commit_sha": "string", "trigger": "manual", "image_reference": "string", "image_tag": "string", "index_digest": "string", "platforms": [ "linux/amd64" ] }, "workflow_id": "string", "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "message": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # List job runs Source: https://docs.kapten.io/api/platform/jobs/list-job-runs Returns the job's deployment runs, a page at a time. `GET /project/{project_id}/environment/{environment_id}/job/{job_id}/runs` **Responses** - `200` — Job runs retrieved successfully - `default` — Error Response example, 200: ```json { "records": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "component_name": "string", "component_sid": "string", "action": "deploy", "trigger": "manual", "status": "QUEUED", "pipeline_context": { "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "pipeline_run_id": "54f73fac-6036-4081-9795-457321f22c71", "stage_run_id": "c6c7d692-4cdb-4e1f-9d55-db374c0d6d91", "pipeline_component_run_id": "63b3c0d9-c480-488a-860f-86e87cc881ec", "stage_component_id": "72d6951a-769e-47ac-a30e-c5b161d3f1fd", "required": true, "timeout_seconds": 0 }, "github_build": { "installation_id": "91166175-c6a9-4caf-88e9-3147ffc9c934", "repository_id": "string", "repository_full_name": "string", "branch": "string", "commit_sha": "string", "trigger": "manual", "image_reference": "string", "image_tag": "string", "index_digest": "string", "platforms": [ "linux/amd64" ] }, "workflow_id": "string", "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "message": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "pagination": { "total_records": 100, "current_page": 1, "total_pages": 10, "next_page": 2, "prev_page": null } } ``` --- # Query job run logs Source: https://docs.kapten.io/api/platform/jobs/query-job-run-logs Returns the deployment logs of one job run: what Kapten did while deploying it, and what its agent on the cluster did. For the job's own output, use the component logs. Without `from` or `to`, the window spans the run, from its start to its end. Logs follow the retention of the log backend, so the logs of an old run may be gone, and runs from before run logs existed return an empty list. `POST /project/{project_id}/environment/{environment_id}/job/{job_id}/runs/{component_run_id}/logs` **Request body** (`application/json`, required) - `view` (string) — Which run log projection to return. - `from` (string) — Inclusive lower bound for the run log time range. - `to` (string) — Inclusive upper bound for the run log time range. - `limit` (integer) — Maximum number of most recent raw backend records to query. - `levels` (string[]) — Optional log levels to include. - `source` (string[]) — Optional timeline event sources to include. - `text` (string) — Optional phrase to search in the log message. Request body example, Timeline only: ```json { "view": "timeline", "limit": 200, "source": [ "control_plane", "agent" ] } ``` Request body example, Raw run-scoped records only: ```json { "view": "raw", "levels": [ "info", "warn", "error" ], "text": "helm" } ``` Request body example, Timeline and raw records: ```json { "view": "both", "from": "2026-07-03T10:00:00Z", "to": "2026-07-03T10:30:00Z", "limit": 500 } ``` **Responses** - `200` — Job run logs retrieved successfully - `default` — Error Response example, 200: ```json { "timeline": [ { "time": "string", "level": "string", "source": "string", "step": "string", "phase": "string", "backend": "string", "backend_step": "string", "message": "string", "metadata": {}, "duration_ms": 0, "run_status": "string", "error_kind": "string", "event": "kapten.build.phase", "event_version": 0, "platform": "linux/amd64", "publication": "child_manifest" } ], "logs": [ { "msg": {}, "time": "string", "level": "string", "project_id": "string", "environment_id": "string", "component_id": "string", "component_type": "string", "component_run_id": "string", "component_kind": "string", "source": "control_plane", "step": "string", "phase": "string", "backend": "string", "backend_step": "string", "run_status": "string", "duration_ms": 0, "error_kind": "string", "metadata": {}, "event": "kapten.build.phase", "event_version": 0, "platform": "linux/amd64", "publication": "child_manifest" } ], "meta": { "component_run_id": "6037affb-fb72-4f94-b0fb-f75a6be340e1", "logs_backend": "victoria_logs", "default_time_range_applied": true, "details_available": true, "details_unavailable_reason": "string", "pipeline_context": { "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "pipeline_run_id": "54f73fac-6036-4081-9795-457321f22c71", "stage_run_id": "c6c7d692-4cdb-4e1f-9d55-db374c0d6d91", "pipeline_component_run_id": "63b3c0d9-c480-488a-860f-86e87cc881ec", "stage_component_id": "72d6951a-769e-47ac-a30e-c5b161d3f1fd", "required": true, "timeout_seconds": 0 } } } ``` --- # Update a job Source: https://docs.kapten.io/api/platform/jobs/update-job Updates a job. Fields left out keep their value. `PUT /project/{project_id}/environment/{environment_id}/job/{job_id}` **Request body** (`application/json`, required) - `name` (string) — Updated job name. - `description` (string) — Updated job description. - `type` (job_type) — Updated job scheduling strategy. - `timezone` (string) — Updated cron timezone. - `cron` (string) — Updated cron schedule. - `configuration` (object) Request body example: ```json { "name": "string", "description": "string", "type": "cron", "timezone": "string", "cron": "string", "configuration": { "cpu_limit_in_milli": "string", "ram_limit_in_mib": "string", "cpu_request_in_milli": "string", "ram_request_in_mib": "string", "max_nb_restart": 0, "max_duration_seconds": 0, "default_port": 1, "source": { "image_name": "string", "tag": "string" }, "healthchecks": { "readiness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 }, "liveness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 } }, "entrypoint": "string", "arguments": [ "string" ] } } ``` **Responses** - `200` — Job updated successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "cluster_id": "d3d1bfdf-67c4-41fa-b065-858242731616", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "name": "string", "description": "string", "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "type": "cron", "timezone": "string", "cron": "string", "configuration": { "cpu_limit_in_milli": "2000m", "ram_limit_in_mib": "2048Mi", "cpu_request_in_milli": "1000m", "ram_request_in_mib": "1024Mi", "max_nb_restart": 0, "max_duration_seconds": 0, "default_port": null, "source": { "image_name": "string", "tag": "string" }, "healthchecks": { "readiness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 }, "liveness_probe": { "type": { "tcp": { "port": 0, "host": null }, "http": { "path": "/", "scheme": "HTTP", "port": 0 }, "exec": { "command": [ "string" ] }, "grpc": { "service": null, "port": 0 } }, "initial_delay_seconds": 30, "period_seconds": 10, "timeout_seconds": 5, "success_threshold": 1, "failure_threshold": 9 } }, "entrypoint": "string", "arguments": [ "string" ] } } ``` --- # Create a pipeline stage Source: https://docs.kapten.io/api/platform/pipeline/create-pipeline-stage Adds a stage to a pipeline. Add its components with the stage component endpoints. `POST /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/stages` **Request body** (`application/json`, required) - `name` (string, required) - `description` (string) - `execution_order` (integer, required) - `on_failure` (pipeline_stage_failure_policy) — Describes how the pipeline should behave after a stage failure. Request body example: ```json { "name": "string", "description": "string", "execution_order": 1, "on_failure": "STOP_PIPELINE" } ``` **Responses** - `200` — Pipeline stage created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "name": "string", "description": "string", "execution_order": 0, "on_failure": "STOP_PIPELINE", "components": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "stage_id": "f38d2b9c-0a0a-4eea-91a8-e974413bb670", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "is_required": true, "timeout_seconds": 0, "created_at": "2019-08-24T14:15:22Z" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Add a component to a pipeline stage Source: https://docs.kapten.io/api/platform/pipeline/create-pipeline-stage-component Adds a component to the components a stage deploys. `POST /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/stages/{pipeline_stage_id}/components` **Request body** (`application/json`, required) - `component_id` (uuid, required) — A universally unique identifier (UUID) string - `component_kind` (component_kind, required) — Component kind for component-scoped variables - `is_required` (boolean) - `timeout_seconds` (integer) Request body example: ```json { "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "is_required": true, "timeout_seconds": 1 } ``` **Responses** - `200` — Pipeline stage component added successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "stage_id": "f38d2b9c-0a0a-4eea-91a8-e974413bb670", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "is_required": true, "timeout_seconds": 0, "created_at": "2019-08-24T14:15:22Z" } ``` --- # Delete a pipeline stage Source: https://docs.kapten.io/api/platform/pipeline/delete-pipeline-stage Deletes a stage and removes its components from the pipeline. `DELETE /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/stages/{pipeline_stage_id}` **Responses** - `204` — Pipeline stage deleted successfully - `default` — Error --- # Remove a component from a pipeline stage Source: https://docs.kapten.io/api/platform/pipeline/delete-pipeline-stage-component Removes a component from a stage. The component itself is not deleted. `DELETE /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/stages/{pipeline_stage_id}/components/{pipeline_stage_component_id}` **Responses** - `204` — Pipeline stage component removed successfully - `default` — Error --- # List pipeline stage components Source: https://docs.kapten.io/api/platform/pipeline/list-pipeline-stage-components Returns the components a stage deploys. `GET /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/stages/{pipeline_stage_id}/components` **Responses** - `200` — Pipeline stage components retrieved successfully - `default` — Error Response example, 200: ```json [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "stage_id": "f38d2b9c-0a0a-4eea-91a8-e974413bb670", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "is_required": true, "timeout_seconds": 0, "created_at": "2019-08-24T14:15:22Z" } ] ``` --- # List pipeline stages Source: https://docs.kapten.io/api/platform/pipeline/list-pipeline-stages Returns a pipeline's stages, in the order they run. `GET /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/stages` **Responses** - `200` — Pipeline stages retrieved successfully - `default` — Error Response example, 200: ```json [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "name": "string", "description": "string", "execution_order": 0, "on_failure": "STOP_PIPELINE", "components": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "stage_id": "f38d2b9c-0a0a-4eea-91a8-e974413bb670", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "is_required": true, "timeout_seconds": 0, "created_at": "2019-08-24T14:15:22Z" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ] ``` --- # Reorder pipeline stages Source: https://docs.kapten.io/api/platform/pipeline/reorder-pipeline-stages Sets the order in which a pipeline's stages run, in one change. The request lists every stage of the pipeline exactly once. `PUT /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/stages/reorder` **Request body** (`application/json`, required) - `stages` (reorder_pipeline_stage_item[], required) Request body example: ```json { "stages": [ { "stage_id": "f38d2b9c-0a0a-4eea-91a8-e974413bb670", "execution_order": 1 } ] } ``` **Responses** - `200` — Pipeline stages reordered successfully - `default` — Error Response example, 200: ```json [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "name": "string", "description": "string", "execution_order": 0, "on_failure": "STOP_PIPELINE", "components": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "stage_id": "f38d2b9c-0a0a-4eea-91a8-e974413bb670", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "is_required": true, "timeout_seconds": 0, "created_at": "2019-08-24T14:15:22Z" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ] ``` --- # Update a pipeline stage Source: https://docs.kapten.io/api/platform/pipeline/update-pipeline-stage Updates a stage's own fields. Change its components with the stage component endpoints. `PUT /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/stages/{pipeline_stage_id}` **Request body** (`application/json`, required) - `name` (string) - `description` (string) - `execution_order` (integer) - `on_failure` (pipeline_stage_failure_policy) — Describes how the pipeline should behave after a stage failure. Request body example: ```json { "name": "string", "description": "string", "execution_order": 1, "on_failure": "STOP_PIPELINE" } ``` **Responses** - `200` — Pipeline stage updated successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "name": "string", "description": "string", "execution_order": 0, "on_failure": "STOP_PIPELINE", "components": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "stage_id": "f38d2b9c-0a0a-4eea-91a8-e974413bb670", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "is_required": true, "timeout_seconds": 0, "created_at": "2019-08-24T14:15:22Z" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Update a pipeline stage component Source: https://docs.kapten.io/api/platform/pipeline/update-pipeline-stage-component Updates how a stage deploys one of its components. `PUT /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/stages/{pipeline_stage_id}/components/{pipeline_stage_component_id}` **Request body** (`application/json`, required) - `is_required` (boolean) - `timeout_seconds` (integer | null) Request body example: ```json { "is_required": true, "timeout_seconds": 1 } ``` **Responses** - `200` — Pipeline stage component updated successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "stage_id": "f38d2b9c-0a0a-4eea-91a8-e974413bb670", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "is_required": true, "timeout_seconds": 0, "created_at": "2019-08-24T14:15:22Z" } ``` --- # Create a pipeline Source: https://docs.kapten.io/api/platform/pipelines/create-pipeline Creates a pipeline in an environment. Add its stages with the stage endpoints. `POST /project/{project_id}/environment/{environment_id}/pipelines` **Request body** (`application/json`, required) - `name` (string, required) - `description` (string) - `is_active` (boolean) Request body example: ```json { "name": "string", "description": "string", "is_active": true } ``` **Responses** - `200` — Pipeline created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "name": "string", "description": "string", "is_active": true, "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "stages": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "name": "string", "description": "string", "execution_order": 0, "on_failure": "STOP_PIPELINE", "components": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "stage_id": "f38d2b9c-0a0a-4eea-91a8-e974413bb670", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "is_required": true, "timeout_seconds": 0, "created_at": "2019-08-24T14:15:22Z" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z" } ``` --- # Delete a pipeline Source: https://docs.kapten.io/api/platform/pipelines/delete-pipeline Deletes a pipeline. `DELETE /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}` **Responses** - `204` — Pipeline deleted successfully - `default` — Error --- # Get a pipeline Source: https://docs.kapten.io/api/platform/pipelines/get-pipeline Returns a pipeline. `GET /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}` **Responses** - `200` — Pipeline retrieved successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "name": "string", "description": "string", "is_active": true, "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "stages": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "name": "string", "description": "string", "execution_order": 0, "on_failure": "STOP_PIPELINE", "components": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "stage_id": "f38d2b9c-0a0a-4eea-91a8-e974413bb670", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "is_required": true, "timeout_seconds": 0, "created_at": "2019-08-24T14:15:22Z" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z" } ``` --- # Get a pipeline run Source: https://docs.kapten.io/api/platform/pipelines/get-pipeline-run Returns a pipeline run, with the state of each of its stages. `GET /project/{project_id}/environment/{environment_id}/pipeline-runs/{pipeline_run_id}` **Responses** - `200` — Pipeline run retrieved successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "status": "QUEUED", "triggered_by_user_id": "6b6a84b3-6fe8-41b4-838a-daa23e33b05f", "workflow_id": "string", "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "message": "string", "stage_runs": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "stage_id": "f38d2b9c-0a0a-4eea-91a8-e974413bb670", "name": "string", "description": "string", "execution_order": 0, "on_failure": "STOP_PIPELINE", "status": "QUEUED", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "message": "string", "component_runs": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "component_name": "string", "component_sid": "string", "action": "deploy", "trigger": "manual", "status": "QUEUED", "pipeline_context": { "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "pipeline_run_id": "54f73fac-6036-4081-9795-457321f22c71", "stage_run_id": "c6c7d692-4cdb-4e1f-9d55-db374c0d6d91", "pipeline_component_run_id": "63b3c0d9-c480-488a-860f-86e87cc881ec", "stage_component_id": "72d6951a-769e-47ac-a30e-c5b161d3f1fd", "required": true, "timeout_seconds": 0 }, "github_build": { "installation_id": "91166175-c6a9-4caf-88e9-3147ffc9c934", "repository_id": "string", "repository_full_name": "string", "branch": "string", "commit_sha": "string", "trigger": "manual", "image_reference": "string", "image_tag": "string", "index_digest": "string", "platforms": [ "linux/amd64" ] }, "workflow_id": "string", "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "message": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ] } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # List pipeline runs Source: https://docs.kapten.io/api/platform/pipelines/list-pipeline-runs Returns a pipeline's runs, a page at a time. `GET /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/runs` **Responses** - `200` — Pipeline runs retrieved successfully - `default` — Error Response example, 200: ```json { "records": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "status": "QUEUED", "triggered_by_user_id": "6b6a84b3-6fe8-41b4-838a-daa23e33b05f", "workflow_id": "string", "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "message": "string", "stage_runs": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "stage_id": "f38d2b9c-0a0a-4eea-91a8-e974413bb670", "name": "string", "description": "string", "execution_order": 0, "on_failure": "STOP_PIPELINE", "status": "QUEUED", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "message": "string", "component_runs": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "component_name": "string", "component_sid": "string", "action": "deploy", "trigger": "manual", "status": "QUEUED", "pipeline_context": { "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "pipeline_run_id": "54f73fac-6036-4081-9795-457321f22c71", "stage_run_id": "c6c7d692-4cdb-4e1f-9d55-db374c0d6d91", "pipeline_component_run_id": "63b3c0d9-c480-488a-860f-86e87cc881ec", "stage_component_id": "72d6951a-769e-47ac-a30e-c5b161d3f1fd", "required": true, "timeout_seconds": 0 }, "github_build": { "installation_id": "91166175-c6a9-4caf-88e9-3147ffc9c934", "repository_id": "string", "repository_full_name": "string", "branch": "string", "commit_sha": "string", "trigger": "manual", "image_reference": "string", "image_tag": "string", "index_digest": "string", "platforms": [ "linux/amd64" ] }, "workflow_id": "string", "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "message": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ] } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "pagination": { "total_records": 100, "current_page": 1, "total_pages": 10, "next_page": 2, "prev_page": null } } ``` --- # List pipelines Source: https://docs.kapten.io/api/platform/pipelines/list-pipelines Returns an environment's pipelines, a page at a time. `GET /project/{project_id}/environment/{environment_id}/pipelines` **Responses** - `200` — Pipelines retrieved successfully - `default` — Error Response example, 200: ```json { "records": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "name": "string", "description": "string", "is_active": true, "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "stages": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "name": "string", "description": "string", "execution_order": 0, "on_failure": "STOP_PIPELINE", "components": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "stage_id": "f38d2b9c-0a0a-4eea-91a8-e974413bb670", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "is_required": true, "timeout_seconds": 0, "created_at": "2019-08-24T14:15:22Z" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z" } ], "pagination": { "total_records": 100, "current_page": 1, "total_pages": 10, "next_page": 2, "prev_page": null } } ``` --- # Run a pipeline Source: https://docs.kapten.io/api/platform/pipelines/run-pipeline Starts a run of the pipeline, which deploys its stages in order. `POST /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}/run` **Responses** - `200` — Pipeline run started successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "status": "QUEUED", "triggered_by_user_id": "6b6a84b3-6fe8-41b4-838a-daa23e33b05f", "workflow_id": "string", "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "message": "string", "stage_runs": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "stage_id": "f38d2b9c-0a0a-4eea-91a8-e974413bb670", "name": "string", "description": "string", "execution_order": 0, "on_failure": "STOP_PIPELINE", "status": "QUEUED", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "message": "string", "component_runs": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "component_name": "string", "component_sid": "string", "action": "deploy", "trigger": "manual", "status": "QUEUED", "pipeline_context": { "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "pipeline_run_id": "54f73fac-6036-4081-9795-457321f22c71", "stage_run_id": "c6c7d692-4cdb-4e1f-9d55-db374c0d6d91", "pipeline_component_run_id": "63b3c0d9-c480-488a-860f-86e87cc881ec", "stage_component_id": "72d6951a-769e-47ac-a30e-c5b161d3f1fd", "required": true, "timeout_seconds": 0 }, "github_build": { "installation_id": "91166175-c6a9-4caf-88e9-3147ffc9c934", "repository_id": "string", "repository_full_name": "string", "branch": "string", "commit_sha": "string", "trigger": "manual", "image_reference": "string", "image_tag": "string", "index_digest": "string", "platforms": [ "linux/amd64" ] }, "workflow_id": "string", "workflow_run_id": "5e5ef678-2347-491b-a579-798b0d4ed952", "started_at": "2019-08-24T14:15:22Z", "finished_at": "2019-08-24T14:15:22Z", "message": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ] } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Update a pipeline Source: https://docs.kapten.io/api/platform/pipelines/update-pipeline Updates a pipeline's own fields. Change its stages with the stage endpoints. `PUT /project/{project_id}/environment/{environment_id}/pipelines/{pipeline_id}` **Request body** (`application/json`, required) - `name` (string) - `description` (string) - `is_active` (boolean) Request body example: ```json { "name": "string", "description": "string", "is_active": true } ``` **Responses** - `200` — Pipeline updated successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "name": "string", "description": "string", "is_active": true, "last_run_id": "08df5d92-87b1-40a2-b1e7-a5977dea4efc", "last_run_status": "QUEUED", "stages": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "pipeline_id": "ec036e81-7903-4e4d-bbfa-ac8516341cf0", "name": "string", "description": "string", "execution_order": 0, "on_failure": "STOP_PIPELINE", "components": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "stage_id": "f38d2b9c-0a0a-4eea-91a8-e974413bb670", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "component_kind": "Kjob", "is_required": true, "timeout_seconds": 0, "created_at": "2019-08-24T14:15:22Z" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z" } ``` --- # Create a project secret Source: https://docs.kapten.io/api/platform/project-secret/create-project-secret Sets a secret on the project, as a key-value pair or a file. `POST /project/{project_id}/secret` **Request body** (`application/json`, required) - `key` (string, required) — Secret key identifier. - `var_type` (variable_type, required) — Variable value type - `value` (string, required) — Secret value to store in Vault. - `file_path` (string) — Required when var\_type is file. Must be an absolute path. Request body example: ```json { "key": "string", "var_type": "key_value", "value": "string", "file_path": "string" } ``` **Responses** - `200` — Secret created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "visibility": "project", "var_type": "key_value", "key": "string", "is_secret": true, "managed": true, "value": "string", "file_path": "string", "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Delete a project secret Source: https://docs.kapten.io/api/platform/project-secret/delete-project-secret Deletes a secret from the project. `DELETE /project/{project_id}/secret/{variable_id}` **Responses** - `204` — Secret deleted successfully - `default` — Error --- # List project secrets Source: https://docs.kapten.io/api/platform/project-secret/list-project-secrets Returns the secrets set on the project, a page at a time. `GET /project/{project_id}/secret` **Responses** - `200` — List of secrets retrieved successfully - `default` — Error Response example, 200: ```json { "records": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "visibility": "project", "var_type": "key_value", "key": "string", "is_secret": true, "managed": true, "value": "string", "file_path": "string", "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "pagination": { "total_records": 100, "current_page": 1, "total_pages": 10, "next_page": 2, "prev_page": null } } ``` --- # Update a project secret Source: https://docs.kapten.io/api/platform/project-secret/update-project-secret Updates a secret's key, value or type. `PATCH /project/{project_id}/secret/{variable_id}` **Request body** (`application/json`, required) - `key` (string) — Updated secret key. - `value` (string) — Updated secret value. - `var_type` (variable_type) — Variable value type Request body example: ```json { "key": "string", "value": "string", "var_type": "key_value" } ``` **Responses** - `200` — Secret updated successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "visibility": "project", "var_type": "key_value", "key": "string", "is_secret": true, "managed": true, "value": "string", "file_path": "string", "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Create a project variable Source: https://docs.kapten.io/api/platform/project-variables/create-project-variable Sets a variable on the project, as a key-value pair or a file. `POST /project/{project_id}/variable` **Request body** (`application/json`, required) - `key` (string, required) — Variable key identifier. - `var_type` (variable_type, required) — Variable value type - `value` (string, required) — Variable value. - `file_path` (string) — Required when var\_type is file. Must be an absolute path. Request body example: ```json { "key": "string", "var_type": "key_value", "value": "string", "file_path": "string" } ``` **Responses** - `200` — Variable created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "visibility": "project", "var_type": "key_value", "key": "string", "is_secret": true, "managed": true, "value": "string", "file_path": "string", "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Delete a project variable Source: https://docs.kapten.io/api/platform/project-variables/delete-project-variable Deletes a variable from the project. `DELETE /project/{project_id}/variable/{variable_id}` **Responses** - `204` — Variable deleted successfully - `default` — Error --- # List project variables Source: https://docs.kapten.io/api/platform/project-variables/list-project-variables Returns the variables set on the project, a page at a time. `GET /project/{project_id}/variable` **Responses** - `200` — List of variables retrieved successfully - `default` — Error Response example, 200: ```json { "records": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "visibility": "project", "var_type": "key_value", "key": "string", "is_secret": true, "managed": true, "value": "string", "file_path": "string", "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ], "pagination": { "total_records": 100, "current_page": 1, "total_pages": 10, "next_page": 2, "prev_page": null } } ``` --- # Update a project variable Source: https://docs.kapten.io/api/platform/project-variables/update-project-variable Updates a variable's key, value or type. `PATCH /project/{project_id}/variable/{variable_id}` **Request body** (`application/json`, required) - `key` (string) — Updated variable key. - `value` (string) — Updated variable value. - `var_type` (variable_type) — Variable value type Request body example: ```json { "key": "string", "value": "string", "var_type": "key_value" } ``` **Responses** - `200` — Variable updated successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "visibility": "project", "var_type": "key_value", "key": "string", "is_secret": true, "managed": true, "value": "string", "file_path": "string", "component_kind": "Kjob", "component_id": "41afafe5-2a48-424a-baef-34c2ad44ef7b", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } ``` --- # Create a project Source: https://docs.kapten.io/api/platform/projects/create-project Creates a project and returns it. `POST /project` **Request body** (`application/json`, required) - `name` (string, required) — The name of the project. - `description` (string, required) — The description of the project. Request body example: ```json { "name": "string", "description": "string" } ``` **Responses** - `200` — project created successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "name": "string", "description": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z" } ``` --- # Delete a project Source: https://docs.kapten.io/api/platform/projects/delete-project Deletes a project. `DELETE /project/{project_id}` **Responses** - `204` — project deleted successfully - `default` — Error --- # Get a project Source: https://docs.kapten.io/api/platform/projects/get-project Returns a project. `GET /project/{project_id}` **Responses** - `200` — project retrieved successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "name": "string", "description": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z" } ``` --- # List projects Source: https://docs.kapten.io/api/platform/projects/list-projects Returns the organization's projects, a page at a time. `GET /project` **Responses** - `200` — List of projects retrieved successfully - `default` — Error Response example, 200: ```json { "records": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "name": "string", "description": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z" } ], "pagination": { "total_records": 100, "current_page": 1, "total_pages": 10, "next_page": 2, "prev_page": null } } ``` --- # Update a project Source: https://docs.kapten.io/api/platform/projects/update-project Updates a project's name and description. `PUT /project/{project_id}` **Request body** (`application/json`, required) - `name` (string) — The updated name of the project. - `description` (string) — The description of the project. Request body example: ```json { "name": "string", "description": "string" } ``` **Responses** - `200` — project updated successfully - `default` — Error Response example, 200: ```json { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6", "name": "string", "description": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "deleted_at": "2019-08-24T14:15:22Z" } ``` --- # Get environment usage Source: https://docs.kapten.io/api/platform/usage/get-environment-usage How long each environment of the token's organization was active in the period [since, until), from its creation to its deletion. Usage is counted in hourly UTC windows: both bounds are truncated to the hour, and a period spans at most 93 days. Only hours before `closed_through` are counted, and an hour closes about five minutes after it ends. Environments that were not active in the period are left out. Requires organization_update on the organization. The billable minutes are the ones the subscription is billed for. `GET /usage/environments` **Responses** - `200` — The usage of the period. - `default` — Error Response example, 200: ```json { "since": "2019-08-24T14:15:22Z", "until": "2019-08-24T14:15:22Z", "closed_through": "2019-08-24T14:15:22Z", "environments": [ { "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4", "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9", "active_seconds": 0.1, "billable_minutes": 0 } ], "days": [ { "day": "2019-08-24T14:15:22Z", "billable_minutes": 0 } ] } ``` --- # CLI overview Source: https://docs.kapten.io/cli `kapten` manages your organization from a terminal: everything you do in the [console](https://app.kapten.io) on projects, environments, applications, jobs, databases, pipelines and clusters, the CLI does too. It also runs in CI jobs, as an [OAuth application](/cli/authentication#run-in-ci), and serves Kapten to [coding agents](/cli/mcp) over MCP. ## Install **mise** [mise](https://mise.jdx.dev) checks the release's signed [packslip](https://packslip.dev) manifest before it installs anything, and installs the shell completions of the version in use: ```bash mise use -g packslip:github.com/kapten-io/cli ``` `mise up` updates it. **npm** With Node.js: ```bash npm install -g @kapten/cli ``` npm installs only the package of your platform, and records each release's provenance. Without installing it, for a CI job or an MCP client: `npx -y @kapten/cli@latest `. **Homebrew** On macOS and Linux: ```bash brew install --cask kapten-io/tap/kapten ``` `brew upgrade --cask kapten` updates it. **Archive** Download the archive for your system from the [releases page](https://github.com/kapten-io/cli/releases): `kapten___.tar.gz` for macOS (`darwin`) and Linux, `.zip` for Windows, each for `amd64` and `arm64`. Check it against `checksums.txt`, and check where it was built with the [GitHub CLI](https://cli.github.com): ```bash gh attestation verify kapten___.tar.gz --repo kapten-io/cli ``` Extract it and put both executables, `kapten` and `restish-mcp`, in the same directory on your `PATH`. `kapten mcp serve` runs `restish-mcp` from the directory `kapten` is in. Check the installation: ```bash kapten --version ``` Every release is built and signed by the [Release workflow](https://github.com/kapten-io/cli/actions/workflows/release.yml) of the public [kapten-io/cli](https://github.com/kapten-io/cli) repository. Its [releases page](https://github.com/kapten-io/cli/releases) lists the changes of each version. ## First commands 1. **Log in** ```bash kapten login ``` The CLI shows a code and opens a page in your browser. Check that the page shows the same code, approve it, and pick an organization. See [Authentication](/cli/authentication). 2. **List your projects** ```bash kapten projects list ``` 3. **List the environments of a project** ```bash kapten environments list ``` Commands take the IDs of the resources they act on as arguments, in order from the project down. `kapten --help` lists the command groups, and `kapten --help` the commands of a group. The [command reference](/cli/reference) documents every command. ## Shell completion `kapten completion ` prints a completion script for `bash`, `zsh`, `fish` or `powershell`. For zsh: ```bash kapten completion zsh > "${fpath[1]}/_kapten" ``` `kapten completion --help` shows how to load it in each shell. --- # Authentication Source: https://docs.kapten.io/cli/authentication The CLI runs commands either as you, after `kapten login`, or as an [OAuth application](/api#authentication), from environment variables. Logins are saved as **contexts**, one per organization, so you can switch between them. ## Log in ```bash kapten login ``` The CLI shows a code such as `WDJB-MJHT` and a page to open. It opens the page in your browser when it can. Otherwise, or with `--no-browser`, open it yourself, on this machine or any other: logging in works over SSH. On the page, check that the code matches, approve it and pick an organization. The code expires after ten minutes. The login is saved as a context named after the organization. `--name` gives it another name: ```bash kapten login --name work ``` `kapten whoami` shows who commands run as, and in which organization. It says to log in again when the session has ended. `kapten logout` removes the active context's credentials, `kapten logout ` another one's, and `kapten logout --all` every context's. ## Switch between organizations Each login is a context, and one context is active. Commands run in the active context, unless `--context` names another one: ```bash kapten auth list # the contexts, the active one marked with * kapten auth use work # make work the active context kapten --context personal projects list ``` ## Where credentials are saved The CLI saves each context's tokens in the operating system's keychain: Keychain on macOS, the Secret Service on Linux, the Credential Manager on Windows. When no keychain is available, it saves them in `credentials.json`, a file only your user can read, in the Kapten config directory (`~/.config/kapten` on Linux), and warns you. `kapten auth list` shows where each context's credentials are. On a machine with no keychain, such as a container, set `KAPTEN_CREDENTIALS_STORE=file` to use the file directly. Access tokens are renewed while you use the CLI. Your login lasts as long as the browser session that approved it: when you sign out of the console, log in again. ## Run in CI In a CI job, the CLI authenticates as an OAuth application of your organization, with no login. [Create an OAuth application](/api#authentication) with only the Roles the job needs, then set its client ID and its secret: ```bash export KAPTEN_CLIENT_ID=cli_… export KAPTEN_CLIENT_SECRET=kapten_sk_… kapten projects list ``` For an application you registered a public key for, set the private key instead of the secret, as a PEM or JWK, in `KAPTEN_CLIENT_PRIVATE_KEY` or in a file named by `KAPTEN_CLIENT_PRIVATE_KEY_FILE`: ```bash export KAPTEN_CLIENT_ID=cli_… export KAPTEN_CLIENT_PRIVATE_KEY_FILE=deploy-key.pem ``` The CLI requests a token for each run and keeps it in memory: nothing is saved. Store the secret or the key in your CI's secret store. When both are possible, `--context` wins over the environment variables, and the environment variables win over the active context. `kapten login` refuses to run while `KAPTEN_CLIENT_ID` is set. ## Environment variables | Variable | Use | | --- | --- | | `KAPTEN_CLIENT_ID` | Authenticate as this OAuth application, with no login | | `KAPTEN_CLIENT_SECRET` | The OAuth application's client secret | | `KAPTEN_CLIENT_PRIVATE_KEY` | The OAuth application's private key, as a PEM or JWK, instead of a secret | | `KAPTEN_CLIENT_PRIVATE_KEY_FILE` | A file holding that private key | | `KAPTEN_CREDENTIALS_STORE` | `file` saves logins in the config directory instead of the keychain | | `KAPTEN_CONFIG_DIR` | The directory of the CLI's contexts and file credentials | --- # Coding agents Source: https://docs.kapten.io/cli/mcp A coding agent works with Kapten through three pieces: - the **`kapten` skill**, which teaches it the resource model and how to run the CLI: discover commands from help, confirm the organization before changing anything, verify the result; - the **`kapten` MCP server**, `kapten mcp serve`, which gives it the CLI's operations as tools; - the **`kapten-docs` MCP server**, `https://docs.kapten.io/mcp`, which searches and reads these docs. ## Set up an agent with the CLI `kapten skills install` writes the skill of your CLI version where your agents read skills, and with `--mcp` adds both MCP servers to their configuration: ```bash kapten --context work skills install --mcp # this project, every agent on this machine kapten skills install --global --mcp --agent codex # for your user, one agent ``` It knows Claude Code, Codex, Cursor, OpenCode and GitHub Copilot, leaves the other entries of their configuration untouched, and updates its own when run again. See [`kapten skills`](/cli/reference/skills). ## Install the plugin The [kapten-io/skills](https://github.com/kapten-io/skills) repository is a plugin with both skills (`kapten` and `kapten-docs`) and both MCP servers, for agents that install plugins. Each CLI release publishes it, tagged with the release's version. Its `kapten` server runs the CLI with `npx`, so it needs Node.js and a login. ```bash # Claude Code /plugin marketplace add kapten-io/skills /plugin install kapten@kapten ``` Codex, Cursor and other clients of the [Agent Plugins](https://agent-plugins.org) standard install it from the same repository. For the skills alone, in any agent: `npx skills add kapten-io/skills`. These docs also list the skills at [`/.well-known/agent-skills/index.json`](https://docs.kapten.io/.well-known/agent-skills/index.json). ## Configure an MCP client by hand `kapten mcp serve` runs an MCP server over stdio: a coding agent that supports MCP can then list, create, update and delete Kapten resources with the same operations as the CLI's commands. The server runs on your machine, with the CLI's login. It has no network listener. 1. **Log in** ```bash kapten login --name work ``` The server uses a saved context, or an OAuth application from the [environment variables](/cli/authentication#run-in-ci). 2. **Add the server to your client** Most MCP clients take a configuration like this one. It runs the CLI with `npx`, which needs Node.js: ```json { "mcpServers": { "kapten": { "command": "npx", "args": ["-y", "@kapten/cli@latest", "--context", "work", "mcp", "serve"] } } } ``` ## One organization per server The server picks its context when it starts and keeps it: `kapten auth use` does not change a running server. Name the context with `--context`, as above, so the server does not depend on the active one. To work with several organizations, add one server per context, each with its own name. ## Limit what the agent can do The server exposes every operation the CLI has, including deletes. Delete tools are marked destructive, so clients that ask before running such tools ask for them. The agent can do what your login can do: for a narrower access, run the server as an [OAuth application](/cli/authentication#run-in-ci) with only the Roles it needs. `--operations` limits the tools to a list of operation IDs, the `operationId` of each operation in the [Platform API](/api/platform) reference: ```json "args": ["--context", "work", "mcp", "serve", "--operations", "listProjects,listEnvironments,queryApplicationRunLogs"] ``` `--request-timeout` bounds each API request, in seconds (30 by default), and `--max-result-bytes` the size of a tool's result (1 MiB by default). See [`kapten mcp serve`](/cli/reference/mcp). --- # Output and errors Source: https://docs.kapten.io/cli/output ## Tables and JSON Commands that list resources print a table of their main fields. Other commands print the resource as JSON. `-o` chooses the format: ```bash kapten projects list # a table kapten projects list -o json # the API's response, pagination included kapten projects get -o yaml ``` `--rsh-columns` chooses a table's columns, and `--rsh-sort-by` the column its rows are sorted by: ```bash kapten environments list --rsh-columns name,type,id --rsh-sort-by name ``` ## Filter results `-f` keeps only part of the response, with a [jq](https://jqlang.org) expression. The response is under `.body`: ```bash kapten projects list -f '.body.records[].id' kapten projects get -f '.body.name' ``` Lists return one page of results at a time: `--page-limit` sets the page size and `--page-number` the page. ## Errors When the API refuses a request, the CLI prints the error on one line to stderr and exits with status `1`. stdout only ever holds results, so a script can pipe it safely. With `-o json`, the API's error document is printed to stdout too. When your session has ended, the error says to run `kapten login` again. `-v` prints the HTTP requests and responses, without tokens, to help find what went wrong: ```bash kapten projects list -v ``` --- # Command reference Source: https://docs.kapten.io/cli/reference Every command the CLI has, generated from the CLI itself. `kapten --help` prints the same information in a terminal. | Command | What it does | | --- | --- | | [`kapten auth`](/cli/reference/auth) | Log in, check who commands run as, and switch between saved logins | | [`kapten applications`](/cli/reference/applications) | Deploy and run long-running applications | | [`kapten clusters`](/cli/reference/clusters) | Connect and manage Kubernetes clusters | | [`kapten components`](/cli/reference/components) | List the components of an environment | | [`kapten databases`](/cli/reference/databases) | Create and manage databases | | [`kapten environments`](/cli/reference/environments) | Create and manage the environments of a project | | [`kapten jobs`](/cli/reference/jobs) | Run and schedule jobs | | [`kapten pipelines`](/cli/reference/pipelines) | Build and run deployment pipelines | | [`kapten projects`](/cli/reference/projects) | Create and manage projects | | [`kapten usage`](/cli/reference/usage) | Show environment usage for billing | | [`kapten mcp`](/cli/reference/mcp) | Serve Kapten operations as MCP tools to a coding agent | ## Global flags These flags work with every command. | Flag | Description | | --- | --- | | `--context string` | Saved login to use for this command (see kapten auth list) | | `-h, --help` | Show help | | `-v, --rsh-verbose` | Show request and response headers (-vv adds TLS details) | | `--version` | Show the version | --- # kapten applications Source: https://docs.kapten.io/cli/reference/applications Every command takes the [global flags](/cli/reference#global-flags). ## kapten applications create Creates a long-running application in an environment, built from a GitHub repository or deployed from a container image. ```bash kapten applications create [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { configuration*: { arguments: [ (string) ] cpu_limit_in_milli: (string) Maximum CPU allocated to the application. Unit is millicores (m). cpu_request_in_milli: (string) Requested CPU. Unit is millicores (m). entrypoint: (string) Application entrypoint. gpu_limit: (integer min:0) Optional GPU count. healthchecks*: { liveness_probe: { failure_threshold: (integer default:9) initial_delay_seconds: (integer default:30) period_seconds: (integer default:10) success_threshold: (integer default:1) timeout_seconds: (integer default:5) type: { exec: <...> grpc: <...> http: <...> tcp: <...> } } readiness_probe: { failure_threshold: (integer default:9) initial_delay_seconds: (integer default:30) period_seconds: (integer default:10) success_threshold: (integer default:1) timeout_seconds: (integer default:5) type: { exec: <...> grpc: <...> http: <...> tcp: <...> } } } max_running_instances: (integer min:1) Maximum number of running instances. min_running_instances: (integer min:1) Minimum number of running instances. ports: [ { external_port: (integer min:1 max:65535) Optional exposed port, persisted for future exposure features. id: (string format:uuid) A universally unique identifier (UUID) string internal_port*: (integer min:1 max:65535) Listening port inside the application. is_default*: (boolean) Whether this is the default port for future domain routing. name*: (string) Human-readable port name. protocol*: (string enum:HTTP,GRPC,TCP,UDP) Application port protocol. } ] ram_limit_in_mib: (string) Maximum memory allocated to the application. ram_request_in_mib: (string) Requested memory. source*: oneOf{ { image_name*: (string pattern:\S minLen:1) image name tag*: (string pattern:\S minLen:1) tag of the image container type*: (string enum:container) Container source discriminator. } { branch*: (string minLen:1) build_policy*: { context: <...> cpu_limit_in_milli*: <...> cpu_request_in_milli*: <...> ram_limit_in_mib*: <...> ram_request_in_mib*: <...> timeout_seconds: <...> } installation_id*: (string format:uuid) A universally unique identifier (UUID) string repository_id*: (string pattern:^[1-9][0-9]*$) trigger_policy: { automatic: <...> path_mode: <...> paths: <...> } type*: (string enum:github) } } storages: [ { id: (string format:uuid) A universally unique identifier (UUID) string mount_path*: (string) Absolute path mounted into the application. name*: (string) Human-readable storage name. size_in_gib*: (integer min:1) Persistent volume size in GiB. storage_type*: (string) Kubernetes storage class name. } ] } description: (string) name*: (string pattern:\S minLen:1) Name of the application component. } ``` Example: ```bash kapten applications create [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `application-id` | The unique identifier for the application | Example: ```bash kapten applications deploy ``` ## kapten applications get Returns an application. ```bash kapten applications get [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `application-id` | The unique identifier for the application | Example: ```bash kapten applications get ``` ## kapten applications get-run Returns one deployment run of the application. ```bash kapten applications get-run [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `application-id` | The unique identifier for the application | | `component-run-id` | The unique identifier for the component run | Example: ```bash kapten applications get-run ``` ## kapten applications list-runs Returns the application's deployment runs, a page at a time. ```bash kapten applications list-runs [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `application-id` | The unique identifier for the application | | Flag | Description | | --- | --- | | `--action string` | Filter component runs by action. | | `--created-after string` | Filter component runs created at or after this timestamp. | | `--created-before string` | Filter component runs created at or before this timestamp. | | `--page-limit int` | Maximum number of records to return (default: 10) | | `--page-number int` | Page number (default: 1) | | `--status string` | Filter component runs by deployment status. | | `--trigger string` | Filter component runs by trigger source. | Example: ```bash kapten applications list-runs ``` ## kapten applications query-run-logs Returns the deployment logs of one application run: what Kapten and the image build did while deploying it, and what its agent on the cluster did. For the application's own output, use the component logs. Without `from` or `to`, the window spans the run, from its start to its end. Logs follow the retention of the log backend, so the logs of an old run may be gone, and runs from before run logs existed return an empty list. ```bash kapten applications query-run-logs [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `application-id` | The unique identifier for the application | | `component-run-id` | The unique identifier for the component run | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { from: (string format:date-time) Inclusive lower bound for the run log time range. levels: [ (string) ] limit: (integer format:int32 default:200 min:1 max:1000) Maximum number of most recent raw backend records to query. source: [ (string enum:control_plane,agent,builder) ] text: (string) Optional phrase to search in the log message. to: (string format:date-time) Inclusive upper bound for the run log time range. view: (string default:both enum:timeline,raw,both) Which run log projection to return. } ``` Example: ```bash kapten applications query-run-logs 'limit: 200, source: [control_plane, agent, builder], view: timeline' ``` ## kapten applications update Updates an application. Fields left out keep their value. ```bash kapten applications update [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `application-id` | The unique identifier for the application | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { configuration: { arguments: [ (string) ] cpu_limit_in_milli: (string) Updated CPU limit. cpu_request_in_milli: (string) Updated CPU request. entrypoint: (string) Updated application entrypoint. gpu_limit: (integer min:0) Updated GPU count. healthchecks: { liveness_probe: { failure_threshold: (integer default:9) initial_delay_seconds: (integer default:30) period_seconds: (integer default:10) success_threshold: (integer default:1) timeout_seconds: (integer default:5) type: { exec: <...> grpc: <...> http: <...> tcp: <...> } } readiness_probe: { failure_threshold: (integer default:9) initial_delay_seconds: (integer default:30) period_seconds: (integer default:10) success_threshold: (integer default:1) timeout_seconds: (integer default:5) type: { exec: <...> grpc: <...> http: <...> tcp: <...> } } } max_running_instances: (integer min:1) Updated maximum number of running instances. min_running_instances: (integer min:1) Updated minimum number of running instances. ports: [ { external_port: (integer min:1 max:65535) Optional exposed port, persisted for future exposure features. id: (string format:uuid) A universally unique identifier (UUID) string internal_port*: (integer min:1 max:65535) Listening port inside the application. is_default*: (boolean) Whether this is the default port for future domain routing. name*: (string) Human-readable port name. protocol*: (string enum:HTTP,GRPC,TCP,UDP) Application port protocol. } ] ram_limit_in_mib: (string) Updated RAM limit. ram_request_in_mib: (string) Updated RAM request. source: oneOf{ { image_name*: (string pattern:\S minLen:1) image name tag*: (string pattern:\S minLen:1) tag of the image container type*: (string enum:container) Container source discriminator. } { branch*: (string minLen:1) build_policy*: { context: <...> cpu_limit_in_milli*: <...> cpu_request_in_milli*: <...> ram_limit_in_mib*: <...> ram_request_in_mib*: <...> timeout_seconds: <...> } installation_id*: (string format:uuid) A universally unique identifier (UUID) string repository_id*: (string pattern:^[1-9][0-9]*$) trigger_policy: { automatic: <...> path_mode: <...> paths: <...> } type*: (string enum:github) } } storages: [ { id: (string format:uuid) A universally unique identifier (UUID) string mount_path*: (string) Absolute path mounted into the application. name*: (string) Human-readable storage name. size_in_gib*: (integer min:1) Persistent volume size in GiB. storage_type*: (string) Kubernetes storage class name. } ] } description: (string) Updated application description. name: (string pattern:\S minLen:1) Updated application name. } ``` Example: ```bash kapten applications update ``` ## kapten auth whoami Show who commands run as. ```bash kapten auth whoami [flags] ``` | Flag | Description | | --- | --- | | `--json` | Output JSON | --- # kapten clusters Source: https://docs.kapten.io/cli/reference/clusters Every command takes the [global flags](/cli/reference#global-flags). ## kapten clusters create Connects a Kubernetes cluster from its kubeconfig. Kapten then installs its agent on the cluster. ```bash kapten clusters create [flags] ``` | Argument | Description | | --- | --- | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { cloud_provider*: (string enum:custom,aws,gcp) The cloud provider for the cluster. kube_config*: (string format:byte) The base64-encoded Kubernetes configuration for the cluster. name*: (string pattern:\S minLen:1) The name of the cluster. } ``` Example: ```bash kapten clusters create 'cloud_provider: aws, kube_config: @file, name: my-production-cluster' ``` ## kapten clusters delete Removes a cluster from the organization. ```bash kapten clusters delete [flags] ``` | Argument | Description | | --- | --- | | `cluster-id` | The unique identifier of the cluster | Example: ```bash kapten clusters delete ``` ## kapten clusters get Returns a cluster. ```bash kapten clusters get [flags] ``` | Argument | Description | | --- | --- | | `cluster-id` | The unique identifier of the cluster | Example: ```bash kapten clusters get ``` ## kapten clusters list Returns the organization's clusters, a page at a time. ```bash kapten clusters list [flags] ``` | Flag | Description | | --- | --- | | `--filter-with-deleted` | Include deleted instances (default: false) | | `--page-limit int` | Maximum number of records to return (default: 10) | | `--page-number int` | Page number (default: 1) | Example: ```bash kapten clusters list ``` ## kapten clusters update Updates a cluster's settings. ```bash kapten clusters update [flags] ``` | Argument | Description | | --- | --- | | `cluster-id` | The unique identifier of the cluster | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { kube_config: (string format:byte) The base64-encoded Kubernetes configuration for the cluster. name: (string pattern:\S minLen:1) The name of the cluster. } ``` Example: ```bash kapten clusters update 'kube_config: @file, name: my-production-cluster' ``` --- # kapten components Source: https://docs.kapten.io/cli/reference/components Every command takes the [global flags](/cli/reference#global-flags). ## kapten components list Returns the applications, jobs and databases of an environment, a page at a time. ```bash kapten components list [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | Flag | Description | | --- | --- | | `--component-kind string` | Optional component kind filter | | `--filter-with-deleted` | Include deleted instances (default: false) | | `--page-limit int` | Maximum number of records to return (default: 10) | | `--page-number int` | Page number (default: 1) | Example: ```bash kapten components list ``` --- # kapten databases Source: https://docs.kapten.io/cli/reference/databases Every command takes the [global flags](/cli/reference#global-flags). ## kapten databases create-mongodb Creates a MongoDB database in an environment. ```bash kapten databases create-mongodb [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text oneOf{ allOf{ allOf{ { accessibility*: allOf{ <...> } description: (string) Optional database description. name*: (string pattern:\S minLen:1) Name of the database. version*: (string) Database engine version. } { configuration*: { activate_backups: <...> activate_high_availability: <...> database_name: <...> encrypt_disk: <...> resources*: <...> } provisioning*: (string enum:IN_CLUSTER) Database provisioning strategy. } } } allOf{ allOf{ { accessibility*: allOf{ <...> } description: (string) Optional database description. name*: (string pattern:\S minLen:1) Name of the database. version*: (string) Database engine version. } { configuration*: { activate_backups: <...> activate_high_availability: <...> database_name: <...> encrypt_disk: <...> resources*: <...> } provisioning*: (string enum:MANAGED) Database provisioning strategy. } } } } ``` Example: ```bash kapten databases create-mongodb [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text oneOf{ allOf{ allOf{ { accessibility*: allOf{ <...> } description: (string) Optional database description. name*: (string pattern:\S minLen:1) Name of the database. version*: (string) Database engine version. } { configuration*: { activate_backups: <...> activate_high_availability: <...> database_name: <...> encrypt_disk: <...> resources*: <...> } provisioning*: (string enum:IN_CLUSTER) Database provisioning strategy. } } } allOf{ allOf{ { accessibility*: allOf{ <...> } description: (string) Optional database description. name*: (string pattern:\S minLen:1) Name of the database. version*: (string) Database engine version. } { configuration*: { activate_backups: <...> activate_high_availability: <...> database_name: <...> encrypt_disk: <...> resources*: <...> } provisioning*: (string enum:MANAGED) Database provisioning strategy. } } } } ``` Example: ```bash kapten databases create-mysql [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text oneOf{ allOf{ allOf{ { accessibility*: allOf{ <...> } description: (string) Optional database description. name*: (string pattern:\S minLen:1) Name of the database. version*: (string) Database engine version. } { configuration*: { activate_backups: <...> activate_high_availability: <...> database_name: <...> encrypt_disk: <...> resources*: <...> } provisioning*: (string enum:IN_CLUSTER) Database provisioning strategy. } } } allOf{ allOf{ { accessibility*: allOf{ <...> } description: (string) Optional database description. name*: (string pattern:\S minLen:1) Name of the database. version*: (string) Database engine version. } { configuration*: { activate_backups: <...> activate_high_availability: <...> database_name: <...> encrypt_disk: <...> resources*: <...> } provisioning*: (string enum:MANAGED) Database provisioning strategy. } } } } ``` Example: ```bash kapten databases create-postgresql [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text oneOf{ allOf{ allOf{ { accessibility*: allOf{ <...> } description: (string) Optional database description. name*: (string pattern:\S minLen:1) Name of the database. version*: (string) Database engine version. } { configuration*: { activate_backups: <...> activate_high_availability: <...> database_name: <...> encrypt_disk: <...> resources*: <...> } provisioning*: (string enum:IN_CLUSTER) Database provisioning strategy. } } } allOf{ allOf{ { accessibility*: allOf{ <...> } description: (string) Optional database description. name*: (string pattern:\S minLen:1) Name of the database. version*: (string) Database engine version. } { configuration*: { activate_backups: <...> activate_high_availability: <...> database_name: <...> encrypt_disk: <...> resources*: <...> } provisioning*: (string enum:MANAGED) Database provisioning strategy. } } } } ``` Example: ```bash kapten databases create-redis [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `database-id` | Unique identifier of the database. | Example: ```bash kapten databases delete ``` ## kapten databases deploy Starts a deployment of the database. ```bash kapten databases deploy [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `database-id` | Unique identifier of the database. | Example: ```bash kapten databases deploy ``` ## kapten databases get-mongodb Returns a MongoDB database. ```bash kapten databases get-mongodb [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `database-id` | Unique identifier of the database. | Example: ```bash kapten databases get-mongodb ``` ## kapten databases get-mysql Returns a MySQL database. ```bash kapten databases get-mysql [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `database-id` | Unique identifier of the database. | Example: ```bash kapten databases get-mysql ``` ## kapten databases get-postgresql Returns a PostgreSQL database. ```bash kapten databases get-postgresql [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `database-id` | Unique identifier of the database. | Example: ```bash kapten databases get-postgresql ``` ## kapten databases get-redis Returns a Redis database. ```bash kapten databases get-redis [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `database-id` | Unique identifier of the database. | Example: ```bash kapten databases get-redis ``` ## kapten databases get-run Returns one deployment run of the database. ```bash kapten databases get-run [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `database-id` | Unique identifier of the database. | | `component-run-id` | The unique identifier for the component run | Example: ```bash kapten databases get-run ``` ## kapten databases list-runs Returns the database's deployment runs, a page at a time. ```bash kapten databases list-runs [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `database-id` | Unique identifier of the database. | | Flag | Description | | --- | --- | | `--action string` | Filter component runs by action. | | `--created-after string` | Filter component runs created at or after this timestamp. | | `--created-before string` | Filter component runs created at or before this timestamp. | | `--page-limit int` | Maximum number of records to return (default: 10) | | `--page-number int` | Page number (default: 1) | | `--status string` | Filter component runs by deployment status. | | `--trigger string` | Filter component runs by trigger source. | Example: ```bash kapten databases list-runs ``` ## kapten databases query-run-logs Returns the deployment logs of one database run: what Kapten did while deploying it, and what its agent on the cluster did. For the database's own output, use the component logs. Without `from` or `to`, the window spans the run, from its start to its end. Logs follow the retention of the log backend, so the logs of an old run may be gone, and runs from before run logs existed return an empty list. ```bash kapten databases query-run-logs [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `database-id` | Unique identifier of the database. | | `component-run-id` | The unique identifier for the component run | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { from: (string format:date-time) Inclusive lower bound for the run log time range. levels: [ (string) ] limit: (integer format:int32 default:200 min:1 max:1000) Maximum number of most recent raw backend records to query. source: [ (string enum:control_plane,agent,builder) ] text: (string) Optional phrase to search in the log message. to: (string format:date-time) Inclusive upper bound for the run log time range. view: (string default:both enum:timeline,raw,both) Which run log projection to return. } ``` Example: ```bash kapten databases query-run-logs 'limit: 200, source: [control_plane, agent], view: timeline' ``` ## kapten databases update-mongodb Updates a MongoDB database's settings. Its provisioning and `database_name` cannot change. ```bash kapten databases update-mongodb [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `database-id` | Unique identifier of the database. | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { accessibility: allOf{ (string enum:PRIVATE,PUBLIC) Database network accessibility. } configuration: { activate_backups: (boolean) activate_high_availability: (boolean) encrypt_disk: (boolean) resources: { cpu_limit_in_milli: (integer format:int64 min:0) cpu_request_in_milli: (integer format:int64 min:0) database_disk_iops: (integer format:int64 min:0) database_disk_type: (string) database_instance_tier: (string) disk_size_in_gib: (integer format:int64 min:0) ram_limit_in_mib: (integer format:int64 min:0) ram_request_in_mib: (integer format:int64 min:0) } } description: (string) Updated database description. name: (string pattern:\S minLen:1) Updated database name. version: (string) Updated database engine version. } ``` Example: ```bash kapten databases update-mongodb [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `database-id` | Unique identifier of the database. | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { accessibility: allOf{ (string enum:PRIVATE,PUBLIC) Database network accessibility. } configuration: { activate_backups: (boolean) activate_high_availability: (boolean) encrypt_disk: (boolean) resources: { cpu_limit_in_milli: (integer format:int64 min:0) cpu_request_in_milli: (integer format:int64 min:0) database_disk_iops: (integer format:int64 min:0) database_disk_type: (string) database_instance_tier: (string) disk_size_in_gib: (integer format:int64 min:0) ram_limit_in_mib: (integer format:int64 min:0) ram_request_in_mib: (integer format:int64 min:0) } } description: (string) Updated database description. name: (string pattern:\S minLen:1) Updated database name. version: (string) Updated database engine version. } ``` Example: ```bash kapten databases update-mysql [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `database-id` | Unique identifier of the database. | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { accessibility: allOf{ (string enum:PRIVATE,PUBLIC) Database network accessibility. } configuration: { activate_backups: (boolean) activate_high_availability: (boolean) encrypt_disk: (boolean) resources: { cpu_limit_in_milli: (integer format:int64 min:0) cpu_request_in_milli: (integer format:int64 min:0) database_disk_iops: (integer format:int64 min:0) database_disk_type: (string) database_instance_tier: (string) disk_size_in_gib: (integer format:int64 min:0) ram_limit_in_mib: (integer format:int64 min:0) ram_request_in_mib: (integer format:int64 min:0) } } description: (string) Updated database description. name: (string pattern:\S minLen:1) Updated database name. version: (string) Updated database engine version. } ``` Example: ```bash kapten databases update-postgresql [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `database-id` | Unique identifier of the database. | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { accessibility: allOf{ (string enum:PRIVATE,PUBLIC) Database network accessibility. } configuration: { activate_backups: (boolean) activate_high_availability: (boolean) encrypt_disk: (boolean) resources: { cpu_limit_in_milli: (integer format:int64 min:0) cpu_request_in_milli: (integer format:int64 min:0) database_disk_iops: (integer format:int64 min:0) database_disk_type: (string) database_instance_tier: (string) disk_size_in_gib: (integer format:int64 min:0) ram_limit_in_mib: (integer format:int64 min:0) ram_request_in_mib: (integer format:int64 min:0) } } description: (string) Updated database description. name: (string pattern:\S minLen:1) Updated database name. version: (string) Updated database engine version. } ``` Example: ```bash kapten databases update-redis [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { cluster_id*: (string format:uuid) A universally unique identifier (UUID) string name*: (string pattern:\S minLen:1) The name of the environment. type*: (string enum:development,staging,production) The type of the environment. } ``` Example: ```bash kapten environments create 'cluster_id: "3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a", name: string, type: development' ``` ## kapten environments delete Deletes an environment, with its variables and secrets. This cannot be undone. ```bash kapten environments delete [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | Example: ```bash kapten environments delete ``` ## kapten environments get Returns an environment. ```bash kapten environments get [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | Example: ```bash kapten environments get ``` ## kapten environments list Returns a project's environments, a page at a time. ```bash kapten environments list [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | Flag | Description | | --- | --- | | `--filter-with-deleted` | Include deleted instances (default: false) | | `--page-limit int` | Maximum number of records to return (default: 10) | | `--page-number int` | Page number (default: 1) | Example: ```bash kapten environments list ``` ## kapten environments update Updates an environment. Fields left out keep their value. ```bash kapten environments update [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { name: (string pattern:\S minLen:1) The updated name of the environment. } ``` Example: ```bash kapten environments update 'name: string' ``` --- # kapten jobs Source: https://docs.kapten.io/cli/reference/jobs Every command takes the [global flags](/cli/reference#global-flags). ## kapten jobs create Creates a cron or one-off job in an environment. ```bash kapten jobs create [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { configuration*: { arguments: [ (string) ] cpu_limit_in_milli: (string) Maximum cpu that can be allocated to the job based on organization cluster configuration. unit is millicores (m). 1000m = 1 cpu cpu_request_in_milli: (string) unit is millicores (m). 1000m = 1 cpu default_port: (integer default: min:1) Port where to run readiness and liveliness probes checks. The port will not be exposed externally entrypoint: (string) Container entrypoint healthchecks*: { liveness_probe: { failure_threshold: (integer default:9) initial_delay_seconds: (integer default:30) period_seconds: (integer default:10) success_threshold: (integer default:1) timeout_seconds: (integer default:5) type: { exec: <...> grpc: <...> http: <...> tcp: <...> } } readiness_probe: { failure_threshold: (integer default:9) initial_delay_seconds: (integer default:30) period_seconds: (integer default:10) success_threshold: (integer default:1) timeout_seconds: (integer default:5) type: { exec: <...> grpc: <...> http: <...> tcp: <...> } } } max_duration_seconds: (integer min:0) Maximum number of seconds allowed for the job to run before killing it and mark it as failed max_nb_restart: (integer min:0) Maximum number of restart allowed before the job is considered as failed 0 means that no restart/crash of the job is allowed ram_limit_in_mib: (string) Maximum memory that can be allocated to the job based on organization cluster configuration. unit is MB. 1024 MB = 1GB ram_request_in_mib: (string) unit is MB. 1024 MB = 1GB source: oneOf{ { image_name*: (string pattern:\S minLen:1) image name tag*: (string pattern:\S minLen:1) tag of the image container } } } cron: (string format:cron) Specifies the job schedule using standard cron format (minute hour day month weekday). Does not include seconds field - follows the traditional 5-field cron syntax. description: (string) name*: (string pattern:\S minLen:1) Name of the job timezone: (string format:timezone) Specifies the timezone for the cron job. Defaults to UTC. } ``` Example: ```bash kapten jobs create [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `job-id` | The unique identifier for the job | Example: ```bash kapten jobs deploy ``` ## kapten jobs get Returns a job. ```bash kapten jobs get [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `job-id` | The unique identifier for the job | Example: ```bash kapten jobs get ``` ## kapten jobs get-run Returns one deployment run of the job. ```bash kapten jobs get-run [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `job-id` | The unique identifier for the job | | `component-run-id` | The unique identifier for the component run | Example: ```bash kapten jobs get-run ``` ## kapten jobs list-runs Returns the job's deployment runs, a page at a time. ```bash kapten jobs list-runs [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `job-id` | The unique identifier for the job | | Flag | Description | | --- | --- | | `--action string` | Filter component runs by action. | | `--created-after string` | Filter component runs created at or after this timestamp. | | `--created-before string` | Filter component runs created at or before this timestamp. | | `--page-limit int` | Maximum number of records to return (default: 10) | | `--page-number int` | Page number (default: 1) | | `--status string` | Filter component runs by deployment status. | | `--trigger string` | Filter component runs by trigger source. | Example: ```bash kapten jobs list-runs ``` ## kapten jobs query-run-logs Returns the deployment logs of one job run: what Kapten did while deploying it, and what its agent on the cluster did. For the job's own output, use the component logs. Without `from` or `to`, the window spans the run, from its start to its end. Logs follow the retention of the log backend, so the logs of an old run may be gone, and runs from before run logs existed return an empty list. ```bash kapten jobs query-run-logs [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `job-id` | The unique identifier for the job | | `component-run-id` | The unique identifier for the component run | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { from: (string format:date-time) Inclusive lower bound for the run log time range. levels: [ (string) ] limit: (integer format:int32 default:200 min:1 max:1000) Maximum number of most recent raw backend records to query. source: [ (string enum:control_plane,agent,builder) ] text: (string) Optional phrase to search in the log message. to: (string format:date-time) Inclusive upper bound for the run log time range. view: (string default:both enum:timeline,raw,both) Which run log projection to return. } ``` Example: ```bash kapten jobs query-run-logs 'limit: 200, source: [control_plane, agent], view: timeline' ``` ## kapten jobs update Updates a job. Fields left out keep their value. ```bash kapten jobs update [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `job-id` | The unique identifier for the job | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { configuration: { arguments: [ (string) ] cpu_limit_in_milli: (string) Updated CPU limit. cpu_request_in_milli: (string) Updated CPU request. default_port: (integer min:1) Updated default probe port. entrypoint: (string) Updated container entrypoint. healthchecks: { liveness_probe: { failure_threshold: (integer default:9) initial_delay_seconds: (integer default:30) period_seconds: (integer default:10) success_threshold: (integer default:1) timeout_seconds: (integer default:5) type: { exec: <...> grpc: <...> http: <...> tcp: <...> } } readiness_probe: { failure_threshold: (integer default:9) initial_delay_seconds: (integer default:30) period_seconds: (integer default:10) success_threshold: (integer default:1) timeout_seconds: (integer default:5) type: { exec: <...> grpc: <...> http: <...> tcp: <...> } } } max_duration_seconds: (integer min:0) Updated max duration in seconds. max_nb_restart: (integer min:0) Updated restart limit. ram_limit_in_mib: (string) Updated RAM limit. ram_request_in_mib: (string) Updated RAM request. source: oneOf{ { image_name*: (string pattern:\S minLen:1) image name tag*: (string pattern:\S minLen:1) tag of the image container } } } cron: (string format:cron) Updated cron schedule. description: (string) Updated job description. name: (string pattern:\S minLen:1) Updated job name. timezone: (string format:timezone) Updated cron timezone. type: allOf{ (string enum:cron,one_time) Job scheduling strategy. } } ``` Example: ```bash kapten jobs update [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { description: (string) is_active: (boolean) name*: (string pattern:\S minLen:1) } ``` Example: ```bash kapten pipelines create 'description: string, is_active: true, name: string' ``` ## kapten pipelines delete Deletes a pipeline. ```bash kapten pipelines delete [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `pipeline-id` | The unique identifier for the pipeline | Example: ```bash kapten pipelines delete ``` ## kapten pipelines deploy Starts a run of the pipeline, which deploys its stages in order. ```bash kapten pipelines deploy [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `pipeline-id` | The unique identifier for the pipeline | Example: ```bash kapten pipelines deploy ``` ## kapten pipelines get Returns a pipeline. ```bash kapten pipelines get [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `pipeline-id` | The unique identifier for the pipeline | | Flag | Description | | --- | --- | | `--filter-with-deleted` | Include deleted instances (default: false) | Example: ```bash kapten pipelines get ``` ## kapten pipelines get-run Returns a pipeline run, with the state of each of its stages. ```bash kapten pipelines get-run [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `pipeline-run-id` | The unique identifier for the pipeline run | Example: ```bash kapten pipelines get-run ``` ## kapten pipelines list Returns an environment's pipelines, a page at a time. ```bash kapten pipelines list [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | Flag | Description | | --- | --- | | `--filter-with-deleted` | Include deleted instances (default: false) | | `--page-limit int` | Maximum number of records to return (default: 10) | | `--page-number int` | Page number (default: 1) | Example: ```bash kapten pipelines list ``` ## kapten pipelines list-runs Returns a pipeline's runs, a page at a time. ```bash kapten pipelines list-runs [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `pipeline-id` | The unique identifier for the pipeline | | Flag | Description | | --- | --- | | `--page-limit int` | Maximum number of records to return (default: 10) | | `--page-number int` | Page number (default: 1) | Example: ```bash kapten pipelines list-runs ``` ## kapten pipelines update Updates a pipeline's own fields. Change its stages with the stage endpoints. ```bash kapten pipelines update [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `environment-id` | The unique identifier of the environment | | `pipeline-id` | The unique identifier for the pipeline | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { description: (string) is_active: (boolean) name: (string pattern:\S minLen:1) } ``` Example: ```bash kapten pipelines update 'description: string, is_active: true, name: string' ``` --- # kapten projects Source: https://docs.kapten.io/cli/reference/projects Every command takes the [global flags](/cli/reference#global-flags). ## kapten projects create Creates a project and returns it. ```bash kapten projects create [flags] ``` | Argument | Description | | --- | --- | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { description*: (string) The description of the project. name*: (string pattern:\S minLen:1) The name of the project. } ``` Example: ```bash kapten projects create 'description: string, name: string' ``` ## kapten projects delete Deletes a project. ```bash kapten projects delete [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | Example: ```bash kapten projects delete ``` ## kapten projects get Returns a project. ```bash kapten projects get [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | Example: ```bash kapten projects get ``` ## kapten projects list Returns the organization's projects, a page at a time. ```bash kapten projects list [flags] ``` | Flag | Description | | --- | --- | | `--filter-with-deleted` | Include deleted instances (default: false) | | `--page-limit int` | Maximum number of records to return (default: 10) | | `--page-number int` | Page number (default: 1) | Example: ```bash kapten projects list ``` ## kapten projects update Updates a project's name and description. ```bash kapten projects update [flags] ``` | Argument | Description | | --- | --- | | `project-id` | The unique identifier for the project | | `body...` | The request body, as shorthand or JSON. See [Request bodies](/cli/request-bodies). | | Flag | Description | | --- | --- | | `--rsh-generate-body` | Print an example request body and exit | | `--rsh-validate` | Validate the JSON request body against the OpenAPI schema before sending | Request body fields, `*` for required: ```text { description: (string) The description of the project. name: (string pattern:\S minLen:1) The updated name of the project. } ``` Example: ```bash kapten projects update 'description: string, name: string' ``` --- # kapten skills Source: https://docs.kapten.io/cli/reference/skills See [Coding agents](/cli/mcp) for what the skill and the MCP servers give an agent. Every command takes the [global flags](/cli/reference#global-flags). ## kapten skills install Write the kapten agent skill of this CLI version where coding agents read skills: in the current project, or for the user with --global. Without --agent, it installs for every agent that has run on this machine. Agents: claude-code, codex, cursor, opencode, copilot. With --mcp, it also adds two MCP servers to each agent's configuration, leaving other entries untouched: kapten (`kapten mcp serve`, with --context when given) and kapten-docs (https://docs.kapten.io/mcp). Running it again updates what it wrote. ```bash kapten skills install [flags] ``` | Flag | Description | | --- | --- | | `--agent strings` | Agents to install for, comma-separated: claude-code, codex, cursor, opencode, copilot | | `--dir string` | Project root (default: the current directory) | | `--dry-run` | Print what would be written, and write nothing | | `--global` | Install for the user instead of the current project | | `--mcp` | Also add the kapten and kapten-docs MCP servers | Examples: ```bash kapten skills install kapten skills install --agent claude-code --mcp kapten skills install --global --mcp --dry-run kapten --context work skills install --agent codex --mcp ``` --- # kapten usage Source: https://docs.kapten.io/cli/reference/usage Every command takes the [global flags](/cli/reference#global-flags). ## kapten usage environments How long each environment of the token's organization was active in the period [since, until), from its creation to its deletion. Usage is counted in hourly UTC windows: both bounds are truncated to the hour, and a period spans at most 93 days. Only hours before `closed_through` are counted, and an hour closes about five minutes after it ends. Environments that were not active in the period are left out. Requires organization_update on the organization. The billable minutes are the ones the subscription is billed for. ```bash kapten usage environments [flags] ``` | Argument | Description | | --- | --- | | `since` | Start of the period, truncated to the hour. | | `until` | End of the period (exclusive), truncated to the hour. | Example: ```bash kapten usage environments ``` --- # Request bodies Source: https://docs.kapten.io/cli/request-bodies Commands that create or update a resource take its fields as their last arguments. Each command's page in the [command reference](/cli/reference) lists the fields, `*` marking the required ones. ## Shorthand Write the fields as `name: value` pairs, separated by commas, in one quoted argument: ```bash kapten projects create 'name: storefront, description: "The online shop"' ``` - Nested fields use dots: `parent.child: value`. - `[]` appends to a list: `list[]: value`. - Unquoted values become numbers, `true`, `false` or `null` when they look like one. Quote a value to keep it a string: `port: "8080"`. ## JSON Pipe a JSON (or YAML) document to the command instead: ```bash kapten projects create < project.json echo '{"name": "storefront", "description": "The online shop"}' | kapten projects create ``` Shorthand arguments after a piped document change it before it is sent, which lets you reuse one file: ```bash kapten projects create 'name: storefront-eu' < project.json ``` ## Check a body before sending it `--rsh-generate-body` prints an example body for the command, with every field, and sends nothing. `--rsh-validate` checks the body against the API's schema before sending it. --- # How Kapten works Source: https://docs.kapten.io/concepts Kapten runs your workloads on Kubernetes clusters in your own cloud account. Its control plane, the **Engine**, stores what you want to run and drives an agent installed on each of your clusters to make it happen. ```text Organization ├── Clusters Kubernetes clusters you connected ├── Integrations GitHub installations └── Projects └── Environments development, staging or production, each on one cluster ├── Components applications, jobs and databases ├── Variables and secrets └── Pipelines ``` - An **[organization](/concepts/organizations-and-roles)** owns everything and decides who can do what through roles. - A **[cluster](/concepts/clusters)** is a Kubernetes cluster that Kapten deploys to. - A **[project](/concepts/projects)** groups the services that ship together. - An **[environment](/concepts/environments)** is one deployment of a project, such as `staging` or `production`, on one cluster. - A **[component](/concepts/components)** is something that runs in an environment: an application, a job or a database. - **[Variables and secrets](/concepts/variables-and-secrets)** configure components, per project, environment or component. - A **[pipeline](/concepts/pipelines)** deploys several components of an environment in ordered stages. Every deployment of a component is recorded as a **run**, with its status, its timeline and its logs, so you can see what was deployed, when, and why it failed. --- # Billing Source: https://docs.kapten.io/concepts/billing Kapten bills **environment minutes**: each [environment](/concepts/environments) counts for every minute it exists, from its creation to its deletion. There is no charge per user, so you can invite your whole team. - Usage is counted per UTC hour. Each environment counts the minutes it was active in that hour, and any started minute counts as a full minute: an environment that existed for ten seconds counts one minute. - Deleting an environment stops its usage. - Your [clusters](/concepts/clusters) run in your own cloud account, so their compute, storage and network are billed by your cloud provider, not by Kapten. Members allowed to manage billing see the current usage per environment and per day in the organization's billing settings. --- # Clusters Source: https://docs.kapten.io/concepts/clusters A **cluster** is a Kubernetes cluster that Kapten deploys to. Kapten does not host your workloads: your applications, jobs and databases run on clusters in your own cloud account, so your data stays in your infrastructure and your cloud bill stays yours. ## Connecting a cluster You connect a cluster with: - a **name**, - its **cloud provider**: `aws`, `gcp`, or `custom` for any other Kubernetes cluster, - its **kubeconfig**, which Kapten uses to install and update its agent. Kapten then installs its **agent** on the cluster, with the components it relies on: an ingress gateway, cert-manager for TLS certificates, and collectors for logs and metrics. They live in namespaces whose names start with `kapten`. The agent carries out deployments for the Engine and reports their progress and logs back. See [Connect a cluster](/guides/connect-a-cluster). ## Cluster state | State | Meaning | | --- | --- | | Waiting for agent | Kapten has not heard from the cluster yet. | | Bootstrapping | Kapten is installing its agent. It takes a few minutes. | | Connected | The agent is installed and the cluster accepts deployments. | | Updating | Kapten is updating its agent on the cluster. | | Bootstrap failed | Kapten could not install its agent: check the kubeconfig's credentials and that the cluster's API server is reachable, then sync. | | Update failed | The last update failed. Sync to try again. | **Sync** reinstalls or updates the agent. Replacing a cluster's kubeconfig also starts a sync. ## Environments on a cluster Each [environment](/concepts/environments) runs on exactly one cluster, and a cluster can host the environments of many projects. A common setup is one cluster for production and one shared by development and staging. --- # Components Source: https://docs.kapten.io/concepts/components A **component** is something Kapten runs in an [environment](/concepts/environments). There are three kinds: applications, jobs and databases. Every deployment of a component is a **run**, with its status, a timeline of its steps and its logs. ## Applications An **application** is a long-running service, such as a web app, an API or a queue worker. Its source is one of: - **GitHub**: a repository and branch from a connected [GitHub installation](/guides/deploy-from-github). Kapten builds a container image from the repository with [Railpack](https://railpack.com), which detects the language and framework, and can rebuild automatically on every push to the branch. - **Container**: an image name and tag from a container registry. An application also defines: | Setting | Description | | --- | --- | | Resources | CPU and memory requests and limits, and an optional GPU count. See [Resources](/reference/resources). | | Instances | Minimum and maximum number of running instances. | | Ports | Internal ports the application listens on, each with a protocol: `HTTP`, `GRPC`, `TCP` or `UDP`. One port is the default. | | Storage | Persistent volumes, each with a mount path, a size in GiB and a Kubernetes storage class. | | Health checks | A readiness probe, which decides when an instance receives traffic, and a liveness probe, which restarts an instance that stopped responding. Each is an HTTP, TCP, gRPC or command check. | | Runtime command | An entrypoint and arguments that replace the image's own. | ## Jobs A **job** runs a container until it exits. It is either: - **cron**: run on a schedule written in the standard five-field cron syntax (`minute hour day month weekday`), in UTC unless you set a time zone; - **one-time**: run once, when you deploy it. A job sets the same resources as an application, plus the maximum number of restarts allowed before the run fails (`0` allows none) and the maximum duration after which it is stopped and marked failed. ## Databases A **database** is a PostgreSQL, MySQL, MongoDB or Redis instance. It is provisioned either: - **in cluster**: Kapten runs the database on the environment's cluster; - **managed**: Kapten provisions the database service of your cloud provider. You choose its engine version, whether it is reachable only from inside the cluster (`PRIVATE`) or from the internet (`PUBLIC`), its resources, and whether to enable disk encryption, high availability and backups. Kapten generates the database's credentials and adds them to the environment as [secrets](/concepts/variables-and-secrets#database-secrets), so your applications can connect without copying passwords around. --- # Environments Source: https://docs.kapten.io/concepts/environments An **environment** is one deployment of a [project](/concepts/projects), for example `staging` or `production`. It is the boundary that owns components: each environment has its own applications, jobs and databases, its own [variables and secrets](/concepts/variables-and-secrets) and its own [pipelines](/concepts/pipelines). ## Type and cluster When you create an environment you choose: - its **type**: `development`, `staging` or `production`, which tells your team what the environment is for (see [Environment types](/reference/environment-types)); - its **cluster**: the [cluster](/concepts/clusters) its components run on. Environments of the same project can run on different clusters, for example production on a dedicated cluster. ## Isolation Each environment gets its own Kubernetes namespace on its cluster. Components of an environment reach each other inside that namespace; a database in one environment is not shared with another. ## Access A role grant on an environment covers the environment and every component in it. See [Organizations and roles](/concepts/organizations-and-roles). ## Billing Kapten bills the time each environment exists, by the minute. See [Billing](/concepts/billing). --- # Organizations and roles Source: https://docs.kapten.io/concepts/organizations-and-roles An **organization** is the top-level account in Kapten. It owns your [clusters](/concepts/clusters), [projects](/concepts/projects) and integrations such as GitHub, and it is the unit you are [billed](/concepts/billing) for. You can belong to several organizations and switch between them. ## Members People sign in to Kapten with their email address: Kapten sends them a one-time sign-in link, there is no password. A user is a **member** of an organization while they hold at least one of its roles. ## Roles A **role** is a named set of permissions. Every organization starts with three built-in roles, which cannot be changed: | Role | Can do | | --- | --- | | `owner` | Everything, including deleting the organization. | | `admin` | Everything except deleting the organization. | | `member` | Belong to the organization and see its access control. Nothing else until given more. | ### Custom roles To give someone access to only part of the organization, create a custom role. A role is a list of **grants**: a permission, such as `environment:create` or `project:delete`, applied to a **scope**: - the whole organization, - all resources of a type, such as every project, - or selected instances, such as one project or one environment. Roles only add permissions: a member holding several roles can do everything any of them allows. A grant on a project includes read access to everything inside it, including environments created later. A grant on an environment lets the member read its project, but not the project's other environments. ## Deleting resources Kapten only deletes a resource once it is empty: you cannot delete a project that still has environments, or an environment that still has pipelines. Delete what it contains first. ## Activity Every change made in an organization is recorded with who made it and when. Members allowed to read it find it in the organization's activity log. --- # Pipelines Source: https://docs.kapten.io/concepts/pipelines A **pipeline** deploys several [components](/concepts/components) of one [environment](/concepts/environments) in a set order: for example, run the database migration job, then deploy the API and the worker together, then the web frontend. ## Stages A pipeline is a list of **stages**, shown as steps in the console, run one after the other. Each stage lists the components it deploys, and **all components of a stage deploy at the same time**. The next stage starts once every component of the current one has finished. A component appears in at most one stage of a pipeline, so it deploys once per run. Each component in a stage has two settings. The console adds components as required with no timeout; the Kapten API can change both. | Setting | Description | | --- | --- | | Required | When a required component fails, its stage fails. A component that is not required can fail without failing the stage. | | Timeout | How long, in seconds, the component's deployment may take before it counts as failed. | ## When a stage fails Each stage has a failure policy: | Policy | Behavior | | --- | --- | | Stop the pipeline (`STOP_PIPELINE`) | The pipeline stops. The stages after it are skipped. | | Continue with the next step (`CONTINUE_PIPELINE`) | The pipeline goes on with the next stage, and is reported as failed at the end. | ## Runs Starting a pipeline creates a **pipeline run**. It records the status and timing of the pipeline, of each stage and of each component deployment, with a message explaining any failure. Each component deployment is also a run of the component, with its own logs. A pipeline can be deactivated to keep its definition without running it. --- # Projects Source: https://docs.kapten.io/concepts/projects A **project** groups the components that make up one product or service, for example a web application, its API, a background worker and their database. A project contains [environments](/concepts/environments), and each environment holds its own copy of the components. Use one project per thing you deploy and release as a whole. Two services that are released independently by different teams usually belong in two projects, which also lets you give each team access to its own project only with [roles](/concepts/organizations-and-roles#custom-roles). ## Project variables Variables and secrets set on the project apply to every component in every environment of that project. See [Variables and secrets](/concepts/variables-and-secrets). --- # Variables and secrets Source: https://docs.kapten.io/concepts/variables-and-secrets Kapten passes configuration to your components as **variables**. A variable is either: - a **key/value** pair, exposed to the container as an environment variable; - a **file**, mounted in the container at an absolute path you choose. A **secret** is a variable whose value is stored in a secrets vault instead of the Engine's database. Once saved, a secret's value is never shown again, in the console or through the API: you can replace it, not read it. ## Where to set them | Level | Applies to | | --- | --- | | Project | Every component of every environment of the project. | | Environment | Every component of that environment. | | Component | One application, job or database. | Set shared settings, such as a log level, on the project, values that differ between staging and production on the environment, and anything specific to one service on the component. Changing a variable takes effect at the component's next deployment. ## Database secrets When you create a [database](/concepts/components#databases), Kapten adds its credentials to the environment as secrets named after the database. For a database named `main`: | Secret | Value | | --- | --- | | `KAPTEN_DATABASE_MAIN_HOST` | Host name to connect to | | `KAPTEN_DATABASE_MAIN_USERNAME` | User name | | `KAPTEN_DATABASE_MAIN_PASSWORD` | Password | | `KAPTEN_DATABASE_MAIN_DATABASE` | Database name | | `KAPTEN_DATABASE_MAIN_CONNECTION_STRING` | Full connection URL | The database name is upper-cased, and each run of characters other than letters and digits becomes a single `_`. These secrets are managed by Kapten: you cannot edit or delete them, and they are removed with the database. --- # Guides Source: https://docs.kapten.io/guides Each guide covers one task, from start to finish. New to Kapten? Start with the [Quickstart](/quickstart). --- # Add a database Source: https://docs.kapten.io/guides/add-a-database 1. **Choose the engine** In your environment, create a database and pick **PostgreSQL**, **MySQL**, **MongoDB** or **Redis**. 2. **Name it** Enter its name, the engine version, and optionally the name of the logical database to create in it. The name decides the names of its [secrets](#connect-your-application). 3. **Choose provisioning and access** - **In cluster** runs the database on the environment's cluster. **Managed** provisions your cloud provider's database service. - **Private** keeps it reachable from inside the cluster only. Choose **Public** only if something outside the cluster must connect to it. 4. **Size it** Set its CPU, memory and disk. 5. **Choose the options** Turn on disk encryption, high availability and backups as needed, then review and create the database. ## Connect your application Kapten adds the database's credentials to the environment as secrets. For a database named `main`, every component of the environment gets: ```bash KAPTEN_DATABASE_MAIN_HOST KAPTEN_DATABASE_MAIN_USERNAME KAPTEN_DATABASE_MAIN_PASSWORD KAPTEN_DATABASE_MAIN_DATABASE KAPTEN_DATABASE_MAIN_CONNECTION_STRING ``` Read them in your code, or map them to the name your framework expects with a component variable. Redeploy applications that were running before the database existed so they pick up the new secrets. ```js // Node.js, with the pg package import pg from "pg"; const pool = new pg.Pool({ connectionString: process.env.KAPTEN_DATABASE_MAIN_CONNECTION_STRING, }); ``` See [Database secrets](/concepts/variables-and-secrets#database-secrets) for how the names are formed. --- # Build a pipeline Source: https://docs.kapten.io/guides/build-a-pipeline This guide builds a three-step [pipeline](/concepts/pipelines) for a typical release: migrate the database, deploy the backend, then the frontend. 1. **Create the pipeline** In your project, open **Pipelines**, then **New pipeline**. Name it, for example `release`. 2. **Add the steps** Add three steps, which run in this order: | Step | Services | If a service fails | | --- | --- | --- | | `migrate` | the `migrate` job | Stop the pipeline | | `backend` | `api`, `worker` | Stop the pipeline | | `frontend` | `web` | Stop the pipeline | Services in the same step deploy together. Drag a step to change when it runs. 3. **Run it** Click **Run pipeline**. Each run appears below the steps: open one to see how each service went and read its logs. If the migration fails, the `backend` and `frontend` steps are skipped and the running version stays in place. Choose **Continue with the next step** for a step whose failure should not block the rest. --- # Connect a cluster Source: https://docs.kapten.io/guides/connect-a-cluster Kapten deploys into [clusters](/concepts/clusters) you own. Connecting one takes a kubeconfig file and a few minutes while Kapten installs its agent. ## Requirements - A Kubernetes cluster, on AWS, Google Cloud or any other provider. - `kubectl` access to the cluster with rights to create a service account and bind it to `cluster-admin`, since Kapten installs its agent with it. - The cluster's API server must be reachable from the internet. ## Create a kubeconfig for Kapten The kubeconfig your cloud CLI writes (`aws eks update-kubeconfig`, `gcloud container clusters get-credentials`) gets its token by running a local command, such as `aws` or `gke-gcloud-auth-plugin`, which Kapten cannot run. Give Kapten a service account of its own instead, with a long-lived token. Run these commands with your usual `kubectl` context pointing at the cluster: 1. **Create the service account** ```bash kubectl create namespace kapten-access kubectl create serviceaccount kapten --namespace kapten-access kubectl create clusterrolebinding kapten --clusterrole cluster-admin --serviceaccount kapten-access:kapten ``` 2. **Create its token** ```bash kubectl apply -f - < kapten-kubeconfig.yaml < **Warning** > > A kubeconfig is a credential to your cluster. Keep the file out of your repository and delete your local copy once the cluster is connected. ## Connect it 1. **Open Clusters** In the [Kapten console](https://app.kapten.io), open **Clusters**, then **Connect cluster**. 2. **Describe the cluster** Enter a name, choose the cloud provider (**AWS**, **GCP** or **Custom**), and upload the kubeconfig file. 3. **Wait for the agent** The cluster shows **Bootstrapping** while Kapten installs its agent, then **Connected**. You can now create [environments](/concepts/environments) on it. ## Replace the kubeconfig When the credentials change, open the cluster's menu, choose **Edit cluster**, and upload the new kubeconfig. Kapten syncs the agent with it. Leave the file empty to keep the current one. ## Troubleshooting If the cluster shows **Bootstrap failed**, Kapten could not install its agent: - Check that the kubeconfig works on its own: `kubectl --kubeconfig ./kapten-kubeconfig.yaml get nodes`. - Check that it holds a token, not an `exec` section that runs a local command such as `aws` or `gke-gcloud-auth-plugin`. - Check that the API server accepts connections from outside your network. Then upload a corrected kubeconfig, or **Sync** the cluster to try again. --- # Deploy a container image Source: https://docs.kapten.io/guides/deploy-a-container-image If you already build your images, in CI or elsewhere, deploy them as they are: Kapten pulls the image and runs it. 1. **Create the application** In your environment, create an application and choose **Container** as its source. Enter the image name, such as `ghcr.io/acme/api`, and its tag, such as `1.4.2`. 2. **Set the runtime command** Optional: override the image's entrypoint and arguments. 3. **Set resources and instances** Set CPU and memory requests and limits, for example a request of `250m` CPU and `256Mi` memory. See [Resources](/reference/resources) for the units. Set the minimum and maximum number of running instances. 4. **Declare ports and volumes** Add each port the application listens on, with its protocol, and mark one as the default. Add a persistent volume for any path whose data must survive a restart. 5. **Add health checks** A **readiness** check tells Kapten when an instance can receive traffic; a **liveness** check restarts an instance that stopped responding. For a web service, an HTTP check on a health endpoint such as `/healthz` is usually enough for both. 6. **Create and deploy** Kapten deploys the application as soon as it is created. Open it to follow the run and read its logs. ## Deploy a new version Change the application's tag and deploy it again. To deploy several applications in a set order, use a [pipeline](/guides/build-a-pipeline). > **Tip** > > Use immutable tags, such as a version or a commit SHA, rather than `latest`: each run then records exactly what it deployed. --- # Deploy from GitHub Source: https://docs.kapten.io/guides/deploy-from-github Kapten can build your application from a GitHub repository and deploy it again on every push to a branch. You do not need a Dockerfile: Kapten builds the image with [Railpack](https://railpack.com), which detects your language and framework. ## Connect GitHub Kapten reads your repositories through the **Kapten GitHub App**. It asks only for read access to their contents and metadata, and for push events. 1. **Install the GitHub App** In the [Kapten console](https://app.kapten.io), open **Integrations**, then **Connect GitHub**. GitHub asks which account to install the app on, a personal account or an organization, and which repositories it can read: all of them, or the ones you select. 2. **Come back to Kapten** GitHub returns you to Kapten, which lists the installation. Every member of your organization allowed to configure components can now build from these repositories. To give Kapten access to more repositories later, change the installation's repository access on GitHub, then refresh the list in Kapten. ## Create the application 1. **Choose the source** In your environment, create an application and choose **GitHub** as its source. Select the installation, the repository and the branch to deploy. 2. **Set the build** **Build context** is the folder Kapten builds from, relative to the repository root: `.` by default, or a folder such as `services/api` in a monorepo. Set the CPU and memory the build may use, and its timeout. 3. **Choose when to build** With automatic builds on, Kapten builds and deploys on every push to the branch. **Path rules** narrow that down: | Rule | Kapten builds when | | --- | --- | | No path filter | Any file changed. | | Include | At least one changed file matches a pattern. | | Exclude | At least one changed file matches none of the patterns. | Patterns are relative to the repository root and case-sensitive, for example `services/api/**`. 4. **Configure and deploy** Set the application's ports, resources and health checks (see [Applications](/concepts/components#applications)), then **Create and deploy**. Each build and deployment is a run of the application: open it to follow the build, the deployment and their logs. ## Disconnect GitHub Disconnecting an installation in **Integrations** stops new builds from its repositories. The GitHub App stays installed on GitHub, and past runs are kept. Uninstall the app from your GitHub settings to remove its access entirely. --- # Schedule a job Source: https://docs.kapten.io/guides/schedule-a-job A [job](/concepts/components#jobs) runs a container until it exits: a nightly report, a cleanup, a data import. 1. **Create the job** In your environment, create a job and name it. 2. **Choose when it runs** Choose **Cron** and enter a schedule in the five-field cron syntax, with an optional time zone (UTC by default). Or choose **One-time** to run it once, when it is deployed. 3. **Set the container** Enter the image and tag, and optionally the entrypoint and arguments. 4. **Set the limits** Set its CPU and memory, then: - the maximum number of restarts before the run counts as failed (`0` allows none); - the maximum duration, in seconds, after which Kapten stops it and marks it failed. 5. **Create it** Review and create the job. Each execution is a run with its own status and logs. ## Cron examples | Schedule | Runs | | --- | --- | | `0 * * * *` | Every hour, on the hour | | `*/15 * * * *` | Every 15 minutes | | `30 2 * * *` | Every day at 02:30 | | `0 9 * * 1` | Every Monday at 09:00 | | `0 0 1 * *` | On the first day of every month, at midnight | Seconds are not supported. > **Tip** > > To run database migrations before deploying a new version of your application, make the migration a one-time job and put it in the first stage of a [pipeline](/guides/build-a-pipeline). --- # Quickstart Source: https://docs.kapten.io/quickstart In this quickstart you deploy a public container image to a Kubernetes cluster you own. It takes about ten minutes, most of it while Kapten installs its agent on the cluster. ## Before you start - A Kapten account. Sign in at [https://app.kapten.io](https://app.kapten.io) with your email address: Kapten sends you a sign-in link, there is no password. - A Kubernetes cluster, on AWS, Google Cloud or any other provider, and its **kubeconfig** file with cluster-admin rights. Kapten installs its agent with it. ## Deploy your first service 1. **Create your organization** The first time you sign in, Kapten asks you to name your organization. Everything you create belongs to it, and you can [invite your team](/concepts/organizations-and-roles) later. 2. **Connect a cluster** Open **Clusters**, then **Connect cluster**. Give the cluster a name, pick its cloud provider, and upload its kubeconfig file. Kapten installs its agent on the cluster. The cluster shows as connected after a few minutes. If it shows **Bootstrap failed**, see [Connect a cluster](/guides/connect-a-cluster#troubleshooting). 3. **Create a project** A [project](/concepts/projects) groups the services that ship together, like an app and its database. Click **Create project** and name it, for example `storefront`. 4. **Add an environment** In the project, add an [environment](/concepts/environments): name it `production`, choose the **production** type, and select the cluster you connected. 5. **Deploy a service** In the environment, click **Deploy a service** and choose **Container image**. Enter: | Field | Value | | --- | --- | | Name | `web` | | Image | `nginxinc/nginx-unprivileged` | | Tag | `stable` | | Port | `8080`, protocol HTTP | Kapten deploys the service as soon as you create it. Open it to follow the deployment and read its logs. ## Next steps **[Deploy from GitHub](/guides/deploy-from-github)** Build and deploy your own code on every push. **[Add a database](/guides/add-a-database)** Give your service a PostgreSQL database and its connection string. **[Variables and secrets](/concepts/variables-and-secrets)** Configure your service per environment. **[Pipelines](/concepts/pipelines)** Deploy several components in order. --- # Reference Source: https://docs.kapten.io/reference Reference pages describe settings precisely. For step-by-step instructions, see the [Guides](/guides). --- # Environment types Source: https://docs.kapten.io/reference/environment-types Every [environment](/concepts/environments) has one of three types, chosen when it is created: | Type | Use it for | | --- | --- | | `development` | Day-to-day work and experiments, where breaking things is fine. | | `staging` | A copy of production to test releases before they ship. | | `production` | What your users rely on. | The type labels the environment for your team and in the console. An environment's type and cluster cannot be changed after it is created: to move an environment to another cluster, create a new environment there. --- # Resources Source: https://docs.kapten.io/reference/resources Kapten passes resources to Kubernetes as requests and limits, in Kubernetes units. ## CPU CPU is set in **millicores**, written with an `m` suffix: `1000m` is one CPU core. | Value | CPU | | --- | --- | | `250m` | A quarter of a core | | `500m` | Half a core | | `1000m` | One core | | `2000m` | Two cores | ## Memory Memory is set in **mebibytes**, written with an `Mi` suffix: `1024Mi` is 1 GiB. | Value | Memory | | --- | --- | | `256Mi` | 256 MiB | | `512Mi` | 512 MiB | | `1024Mi` | 1 GiB | | `2048Mi` | 2 GiB | ## Requests and limits | Setting | Meaning | | --- | --- | | Request | What Kubernetes reserves for each instance. An instance is only scheduled on a node with this much free capacity. | | Limit | The most an instance may use. Above its CPU limit an instance is throttled; above its memory limit it is stopped and restarted. | Set the request to what the service uses under normal load and the limit to its peak. A limit far above the request lets one service starve others on the same node. ## GPU Applications can request whole GPUs with a GPU count. The cluster must have GPU nodes and their device plugin installed. ## Storage Persistent volumes are sized in whole **GiB**, and use a Kubernetes **storage class** of your cluster, such as `gp3` on EKS or `standard-rwo` on GKE. List the classes of your cluster with: ```bash kubectl get storageclass ``` ## Instances Applications run between a **minimum** and a **maximum** number of instances, both at least `1`. ## Builds Applications built from GitHub set the CPU and memory of their build separately from the application's own, in the same units, and a build timeout.