App

Use these endpoints to manage App operations on a Crate Operator host. The reference below includes request attributes, response shapes, and executable request examples.

The App object

Required attributes

app_id integer<int32>

asset_url string

callback_url string<uri>

deployment_id integer<int32>

deployment_strategy DeploymentStrategy

Deployment strategy for the app.

immediatebluegreencanary

domain string

env_vars map<string, string>

environment_id integer<int32>

slots map<string, InstancePort>

target_version string

team_id string

Optional attributes

health_check_path string | null

The App object JSON

{
  "app_id": 1,
  "asset_url": "string",
  "callback_url": "https://example.com/callback",
  "deployment_id": 1,
  "deployment_strategy": "immediate",
  "domain": "string",
  "env_vars": {
    "key": "string"
  },
  "environment_id": 1,
  "health_check_path": null,
  "slots": {
    "key": {
      "application_port": 1,
      "host_port": 1
    }
  },
  "target_version": "string",
  "team_id": "string"
}

POST /v1/app/instance/binary/deploy

Deploy or create app via instance model

Platform sends instance IDs (persistent DB keys) and port configs. The operator inspects local state to decide create vs update, then executes and returns instance state and traffic allocations.

Request attributes

Required attributes

app_id integer<int32>

asset_url string

callback_url string<uri>

deployment_id integer<int32>

deployment_strategy DeploymentStrategy

Deployment strategy for the app.

immediatebluegreencanary

domain string

env_vars map<string, string>

environment_id integer<int32>

slots map<string, InstancePort>

target_version string

team_id string

Optional attributes

health_check_path string | null

Responses

202 Accepted

400 Bad Request

500 Server Error

Request cURL

POST /v1/app/instance/binary/deploy

curl --request POST 'http://localhost:8080/v1/app/instance/binary/deploy' \
  --header 'X-API-Key: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "app_id": 1,
  "asset_url": "string",
  "callback_url": "https://example.com/callback",
  "deployment_id": 1,
  "deployment_strategy": "immediate",
  "domain": "string",
  "env_vars": {
    "key": "string"
  },
  "environment_id": 1,
  "health_check_path": null,
  "slots": {
    "key": {
      "application_port": 1,
      "host_port": 1
    }
  },
  "target_version": "string",
  "team_id": "string"
}'

Response JSON

{
  "current_step": "accepted",
  "deployment_id": 1,
  "events": [
    {
      "id": "string",
      "message": "string",
      "occurred_at": "2026-06-19T12:00:00Z",
      "step": "string"
    }
  ],
  "instances": {
    "key": {
      "ports": {
        "application_port": 1,
        "host_port": 1
      },
      "slot": {
        "label": "string"
      },
      "state": "pending",
      "traffic_allocation": 1
    }
  },
  "message": "string",
  "status": "string"
}

POST /v1/app/instance/docker/deploy

Deploy or create docker app via instance model

Platform sends instance IDs and port configs along with docker image info. The operator inspects local state to decide create vs update, then executes and returns instance state and traffic allocations.

Request attributes

Required attributes

app_id integer<int32>

callback_url string<uri>

deployment_id integer<int32>

deployment_strategy DeploymentStrategy

Deployment strategy for the app.

immediatebluegreencanary

domain string

env_vars map<string, string>

environment_id integer<int32>

image string

Docker image name (e.g. `registry.example.com/myapp`).

image_tag string

Docker image tag (e.g. `v1.2.3`).

slots map<string, InstancePort>

target_version string

team_id string

Optional attributes

docker_command array<string>

health_check_path string | null

Optional HTTP path used for readiness checks (for example `/healthz`).

registry_credentials DockerRegistryCredentials

volumes array<string>

Responses

202 Accepted

400 Bad Request

500 Server Error

Request cURL

POST /v1/app/instance/docker/deploy

curl --request POST 'http://localhost:8080/v1/app/instance/docker/deploy' \
  --header 'X-API-Key: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "app_id": 1,
  "callback_url": "https://example.com/callback",
  "deployment_id": 1,
  "deployment_strategy": "immediate",
  "docker_command": null,
  "domain": "string",
  "env_vars": {
    "key": "string"
  },
  "environment_id": 1,
  "health_check_path": null,
  "image": "string",
  "image_tag": "string",
  "registry_credentials": null,
  "slots": {
    "key": {
      "application_port": 1,
      "host_port": 1
    }
  },
  "target_version": "string",
  "team_id": "string",
  "volumes": null
}'

Response JSON

{
  "current_step": "accepted",
  "deployment_id": 1,
  "events": [
    {
      "id": "string",
      "message": "string",
      "occurred_at": "2026-06-19T12:00:00Z",
      "step": "string"
    }
  ],
  "instances": {
    "key": {
      "ports": {
        "application_port": 1,
        "host_port": 1
      },
      "slot": {
        "label": "string"
      },
      "state": "pending",
      "traffic_allocation": 1
    }
  },
  "message": "string",
  "status": "string"
}

POST /v1/app/binary/deploy

Deploy or create binary app

Creates the app if it does not yet exist on this host, otherwise performs a rolling deploy. The operator inspects local app state (app directory and systemd units) to decide.

Request attributes

Required attributes

app_id integer<int32>

asset_url string

callback_url string<uri>

deployment_id integer<int32>

deployment_strategy DeploymentStrategy

Deployment strategy for the app.

immediatebluegreencanary

domain string

env_vars map<string, string>

environment_id integer<int32>

instances map<string, BinaryAppInstance>

team_id string

Optional attributes

health_check_path string | null

Optional HTTP path used for readiness checks (for example `/healthz`).

Responses

202 Accepted

400 Bad Request

500 Server Error

Request cURL

POST /v1/app/binary/deploy

curl --request POST 'http://localhost:8080/v1/app/binary/deploy' \
  --header 'X-API-Key: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "app_id": 1,
  "asset_url": "string",
  "callback_url": "https://example.com/callback",
  "deployment_id": 1,
  "deployment_strategy": "immediate",
  "domain": "string",
  "env_vars": {
    "key": "string"
  },
  "environment_id": 1,
  "health_check_path": null,
  "instances": {
    "key": {
      "application_port": 1,
      "host_port": 1,
      "instance": "primary"
    }
  },
  "team_id": "string"
}'

Response JSON

{
  "deployment_id": 1,
  "message": "string",
  "status": "string"
}

GET /v1/app/deploy/{deployment_id}/status

Get operator update status

Parameters

deployment_id string path required

Responses

200 App Binary Deployment Status

404 Not Found

Request cURL

GET /v1/app/deploy/{deployment_id}/status

curl --request GET 'http://localhost:8080/v1/app/deploy/<deployment_id>/status' \
  --header 'X-API-Key: <token>'

Response JSON

{
  "current_step": "string",
  "deployment_id": "string",
  "error": null,
  "events": [
    {
      "id": "string",
      "message": "string",
      "occurred_at": "2026-06-19T12:00:00Z",
      "step": "string"
    }
  ],
  "failed": true,
  "finished_at": "2026-06-19T12:00:00Z",
  "started_at": "2026-06-19T12:00:00Z",
  "state": "queued",
  "target_version": "string",
  "topology": [
    {
      "id": "string",
      "role": "primary",
      "state": "pending",
      "version": "string"
    }
  ]
}

GET /v1/app/instance/deploy/{deployment_id}/status

Get instance deployment status

Parameters

deployment_id integer<int32> path required

Responses

200 Instance Deployment Status

404 Not Found

Request cURL

GET /v1/app/instance/deploy/{deployment_id}/status

curl --request GET 'http://localhost:8080/v1/app/instance/deploy/1/status' \
  --header 'X-API-Key: <token>'

Response JSON

{
  "current_step": "string",
  "deployment_id": 1,
  "error": null,
  "events": [
    {
      "id": "string",
      "message": "string",
      "occurred_at": "2026-06-19T12:00:00Z",
      "step": "string"
    }
  ],
  "failed": true,
  "finished_at": "2026-06-19T12:00:00Z",
  "instances": {
    "key": {
      "ports": {
        "application_port": 1,
        "host_port": 1
      },
      "slot": {
        "label": "string"
      },
      "state": "pending",
      "traffic_allocation": 1
    }
  },
  "started_at": "2026-06-19T12:00:00Z",
  "state": "queued",
  "target_version": "string"
}

POST /v1/app/docker/deploy

Deploy or create docker app

Creates the app if it does not yet exist on this host, otherwise performs a rolling deploy. The operator inspects local app state (app directory and systemd units) to decide.

Request attributes

Required attributes

app_id integer<int32>

callback_url string<uri>

deployment_id integer<int32>

deployment_strategy DeploymentStrategy

Deployment strategy for the app.

immediatebluegreencanary

domain string

environment_id integer<int32>

image string

Docker image name (e.g. `registry.example.com/myapp`).

image_tag string

Docker image tag (e.g. `v1.2.3`).

instances map<string, BinaryAppInstance>

team_id string

Optional attributes

docker_command array<string>

env_vars map<string, string>

health_check_path string | null

Optional HTTP path used for readiness checks (for example `/healthz`).

registry_credentials DockerRegistryCredentials

volumes array<string>

Responses

202 Accepted

400 Bad Request

500 Server Error

Request cURL

POST /v1/app/docker/deploy

curl --request POST 'http://localhost:8080/v1/app/docker/deploy' \
  --header 'X-API-Key: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "app_id": 1,
  "callback_url": "https://example.com/callback",
  "deployment_id": 1,
  "deployment_strategy": "immediate",
  "docker_command": null,
  "domain": "string",
  "env_vars": null,
  "environment_id": 1,
  "health_check_path": null,
  "image": "string",
  "image_tag": "string",
  "instances": {
    "key": {
      "application_port": 1,
      "host_port": 1,
      "instance": "primary"
    }
  },
  "registry_credentials": null,
  "team_id": "string",
  "volumes": null
}'

Response JSON

{
  "deployment_id": 1,
  "message": "string",
  "status": "string"
}

POST /v1/app/delete

Delete app (remove service and files)

Asynchronously deletes app instances by stopping and removing systemd units, app files, config, and the Caddy route. Accepts multiple instance IDs (e.g. both blue/green slots) for full cleanup.

Request attributes

Required attributes

app_id integer<int32>

callback_url string<uri>

domain string

environment_id integer<int32>

instance_ids array<string>

team_id string

Optional attributes

deployment_id integer<int32> | null

Responses

202 Accepted — deletion is in progress

400 Bad Request

500 Server Error

Request cURL

POST /v1/app/delete

curl --request POST 'http://localhost:8080/v1/app/delete' \
  --header 'X-API-Key: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "app_id": 1,
  "callback_url": "https://example.com/callback",
  "deployment_id": null,
  "domain": "string",
  "environment_id": 1,
  "instance_ids": [
    "string"
  ],
  "team_id": "string"
}'

Response JSON

{
  "message": "string",
  "status": "string"
}

POST /v1/app/domain/update

Update app domain route in Caddy

Request attributes

Required attributes

app_id integer<int32>

environment_id integer<int32>

new_domain string

old_domain string

server_id string

team_id string

Responses

200 OK

400 Bad Request

404 Route not found

409 Target domain already exists

503 Caddy unavailable

Request cURL

POST /v1/app/domain/update

curl --request POST 'http://localhost:8080/v1/app/domain/update' \
  --header 'X-API-Key: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "app_id": 1,
  "environment_id": 1,
  "new_domain": "string",
  "old_domain": "string",
  "server_id": "string",
  "team_id": "string"
}'

Response JSON

{
  "message": "string",
  "route_id": "string"
}

POST /v1/app/start

Start app service

Starts the app service instance by instance_id.

Request attributes

Required attributes

app_id integer<int32>

callback_url string<uri>

domain string

environment_id integer<int32>

instance_id string

team_id string

Responses

202 Accepted

400 Bad Request

500 Server Error

Request cURL

POST /v1/app/start

curl --request POST 'http://localhost:8080/v1/app/start' \
  --header 'X-API-Key: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "app_id": 1,
  "callback_url": "https://example.com/callback",
  "domain": "string",
  "environment_id": 1,
  "instance_id": "string",
  "team_id": "string"
}'

Response JSON

{
  "message": "string",
  "status": "string"
}

POST /v1/app/stop

Stop app service

Stops the app service instance by instance_id.

Request attributes

Required attributes

app_id integer<int32>

callback_url string<uri>

domain string

environment_id integer<int32>

instance_id string

team_id string

Responses

202 Accepted

400 Bad Request

500 Server Error

Request cURL

POST /v1/app/stop

curl --request POST 'http://localhost:8080/v1/app/stop' \
  --header 'X-API-Key: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "app_id": 1,
  "callback_url": "https://example.com/callback",
  "domain": "string",
  "environment_id": 1,
  "instance_id": "string",
  "team_id": "string"
}'

Response JSON

{
  "message": "string",
  "status": "string"
}

POST /v1/app/restart

Restart app service

Restarts the app service instance by instance_id.

Request attributes

Required attributes

app_id integer<int32>

callback_url string<uri>

domain string

environment_id integer<int32>

instance_id string

team_id string

Responses

202 Accepted

400 Bad Request

500 Server Error

Request cURL

POST /v1/app/restart

curl --request POST 'http://localhost:8080/v1/app/restart' \
  --header 'X-API-Key: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "app_id": 1,
  "callback_url": "https://example.com/callback",
  "domain": "string",
  "environment_id": 1,
  "instance_id": "string",
  "team_id": "string"
}'

Response JSON

{
  "message": "string",
  "status": "string"
}