Skip to content

Create App Deployment

POST
/apps/{app_id}/deployments

Queue a deployment from a pinned source ref.

Returns queued. Nothing builds yet — the provisioner (M6-8) is what moves it to building. Recording the intent before any infrastructure exists is deliberate: it makes the control plane the source of truth for what SHOULD be running, which is what a reconciler needs to exist against.

Authorizations

Parameters

Path Parameters

app_id
required
string

Header Parameters

X-Org-Id
Any of:
string

Request Body required

Start a deployment from a pinned source ref.

source_ref is a COMMIT-ish, not a branch name. A branch moves, so a deployment recorded against one cannot answer “what is running right now” a week later — which is the question a rollback has to answer.

object
schema_version_id
Any of:
string
source_ref
required

Immutable source reference (commit SHA). Branches move; deployments must not.

string
>= 1 characters <= 255 characters

Responses

201

Successful Response

object
data
required
object
app_id
required
string
build_finished_at
Any of:
string format: date-time
build_seconds
Any of:
number
build_started_at
Any of:
string format: date-time
created_at
Any of:
string format: date-time
deployed_at
Any of:
string format: date-time
deployment_id
required
string
image_digest
Any of:
string
last_error_sanitized
Any of:
string
schema_version_id
Any of:
string
source_ref
Any of:
string
status
required
string
pagination
Any of:
object
has_next
required

Whether there are more pages

boolean
limit
required

Items per page

integer
next_cursor
Any of:
string
page
required

Current page number (1-indexed)

integer
total
required

Total number of items

integer

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string