Deploy a new app from a container image, or from a Git repository. A tag is resolved to a digest at its registry; a Git app deploys with its first build.

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", "git": { "installationId": 1, "connection": "example", "repository": "acme/shop", "branch": "main", "strategy": "auto", "context": "apps/web", "dockerfile": "example", "imageRepository": "registry.example.com/acme/shop" }, "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

The image to run; give this or git.

string | null

Example

ghcr.io/acme/api:1.4.2

git

One of:

null

null

object

Build the app from a Git repository instead (M3); its first build deploys it.

object

installationId

A GitHub App installation linked to this organization. Required unless connection is given.

integer format: int64

connection

A Git connection of this organization (its id), instead of an installation: GitLab, Gitea or a GitHub token.

string

repository

required

string

Example

acme/shop

branch

required

string

Example

main

strategy

string

Allowed values: auto dockerfile railpack

context

Build context inside the repository; the root when empty.

string

Example

apps/web

dockerfile

Dockerfile relative to the context; Dockerfile when unset.

string | null

imageRepository

required

Where builds push, without tag or digest.

string

Example

registry.example.com/acme/shop

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

exposure

One of:

null

null

object

Whether the app can be reached through the gateway, apart from whether it runs (null while it has no route).

object

routed

The gateway accepted the route and resolved its references; null until a gateway controller answered.

boolean | null

message

string | null

hosts

required

Array<object>

One hostname of an app.

object

host

required

string

tls

required

auto (certificate from the cluster issuer), secret (the app’s own certificate) or none (plain HTTP).

string

certificate_ready

For auto hosts with a certificate of their own: whether it is issued.

boolean | null

certificate_message

string | null

paused

Why delivery is paused, while it is: new runs wait.

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

The image’s registry cannot be reached

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"
}