Deployments

Deployments are running instances of templates. Each deployment has a unique name, runs in a Kubernetes namespace, and is managed by the UserDeployment operator.

Deployment Operations

List Deployments

GET /api/deployments

Returns all deployments for the authenticated user. Results are filtered by the current team context if a team is selected. Authentication: Required (session or API key with deployments:read scope) Query Parameters:

team_id

string

Filter by team ID

Response:

name

string

Unique deployment name

status

string

Deployment status: Pending, Provisioning, Ready, Error, Deleting

template

string

Template name used for this deployment

visibility

string

Visibility: public or internal

ingresses

array

Array of ingress endpoints

lastError

string

Error message if status is Error

canDelete

boolean

Whether the deployment can be deleted

Example:

curl -X GET "https://your-domain.com/api/deployments" \
  -H "Authorization: Bearer YOUR_API_KEY"

[
  {
    "name": "abc123xyz7",
    "status": "Ready",
    "template": "nginx",
    "visibility": "public",
    "ingresses": [
      {
        "id": "nginx",
        "name": "nginx",
        "host": "abc123xyz7.yourdomain.com",
        "url": "https://abc123xyz7.yourdomain.com"
      }
    ],
    "canDelete": true
  }
]

Create Deployment

POST /api/deployments

Create a new deployment from a template. The deployment is provisioned via the UserDeployment Kubernetes operator. Authentication: Required (deployments:write scope) Request Body:

template

string

required

Template name to deploy (e.g., “nginx”, “postgres”)

envVars

object

Environment variables as key-value pairs

visibility

string

Deployment visibility: public or internal (default: public)

Response: 201 Created

name

string

Generated deployment name

status

string

Initial status (typically Pending)

template

string

Template name

visibility

string

Deployment visibility

Example:

curl -X POST "https://your-domain.com/api/deployments" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "nginx",
    "envVars": {
      "PORT": "8080"
    },
    "visibility": "public"
  }'

Tier Limits: Deployment creation is subject to tier limits when billing is enabled:

Free: 1 deployment
Business: 10 deployments
Enterprise: Unlimited

If the limit is reached, the API returns 403 Forbidden.

Get Deployment Status

GET /api/deployments/status?name={deploymentName}

Get the current status of a deployment, including ingress endpoints if ready. Query Parameters:

name

string

required

Deployment name

Response:

status

string

Current status

deploymentReady

boolean

Whether the deployment is ready to receive traffic

allowDelete

boolean

Whether the deployment can be deleted

allowRequest

boolean

Whether a new deployment request is allowed

ingresses

array

Array of ingress endpoints (only when ready)

statusMessage

string

Additional status information or error message

Example:

curl -X GET "https://your-domain.com/api/deployments/status?name=abc123xyz7" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "status": "Ready",
  "deploymentReady": true,
  "allowDelete": true,
  "allowRequest": false,
  "ingresses": [
    {
      "id": "nginx",
      "name": "nginx",
      "host": "abc123xyz7.yourdomain.com",
      "url": "https://abc123xyz7.yourdomain.com"
    }
  ]
}

Delete Deployment

POST /api/deployments/delete

Delete a deployment. This marks the UserDeployment CR’s desiredState as deleted, and the operator handles cleanup via finalizers. Authentication: Required (deployments:write scope) Request Body:

deployment_name

string

required

Name of the deployment to delete

Response: Redirects to deployments page (for form POST) or returns JSON success Example:

curl -X POST "https://your-domain.com/api/deployments/delete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deployment_name": "abc123xyz7"}'

Notes:

The API verifies deployment ownership before deletion
Deployment secrets are automatically cleaned up
Kubernetes resources are removed by the operator
Deletion is recorded in billing events

Restart Deployment

POST /api/deployments/restart

Restart all pods in a deployment by adding a restart annotation. Request Body:

deployment_name

string

required

Name of the deployment to restart

Response: 200 OK Example:

curl -X POST "https://your-domain.com/api/deployments/restart" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"deployment_name": "abc123xyz7"}'

Deploy Raw Image

POST /api/deployments/deploy-image

Deploy a raw container image without requiring a pre-existing template. Useful for custom images or CI/CD pipelines. Request Body:

image

string

required

Container image (e.g., nginx:latest, myregistry.com/app:v1.2.3)

name

string

Custom deployment name (auto-generated if not provided)

containerPort

integer

Port the container listens on (default: 8080)

envVars

object

Environment variables as key-value pairs

visibility

string

Visibility: public or internal (default: public)

Response: 201 Created Example:

curl -X POST "https://your-domain.com/api/deployments/deploy-image" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "myapp:v1.0.0",
    "containerPort": 3000,
    "envVars": {
      "NODE_ENV": "production",
      "PORT": "3000"
    }
  }'

Get Deployment Configuration

GET /api/deployments/config?name={deploymentName}

Retrieve the configuration for a deployment, including environment variables. Query Parameters:

name

string

required

Deployment name

Response:

configData

object

Key-value pairs of environment variables

Update Deployment Configuration

PUT /api/deployments/config

Update environment variables for a deployment. This triggers a pod restart. Request Body:

deployment_name

string

required

Deployment name

configData

object

required

New environment variables (replaces existing)

Response: 200 OK Example:

curl -X PUT "https://your-domain.com/api/deployments/config" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_name": "abc123xyz7",
    "configData": {
      "PORT": "8080",
      "DEBUG": "true"
    }
  }'

Deployment Logs

Get Deployment Logs

GET /api/deployments/{name}/logs

Retrieve container logs from a deployment. Path Parameters:

name

string

required

Deployment name

Query Parameters:

service

string

Service name for multi-service deployments (default: first service)

tail

integer

Number of recent lines to return (default: 100)

boolean

Stream logs in real-time (default: false)

Response:

logs

string

Container logs

Example:

curl -X GET "https://your-domain.com/api/deployments/abc123xyz7/logs?tail=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Stream Deployment Logs

GET /api/deployments/{name}/logs/stream

Stream container logs in real-time using Server-Sent Events (SSE). Path Parameters:

name

string

required

Deployment name

Query Parameters:

service

string

Service name for multi-service deployments

Response: text/event-stream Example:

curl -X GET "https://your-domain.com/api/deployments/abc123xyz7/logs/stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream"

Deployment Metrics

Get Deployment Metrics

GET /api/deployments/{name}/metrics

Retrieve CPU and memory metrics for a deployment. Path Parameters:

name

string

required

Deployment name

Query Parameters:

service

string

Service name for multi-service deployments

Response:

cpuUsage

string

CPU usage in millicores (e.g., “150m”)

memoryUsage

string

Memory usage in bytes (e.g., “256Mi”)

timestamp

string

ISO 8601 timestamp of measurement

Example:

curl -X GET "https://your-domain.com/api/deployments/abc123xyz7/metrics" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "cpuUsage": "150m",
  "memoryUsage": "256Mi",
  "timestamp": "2024-03-05T10:30:00Z"
}

Deployment History

Get Deployment History

GET /api/deployments/{name}/history

Retrieve deployment revision history (configuration changes, restarts, etc.). Path Parameters:

name

string

required

Deployment name

Response:

revisions

array

Array of revision objects

Example:

curl -X GET "https://your-domain.com/api/deployments/abc123xyz7/history" \
  -H "Authorization: Bearer YOUR_API_KEY"

Auto-Update Configuration

Get Auto-Update Settings

GET /api/deployments/auto-update?name={deploymentName}

Retrieve auto-update configuration for a deployment. Response:

enabled

boolean

Whether auto-update is enabled

strategy

string

Update strategy (e.g., “rolling”, “recreate”)

Update Auto-Update Settings

PUT /api/deployments/auto-update

Configure auto-update settings for a deployment. Request Body:

deployment_name

string

required

Deployment name

enabled

boolean

required

Enable or disable auto-updates

strategy

string

Update strategy: rolling or recreate

Response: 200 OK Example:

curl -X PUT "https://your-domain.com/api/deployments/auto-update" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_name": "abc123xyz7",
    "enabled": true,
    "strategy": "rolling"
  }'

Deployment Events

Get Deployment Events

GET /api/deployments/{name}/events

Retrieve Kubernetes events for a deployment (useful for debugging). Path Parameters:

name

string

required

Deployment name

Response:

events

array

Array of Kubernetes event objects

Example:

curl -X GET "https://your-domain.com/api/deployments/abc123xyz7/events" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Responses

All deployment endpoints may return the following errors:

error

string

Human-readable error message

Common Error Codes

400 Bad Request - Missing or invalid parameters
403 Forbidden - Deployment limit reached or ownership verification failed
404 Not Found - Deployment does not exist
409 Conflict - Deployment name already exists
500 Internal Server Error - Kubernetes API error or database failure
503 Service Unavailable - Operator not available

Getting Started

Core Concepts

Components

Deployment

API Reference

Deployment Operations

List Deployments

Create Deployment

Get Deployment Status

Delete Deployment

Restart Deployment

Deploy Raw Image

Get Deployment Configuration

Update Deployment Configuration

Deployment Logs

Get Deployment Logs

Stream Deployment Logs

Deployment Metrics

Get Deployment Metrics

Deployment History

Get Deployment History

Auto-Update Configuration

Get Auto-Update Settings

Update Auto-Update Settings

Deployment Events

Get Deployment Events

Error Responses

Common Error Codes

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Components

Deployment

API Reference

​Deployment Operations

​List Deployments

​Create Deployment

​Get Deployment Status

​Delete Deployment

​Restart Deployment

​Deploy Raw Image

​Get Deployment Configuration

​Update Deployment Configuration

​Deployment Logs

​Get Deployment Logs

​Stream Deployment Logs

​Deployment Metrics

​Get Deployment Metrics

​Deployment History

​Get Deployment History

​Auto-Update Configuration

​Get Auto-Update Settings

​Update Auto-Update Settings

​Deployment Events

​Get Deployment Events

​Error Responses

​Common Error Codes

Build docs developers (and LLMs) love

Deployment Operations

List Deployments

Create Deployment

Get Deployment Status

Delete Deployment

Restart Deployment

Deploy Raw Image

Get Deployment Configuration

Update Deployment Configuration

Deployment Logs

Get Deployment Logs

Stream Deployment Logs

Deployment Metrics

Get Deployment Metrics

Deployment History

Get Deployment History

Auto-Update Configuration

Get Auto-Update Settings

Update Auto-Update Settings

Deployment Events

Get Deployment Events

Error Responses

Common Error Codes