API reference

API Keys

List API Keys

List all API keys for the authenticated provider. Only the key prefix comes back, never the full key.

`prefix` is the first 16 characters of the key: enough to identify it in a list, not enough to use it. Revoked keys stay in the list with `status: "revoked"`.

API Keys

Create API Key

Create a new API key. The response contains the raw key, and it is the only time you will see it.

Parameters

namestringrequired

A name for the key, for your own reference

scopesstring[]default ["*"]

Permission scopes

modestringdefault live

Key mode: "live" or "test"

expires_atstring

ISO 8601 expiration date

Errors

• 400 Missing required field "name"

Only `name` is required. `mode` defaults to `live`, `scopes` defaults to `["*"]`, and `expires_at` must be RFC 3339 if you send it. The `key` field holds the raw token. Nothing else in the API returns it again, so copy it before you move on.

API Keys

Delete API Key

Revoke an API key. Takes effect immediately.

Errors

• 404 API key not found

The key is marked revoked rather than erased, so it keeps showing up in `GET /api-keys` with `status: "revoked"`. Deleting a key that belongs to another provider returns 404.

Tenants

List Tenants

List all tenants for the authenticated provider. Paginated, with an optional status filter.

Parameters

statusstring

Filter by status (e.g., ready, deploying, failed)

limitintdefault 20

Results per page

offsetintdefault 0

Pagination offset

sortstring

Sort field (e.g., created_at, name)

searchstring

Search by tenant name

Takes `limit` (1–100, default 20), `offset`, and `status` as query parameters. The live URL is `deployment_url`, and it stays empty until the first deploy routes successfully. Deleted tenants are excluded.

Tenants

Create Tenant

Create a new tenant environment. Supports a single-service (legacy) or multi-service request body.

Parameters

namestringrequired

Unique tenant name (used as subdomain)

display_namestring

Display name for the tenant

source_typestring

Source type: "github" or "image" (single-service mode)

repo_urlstring

Git repository URL (single-service mode)

branchstringdefault main

Git branch

servicesobject[]

Array of service definitions (multi-service mode)

envobject

Environment variables as key-value pairs

Errors

• 400 Validation error (missing name, invalid source_type, duplicate service names)
• 409 Tenant name already taken
• 422 Tenant limit reached for this provider

Creation is asynchronous, so the call returns 202 with the tenant at `status: "pending"`. Supply either `source_type` or `services[]`. A legacy body is wrapped into one primary service for you. The first deploy is queued automatically. `auto_deploy_started` tells you whether that worked; if it did not, `auto_deploy_error` explains why and the tenant is marked failed rather than left pending. Pass `"deploy_on_create": false` to stage the configuration without deploying. Watch progress at `GET /api/v1/tenants/{id}/events`. A duplicate name returns 409, and exceeding your plan's tenant limit returns 422.

Tenants

Get Tenant

Get full details for a tenant, including its services.

Errors

• 404 Tenant not found

Domains are not included here. Fetch them from `GET /tenants/{id}/domains`. When a deploy fails, `last_error` and `error_stage` carry the reason; `diagnostic_message` may appear mid-deploy with a non-fatal hint, such as a readiness probe that is not passing yet.

Tenants

Update Tenant

Partial update of a tenant. Only provided fields are changed.

Parameters

display_namestring

Display name for the tenant

branchstring

Default git branch

resource_sizestring

Resource tier: small, medium, large

app_portint

Application port

egress_modestring

Network egress mode: open or restricted

Errors

• 404 Tenant not found

`resource_size` must be `small`, `medium`, or `large`; `egress_mode` must be `allow_all` or `restricted`; `app_port` must be between 1 and 65535. Changes to build or runtime settings take effect on the next deploy. Trigger one with `POST /tenants/{id}/deployments`.

Tenants

Delete Tenant

Delete a tenant and every resource it owns.

Errors

• 404 Tenant not found

Returns 202. The tenant is soft-deleted right away (the name is freed and it drops out of `GET /tenants`) while containers, volumes, and routes are torn down in the background.

Services

List Services

List all services for a tenant.

A plain array, not paginated. Services deploy in `deploy_priority` order, lowest first.

Services

Add Service

Add a new service to an existing tenant.

Parameters

namestringrequired

Unique service name within the tenant

source_typestringrequired

Source type: "github" or "image"

repo_urlstring

Git repository URL

branchstringdefault main

Git branch

image_urlstring

Container image URL (for source_type "image")

portint

Service port

is_routablebooleandefault false

Whether the service receives HTTP traffic

resource_sizestringdefault small

Resource tier: small, medium, large

Errors

• 400 Missing required field (name or source_type)
• 409 Service name already exists in this tenant
• 422 Tenant is not in a deployable state

Returns 202. Creating the service also queues a deploy of it. `name` and `source_type` are required; `port` defaults to 8080 and `is_routable` to true. A service added this way is never primary. A duplicate name returns 409, and a tenant that is mid-deploy returns 422.

Services

Remove Service

Remove a service from a tenant. The primary service cannot be removed.

Errors

• 400 Cannot remove the primary service
• 404 Service not found

Addressed by service name, not ID. Removing the primary service returns 400. The tenant's aggregate status is recalculated from whatever services remain.

Services

Deploy Service

Trigger a deployment for one service.

Returns 202 with the tracking deployment record. `version` counts up per service. Subscribe to the tenant events stream to follow progress; a tenant that is already deploying returns 422.

Services

List Service Deployments

List deployment history for one service.

Paginated with `limit` and `offset`. `is_current` is scoped to this service: it marks the deployment currently serving traffic for THIS service, and every service in a tenant has its own current deployment. `has_config_snapshot` reports whether the deployment's configuration was captured, and `has_retained_secrets` whether its secret values are still held. A deployment that captured no secrets reports `has_retained_secrets: true`, because a rollback restores it in full. Together they tell you what a rollback to that deployment would restore before you request it. Roll one of these back with `POST /api/v1/tenants/{id}/services/{serviceName}/deployments/{depId}/rollback`.

Services

Service Logs

Stream logs for one service.

Parameters

linesintdefault 100

Number of log lines to return

followbooleandefault false

Stream logs in real-time (SSE)

`lines` defaults to 100 and caps at 5000. `follow=true` holds the connection open and streams new output, up to ten minutes. With no running pods you get 404; on a deployment without log streaming configured, 501.

Services

Deploy All Services

Deploy every service in a tenant at once.

Returns 202 with one tenant-level deployment record covering the whole run. Services build and deploy in `deploy_priority` order, and one failing service does not stop the others. The tenant's final status is derived from all of them together.

Services

Rollback Service Deployment

Roll one service back to an earlier deployment of that same service.

Returns 202. Restores one service to an earlier deployment of that same service, leaving every other service alone. Use this rather than the tenant-level rollback for anything in a multi-service tenant. The tenant-level endpoint redeploys the primary workload, so restoring a service's image through it would deploy that image tenant-wide, and it rejects service-scoped targets for that reason. No rebuild happens: the target's image already exists in the registry and is redeployed as-is. Configuration comes from the target's snapshot, with database credentials and inter-service discovery variables re-derived live on top, because those describe current topology. `config_source` reports which configuration was applied (`snapshot`, `partial` or `current`) with the same meaning as the tenant-level rollback, and `{"refresh_config": true}` opts into current configuration with the old image. Returns 404 when the deployment does not exist, belongs to another tenant, or belongs to a DIFFERENT service of this tenant. A sibling service's deployment is not visible on this route, so it reads as not found rather than as a validation error. Returns 422 when the target did not complete successfully, when it has no image to restore, or when the tenant is not in a deployable state (`pending`, `ready` or `failed`). The new deployment is versioned in the service's own sequence, not the tenant's, so its `version` continues that service's history. Configuration retention: a deployment's settings and non-secret variables are kept for the life of the deployment row, so `has_config_snapshot` stays true. Only secret VALUES are bounded, to the most recent 3 deployments per service by default. Operators can change this with the `config_snapshots.secret_retention` platform config key, which is read with a 30 second cache and needs no restart.

Deployments

List Deployments

List all deployments for a tenant, newest first.

Paginated with `limit` and `offset`. Status moves through `pending` → `building` → `deploying` → `succeeded` or `failed`. Deployments scoped to a single service also carry a `service_id`. `has_config_snapshot` reports whether the deployment's configuration was captured, and `has_retained_secrets` whether its secret values are still held. A deployment that captured no secrets reports `has_retained_secrets: true`, because a rollback restores it in full. Together they tell you what a rollback to that deployment would restore before you request it.

Deployments

Create Deployment

Trigger a new deployment for a tenant.

Parameters

branchstring

Git branch to deploy

commit_shastring

Specific commit to deploy

Returns 202. Every field is optional. An empty body builds the configured branch at its latest commit, with `source_type` falling back to `github`, `deploy_type` to `full`, `trigger` to `api`, and `image_tag` to `pending` until the build assigns a real tag. Use `source_ref` to pin a commit SHA or tag. Only tenants in `pending`, `ready`, or `failed` accept new deployments; anything else returns 422.

Deployments

Get Deployment

Get details for one deployment.

On a failure, `error_stage` names the pipeline stage that broke and `build_logs` holds the captured build output. Both are omitted on a clean deploy. `has_config_snapshot` reports whether the deployment's configuration was captured, and `has_retained_secrets` whether its secret values are still held. A deployment that captured no secrets reports `has_retained_secrets: true`, because a rollback restores it in full. Together they tell you what a rollback to that deployment would restore before you request it.

Deployments

Rollback Deployment

Roll back to a specific earlier deployment, restoring its image and the configuration it ran with.

Returns 202. `{depId}` is the deployment to RESTORE: the rollback runs as a new deployment that redeploys that deployment's image. By default it also restores the configuration that deployment ran with, rather than applying today's configuration to an old image. The response reports which was applied in `config_source`: - `snapshot`: image and configuration both restored, secrets included. - `partial`: settings and non-secret variables restored; the target's secret values are past the retention window, so current values are used for those. This is the usual result for an older deployment, and is normally what you want: a rotated credential should be current. - `current`: the deployment predates configuration snapshots, so current configuration is used. Send `{"refresh_config": true}` to keep the old image but deliberately use current configuration. A bare POST with no body keeps the default. Fails with 422 when the target did not complete successfully, when it has no image to restore, or when it is service-scoped. A service's deployment cannot be restored here, because this endpoint redeploys the tenant's primary workload and would push that image tenant-wide. Use `POST /api/v1/tenants/{id}/services/{serviceName}/deployments/{depId}/rollback` instead. Returns 404 when the deployment does not exist or belongs to another tenant. A rollback fails rather than deploying if the target named secret variables that no longer exist and whose values are past the retention window; the error names the keys. Recreate them, or retry with `refresh_config`. Configuration retention: a deployment's settings and non-secret variables are kept for the life of the deployment row, so `has_config_snapshot` stays true. Only secret VALUES are bounded, to the most recent 3 deployments per service by default. Operators can change this with the `config_snapshots.secret_retention` platform config key, which is read with a 30 second cache and needs no restart.

Environment Variables

Get Env Vars

List environment variables for a tenant.

Variables flagged `is_secret` come back with their value replaced by `[redacted]`, and nothing in the API reveals them again. `source` is `user` for anything you set and `system` for values Staxa injects, such as database credentials.

Environment Variables

Bulk Set Env Vars

Create or update environment variables in bulk.

The request body is a flat `Record<string, string>`, not a nested object. Keys are merged, not replaced: anything you send is created or overwritten, and anything you leave out is kept as it was. `updated` counts the keys in your request. Variables set this way are always non-secret and owned by you (`source: "user"`). Values are encrypted at rest and reach your containers on the next deploy. There is no endpoint for deleting a single variable. Set it to an empty string instead.

Domains

List Domains

List custom domains for a tenant.

Point your A record at the `server_ip` field, which is only present when the platform has one configured. Domain `status` runs `pending` → `verified` → `active`; `ssl_status` tracks certificate issuance separately.

Domains

Add Domain

Add a custom domain to a tenant.

Parameters

domainstringrequired

Custom domain name

is_primarybooleandefault false

Set as primary domain

service_idstring

Route to a specific service (multi-service tenants)

Returns 201. `type` defaults to `custom`, which is what generates the `verification_record` you need for the TXT check. `service_id` is optional and must be a service ID (`svc_...`) belonging to this tenant. Leave it out to route the domain at the primary service. Domains must be valid hostnames of 253 characters or fewer.

Domains

Verify Domain

Run the DNS check for a custom domain.

Always returns 200. The shape tells you the outcome. The check looks for a TXT record at `_staxa-verify.<your-domain>` matching `verification_record`; until that resolves you get the pending shape back, and you can call this as often as you need. Once it passes, the domain object is returned and the SSL certificate is issued automatically. A domain that is already verified or active is returned unchanged.

Domains

Delete Domain

Remove a custom domain from a tenant.

For a domain that reached `verified` or `active`, the route, certificate, and any managed CNAME record are cleaned up first.

Network Rules

List Network Rules

List network rules for a tenant, with optional filtering.

Parameters

directionstring

Filter: "inbound" or "outbound"

statusstringdefault active

Filter by status

A plain array, not paginated. Filter with `direction` (`inbound` or `outbound`) and `status`, which defaults to `active`. `connection_string` is computed on create and read, not stored, so it is absent from this list.

Network Rules

Create Network Rule

Create a network rule. Inbound TCP rules allocate a port; outbound rules require restricted egress mode.

Parameters

directionstringrequired

"inbound" or "outbound"

protocolstringrequired

Protocol: "tcp" or "udp"

target_servicestring

Target service name (inbound)

target_portint

Target port (inbound)

source_cidrsstring[]

Allowed source IPs (inbound)

destination_cidrsstring[]

Allowed destination IPs (outbound)

destination_portint

Destination port (outbound)

ttl_hoursint

Auto-expire after N hours

descriptionstring

Free-text description of the rule

Errors

• 400 Invalid CIDR format, CIDR too wide, or too many CIDRs
• 409 NodePort pool exhausted (inbound)
• 422 Rule limit reached, or egress_mode must be "restricted" for outbound rules

Returns 201. `direction` and `protocol` are required: `inbound` or `outbound`, `tcp` or `udp`. Inbound TCP rules get a port from the platform pool in `allocated_port`; when the pool is empty you get 409 `PORT_POOL_EXHAUSTED`. Outbound rules only work on a tenant with `egress_mode: "restricted"`, otherwise 422 `EGRESS_MODE_REQUIRED`. Each one is folded into a single network policy covering every active outbound rule. `ttl_hours` sets an expiry, after which the rule is cleaned up automatically; leave it out to use the platform default. CIDRs are validated on the way in: 400 with `INVALID_CIDR`, `CIDR_TOO_WIDE` (`/0` and `/1` are blocked), or `TOO_MANY_CIDRS`. Past your rule limit you get 422 `RULE_LIMIT_REACHED`.

Network Rules

Get Network Rule

Get details for one network rule.

A rule belonging to another tenant returns 404 rather than 403.

Network Rules

Delete Network Rule

Delete a network rule. Inbound rules release the allocated port.

Deleting an outbound rule rebuilds the egress policy from the rules that remain; removing the last one drops the policy entirely and the tenant falls back to whatever its `egress_mode` allows.

Real-Time

Events (SSE)

Subscribe to deployment events over Server-Sent Events (SSE).

Three event names come down the wire: `connected` once on open, `deployment` for every pipeline update, and `ping` every 15 seconds to hold the connection alive. On connect, the events already recorded for the tenant's latest deployment are replayed first, so a client that joins late still sees the full picture. Deployment stages run `validate` → `provision` → `database` → `build` → `arch_check` → `deploy` → `route` → `health_check` → `ready`, with `progress` climbing from 0 to 100. Deletions emit `deleting` and `deleted`. A failure ends the stream on the stage that broke. Read `error_stage` from the deployment for the detail.

Real-Time

Container Logs

Stream container logs for a tenant.

Parameters

linesintdefault 200

Number of log lines to return

followbooleandefault false

Stream logs as they arrive

`lines` defaults to 100 and caps at 5000. `follow=true` holds the connection open and streams new output, up to ten minutes. This reads the tenant's primary workload. For a specific service in a multi-service tenant, use `GET /tenants/{id}/services/{serviceName}/logs`. With no running pods you get 404.

Templates

List Templates

List available application templates for quick-start tenant creation.

Public: no authentication needed, limited to 60 requests per minute per IP. Narrow the list with a `category` query parameter.

Templates

Get Template

Get details for one template, by ID or slug.

Public, same as the list endpoint. The path segment is matched against the template ID first and then its slug, so `/templates/nextjs-postgres` works as well as `/templates/tmpl_nextjs_postgres`. Image-based templates carry an `image` instead of a `starter_repo`.

Templates

List Runtime Versions

List the runtime versions the platform can build against.

The set is platform configuration, so it changes as runtimes are added or retired, so read it rather than hardcoding a list. Use these values for `runtime_version` when creating a tenant or a service.

GitHub App

Get GitHub Installation

Get the GitHub App installation status for the authenticated provider.

Always 200. Check `connected` rather than the status code. When nothing is installed, `install_url` is where you send the user to install the app. `repository_selection` is `all` or `selected`, and a suspended installation carries `suspended_at`.

GitHub App

Register GitHub Installation

Register a GitHub App installation for the provider. Called after GitHub redirects back from the install flow.

Parameters

installation_idintrequired

GitHub App installation ID from the OAuth callback

Returns 200. The installation is verified against GitHub before anything is written, and the account metadata in the response comes from GitHub rather than the request, and an ID GitHub does not recognise returns 400. Calling it again for the same provider updates the existing record instead of creating a second one.

GitHub App

Delete GitHub Installation

Remove the GitHub App installation link from the provider account.

This only unlinks the installation on the Staxa side. The app stays installed on GitHub until it is removed there too, so a later `POST /github/installation` can re-link it.

GitHub App

List GitHub Repos

List repositories accessible through the GitHub App installation.

Which repositories appear depends on what the installation was granted: everything, or just the ones the user picked. With no installation registered you get 400.

GitHub App

List GitHub Branches

List branches for one repository.

The repository has to be one the installation can reach, otherwise the call fails. With no installation registered you get 400.

GitHub App

Analyze Repository

Inspect a repository and detect its runtime, framework, and how to run it.

Takes an optional `branch`, defaulting to `main`. The repository tree and its dependency manifests are read through the GitHub App installation; nothing is cloned and nothing is written. When a Dockerfile is present, its base image decides `detected_runtime` and `detected_version`; otherwise both are inferred from the framework. `has_dockerfile: false` means Staxa will generate one for you at build time. Use the result to prefill a create-tenant call: `framework`, `runtime_version`, and `detected_port` map onto `framework`, `runtime_version`, and `app_port`. With no installation registered you get 400.

Registry Credentials

List Registries

List saved container registry credentials.

Credentials themselves are never returned by any endpoint. They are encrypted at rest and only decrypted when Staxa talks to the registry. `status` is `active` or `error`; when it is `error`, `last_error` carries the reason from the last attempt.

Registry Credentials

Create Registry Credential

Save credentials for a private container registry.

Returns 201. `registry_type` must be `dockerhub`, `ghcr`, `ecr`, or `gcr`, and the shape of `credentials` follows from it. `registry_url` defaults per type (`https://index.docker.io/v1/`, `https://ghcr.io`, `https://gcr.io`) but is required for ECR, since the URL carries your account and region. Credentials are checked against the registry before they are stored, so a bad secret returns 422 `REGISTRY_VERIFICATION_FAILED` and nothing is saved. That is also why the credential comes back already `active`. Past your credential limit you get 422 `REGISTRY_LIMIT_REACHED`. `namespace` scopes repository listings to one organisation or project.

Registry Credentials

Get Registry Credential

Get details for a saved registry credential. The credentials themselves are never returned.

A credential belonging to another provider returns 404 rather than 403.

Registry Credentials

Update Registry Credential

Rename a registry credential or rotate its secret.

Both fields are optional. New credentials are verified before they replace the old ones. If verification fails you get 422 and the stored credential is left alone, so a rotation can never lock you out by half-applying. `registry_type` and `registry_url` are fixed at creation; to change either, create a new credential.

Registry Credentials

Delete Registry Credential

Delete a saved registry credential.

Deployments that pull images with this credential will start failing on their next build, so repoint them first.

Registry Credentials

Verify Registry Credential

Re-test that the saved credentials can still authenticate with the registry.

On success the credential comes back with `status: "active"` and a fresh `last_verified`. On failure you get 422 `REGISTRY_VERIFICATION_FAILED`, and the credential is marked `error` with the reason stored in `last_error`. It's worth calling after a token rotation on the registry side.

Registry Credentials

List Registry Repos

List repositories available in the registry.

Parameters

qstring

Search query to filter repos

limitintdefault 25

Maximum results to return

Takes `q` to filter by name and `limit` (1–100, default 25). Results are scoped to the credential's `namespace` where the registry supports it.

Registry Credentials

List Registry Tags

List tags for one repository in the registry.

Repository paths may contain slashes, as in `library/nginx`. The whole path goes between `/repos/` and `/tags`, and wildcard matching handles it. Takes `limit` (1–100, default 25). Which fields are populated depends on the registry; some return a digest and size, others only the tag name.