Deploy a new app from a container image.

POST

/api/v1/projects/{project}/environments/{environment}/apps

curl --request POST \
  --url https://example.com/api/v1/projects/example/environments/example/apps \
  --header 'Content-Type: application/json' \
  --data '{ "name": "api", "image": "ghcr.io/acme/api:1.4.2", "port": 8080, "command": [ "example" ], "replicas": 1, "max_replicas": 1, "size": "small", "env": [ { "name": "LOG_LEVEL", "value": "example", "secret": { "name": "example", "key": "example" } } ], "domains": [ "example" ], "health_check_path": "/healthz", "schedule": "0 3 * * *", "time_zone": "Europe/Berlin", "protocol": "http", "volumes": [ { "name": "data", "mount_path": "/data", "size": "5Gi" } ], "fs_group": 1000 }'

Parameters

Path Parameters

project

required

string

Project name

environment

required

string

Environment short name

Request Body^required

Media typeapplication/json

object

name

required

string

Example

api

image

required

string

Example

ghcr.io/acme/api:1.4.2

port

Port the process listens on; omit for workers and scheduled jobs.

integer | null format: int32

Example

8080

command

Array<string>

replicas

integer format: int32

max_replicas

CPU autoscaling up to this many replicas when greater than replicas.

integer | null format: int32

size

Size preset: nano, small, medium, large (or custom).

string

Example

small

env

Array<object>

Environment variable: a plain value or a secret reference.

object

name

required

string

Example

LOG_LEVEL

value

string | null

secret

One of:

null

null

object

object

name

required

string

key

required

string

domains

Array<string>

health_check_path

string | null

Example

/healthz

schedule

Cron expression: the app runs as a scheduled job (no port).

string | null

Example

0 3 * * *

time_zone

IANA time zone for schedule (default UTC).

string | null

Example

Europe/Berlin

protocol

string

Allowed values: http tcp

volumes

Array<object>

Persistent volume (kept when the app is deleted, unless requested).

object

name

required

string

Example

data

mount_path

required

string

Example

/data

size

Capacity such as 5Gi. Can grow, never shrink.

string

Example

5Gi

fs_group

Group id owning the volumes, for images running as a non-root user.

integer | null format: int64

Example

1000

Responses

201

Media typeapplication/json

object

name

required

string

project

required

string

environment

required

Environment short name.

string

namespace

required

string

image

string | null

git_repo

string | null

url

string | null

ready

required

boolean

reason

Available, Progressing, RolloutFailed, Scheduled, AwaitingBuild, …

string | null

message

string | null

processes

required

Array<object>

object

name

required

string

command

required

Array<string>

port

integer | null format: int32

size

required

string

min_replicas

required

integer format: int32

max_replicas

required

integer format: int32

schedule

Cron expression of scheduled processes.

string | null

protocol

required

http or tcp.

string

env

required

Values are only included in the app detail, for callers allowed to read secrets.

Array<object>

Environment variable: a plain value or a secret reference.

object

name

required

string

value

string | null

secret

One of:

null

null

object

object

name

required

string

key

required

string

domains

required

Array<string>

volumes

required

Array<object>

Persistent volume (kept when the app is deleted, unless requested).

object

name

required

string

mount_path

required

string

size

Capacity such as 5Gi. Can grow, never shrink.

string

created_at

string | null

Example

{
  "env": [
    {
      "name": "LOG_LEVEL"
    }
  ],
  "volumes": [
    {
      "name": "data",
      "mount_path": "/data",
      "size": "5Gi"
    }
  ]
}

403

Media typeapplication/json

Problem Details body.

object

code

required

Stable machine-readable code, e.g. forbidden.

string

title

required

Short human readable title.

string

status

required

HTTP status.

integer format: int32

detail

Details, if safe to expose.

string | null

Example

{
  "code": "forbidden"
}

409

Media typeapplication/json

Problem Details body.

object

code

required

Stable machine-readable code, e.g. forbidden.

string

title

required

Short human readable title.

string

status

required

HTTP status.

integer format: int32

detail

Details, if safe to expose.

string | null

Example

{
  "code": "forbidden"
}

422

Media typeapplication/json

Problem Details body.

object

code

required

Stable machine-readable code, e.g. forbidden.

string

title

required

Short human readable title.

string

status

required

HTTP status.

integer format: int32

detail

Details, if safe to expose.

string | null

Example

{
  "code": "forbidden"
}

503

Media typeapplication/json

Problem Details body.

object

code

required

Stable machine-readable code, e.g. forbidden.

string

title

required

Short human readable title.

string

status

required

HTTP status.

integer format: int32

detail

Details, if safe to expose.

string | null

Example

{
  "code": "forbidden"
}