Client API: Apps

Name	In	Type	Required	Description
`status`	query	string or null	no
`limit`	query	integer	no	Default: `50`.
`offset`	query	integer	no	Default: `0`.

Responses

Section titled Create an app and, unless deploy is false, its first release

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Create an app and, unless deploy is false, its first release

POST /api/v1/client/apps

Create an app and, unless deploy is false, its first release. An app whose first release cannot start yet is still created, with the reason in deploy_error.

A web app needs no plan and no size: instance_size is optional and sets only the memory limit the app starts with. The app is billed by use from the moment it is created, on memory, CPU, requests, data out, builds and logs, by the account that owns it (an organization's owner for an organization's app). A prepaid account needs the $10 deposit that unlocks hourly billing before its first instance: without it the answer is 403 deposit_required with the minimum, and nothing is created. An account billed by invoice needs no deposit and gets the use on its monthly invoice. A size no product can carry is refused with 409 size_not_offered.

This route makes git and image apps. A static site has no instance, so it needs no deposit and bills only builds and logs past the amounts included each month. Order one with POST /api/v1/services/order and kind static.

Authentication: an access token, sent as Authorization: Bearer <token>.

Request body

application/json (required)

Field	Type	Required	Description
`name`	string	yes
`repo_url`	string or null	no
`repo_branch`	string or null	no
`repo_subdir`	string or null	no
`repo_token`	string or null	no	Write only; an empty string removes it
`image_ref`	string or null	no
`framework`	string or null	no
`install_command`	string or null	no
`build_command`	string or null	no
`start_command`	string or null	no
`dockerfile_path`	string or null	no
`port`	integer or null	no
`health_check_path`	string or null	no
`instance_size`	string or null	no	Optional. small (512 MB), medium (1 GB) or large (2 GB) sets the memory, CPU and disk limit the app starts with, and small applies when it is left out. There is no plan to pick: the bill follows what the app uses, not this size. An app billed by use keeps the size it started with, and another size answers 409
`regions`	array of string or null	no
`min_replicas`	integer or null	no
`max_replicas`	integer or null	no
`slug`	string or null	no	The name on the platform; derived from name when left out
`source_type`	string	no	git builds a repository and image runs a container image. This route makes web apps with an instance. A static site is ordered with POST /api/v1/services/order (kind static), not created here
`env`	array of EnvVarIn or null	no
`env[].key`	string	yes
`env[].value`	string or null	no	Left out: the saved value is kept
`env[].secret`	boolean or null	no	Redacted from build logs; new variables default to true
`env[].target`	string or null	no
`deploy`	boolean	no	Start the first release at once

Responses

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

Regions

Section titled Regions

GET /api/v1/client/apps/regions

What the create form offers: the regions that can run apps now, the instance sizes, the replica bounds and the owner's app limit.

Authentication: an access token, sent as Authorization: Bearer <token>.

Responses

Section titled Get one app with its domains, recent releases and live replicas

Status	Meaning
`200`	Success.

Get one app with its domains, recent releases and live replicas

GET /api/v1/client/apps/{app_uuid}

Get one app with its domains, recent releases and live replicas. deployments holds the five newest releases and deployments_total counts them all; replicas are those of the live release, failed ones left out. Another owner's app answers 404, as one that does not exist does.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`app_uuid`	path	string (uuid)	yes

Responses

Section titled Change an app's settings

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Change an app's settings

PATCH /api/v1/client/apps/{app_uuid}

Change an app's settings. redeploy_required and rebuild_required say whether running replicas pick the change up only with a new release or a new build. regions, min_replicas and max_replicas reach the live release at once, as its placements. On an app a service bills, another instance_size is refused with 409 plan_change_required: the size is the plan's, changed with POST /api/v1/services/{service_id}/change-plan.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`app_uuid`	path	string (uuid)	yes

Request body

application/json (required)

Field	Type	Required	Description
`name`	string or null	no
`repo_url`	string or null	no
`repo_branch`	string or null	no
`repo_subdir`	string or null	no
`repo_token`	string or null	no	Write only; an empty string removes it
`image_ref`	string or null	no
`framework`	string or null	no
`install_command`	string or null	no
`build_command`	string or null	no
`start_command`	string or null	no
`dockerfile_path`	string or null	no
`port`	integer or null	no
`health_check_path`	string or null	no
`instance_size`	string or null	no	Optional. small (512 MB), medium (1 GB) or large (2 GB) sets the memory, CPU and disk limit the app starts with, and small applies when it is left out. There is no plan to pick: the bill follows what the app uses, not this size. An app billed by use keeps the size it started with, and another size answers 409
`regions`	array of string or null	no
`min_replicas`	integer or null	no
`max_replicas`	integer or null	no

Responses

Section titled Delete app

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Delete app

DELETE /api/v1/client/apps/{app_uuid}

Delete the app: releases on their way are canceled, its routes and domains removed, its replicas drained and their servers removed, its environment and secrets erased. It cannot be undone.

An app a service bills is deleted by ending that service now, as a cancellation from the services page does: the answer has deleted false, ending true and the service, and the app goes when the service's terminate job runs. An app whose service is already ending answers 409 already_ending.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`app_uuid`	path	string (uuid)	yes
`confirm`	query	string	yes	The app's name on the platform, typed to confirm
`reason`	query	string or null	no

Responses

Section titled List an app's releases, newest first, a page at a time

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

List an app's releases, newest first, a page at a time

GET /api/v1/client/apps/{app_uuid}/deployments

List an app's releases, newest first, a page at a time. This API names a release deployment, and the deployments array holds them. limit takes 1 to 100 (20 when left out) and total counts every release. Each one carries its status, source, trigger, build and replica counts. trigger says what started it: push (a push to the connected branch), manual (Deploy a branch or an image, an upload, a promotion or a Redeploy), rebuild (Rebuild, or Pull again for an image), rollback or deploy_hook. is_current is true for the live release.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required	Description
`app_uuid`	path	string (uuid)	yes
`limit`	query	integer	no	Default: `20`.
`offset`	query	integer	no	Default: `0`.

Responses

Section titled Deploy a branch or an image, which starts a release

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Deploy a branch or an image, which starts a release

POST /api/v1/client/apps/{app_uuid}/deployments

Deploy a branch or an image, which starts a release. A git app builds git_ref, a branch, tag or commit (its branch when left out); an image app runs image_ref (its own when left out). A branch or commit for an image app, or an image for a git app, is refused with source_mismatch rather than ignored. The release has the trigger manual.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`app_uuid`	path	string (uuid)	yes

Request body

application/json (required)

Field	Type	Required	Description
`git_ref`	string or null	no	Branch, tag or commit; the app's branch when left out
`git_sha`	string or null	no
`image_ref`	string or null	no	An image app's reference; the app's when left out

Responses

Section titled Get one release of an app, with each of its replicas

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

Get one release of an app, with each of its replicas

GET /api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}

Get one release of an app, with each of its replicas. replica_list gives each replica's region, state, failed health checks in a row and last error. A release of another app answers 404.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`app_uuid`	path	string (uuid)	yes
`deployment_uuid`	path	string (uuid)	yes

Responses

Section titled Cancel a release that is still queued, building or deploying

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Cancel a release that is still queued, building or deploying

POST /api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}/cancel

Cancel a release that is still queued, building or deploying. Its build stops and its replicas are removed, and the live release goes on serving. A release that has finished answers 409.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`app_uuid`	path	string (uuid)	yes
`deployment_uuid`	path	string (uuid)	yes

Responses

Section titled The end of the release's build log (secrets redacted as it was written)

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

The end of the release's build log (secrets redacted as it was written)

GET /api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}/log

The end of the release's build log (secrets redacted as it was written). A release of an image has none.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`app_uuid`	path	string (uuid)	yes
`deployment_uuid`	path	string (uuid)	yes

Responses

Section titled Rollback app

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Rollback app

POST /api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}/rollback

Roll back: a new release of this earlier ready release's image; its replicas that still have servers are started again instead of placed. The new release has the trigger rollback.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`app_uuid`	path	string (uuid)	yes
`deployment_uuid`	path	string (uuid)	yes

Responses

Section titled List an app's domains: its platform name first, then its custom domains

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

List an app's domains: its platform name first, then its custom domains

GET /api/v1/client/apps/{app_uuid}/domains

List an app's domains: its platform name first, then its custom domains. Each says whether it is verified and whether its certificate is issued, and an unverified one carries the TXT record to publish in verification.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`app_uuid`	path	string (uuid)	yes

Responses

Section titled Add a custom domain

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Add a custom domain

POST /api/v1/client/apps/{app_uuid}/domains

Add a custom domain. It gets no route until the TXT record in verification is published and checked.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`app_uuid`	path	string (uuid)	yes

Request body

application/json (required)

Field	Type	Required
`hostname`	string	yes

Responses

Section titled Remove a custom domain from an app

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

Remove a custom domain from an app

DELETE /api/v1/client/apps/{app_uuid}/domains/{hostname}

Remove a custom domain from an app. The hostname stops reaching the app, and its route and certificate are deleted. The platform name cannot be removed (409 platform_domain), and a hostname the app does not have answers 404.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`app_uuid`	path	string (uuid)	yes
`hostname`	path	string	yes

Responses

Section titled Look for the domain's TXT record

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Look for the domain's TXT record

POST /api/v1/client/apps/{app_uuid}/domains/{hostname}/verify

Look for the domain's TXT record. Found: the domain is verified, its route is created and, once replicas serve it, its certificate ordered.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`app_uuid`	path	string (uuid)	yes
`hostname`	path	string	yes

Responses

Section titled List an app's environment variables without their values

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

List an app's environment variables without their values

GET /api/v1/client/apps/{app_uuid}/env

List an app's environment variables without their values. Each key comes with its target, whether it is secret and, for a value of eight characters or more, its last four as hint. readable is false when a saved value can no longer be read; set it again.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`app_uuid`	path	string (uuid)	yes

Responses

Section titled Set many variables; a variable given without value keeps its saved one

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Set many variables; a variable given without value keeps its saved one

PUT /api/v1/client/apps/{app_uuid}/env

Set many variables; a variable given without value keeps its saved one. With replace every variable not listed is deleted. Changes reach replicas with the next release.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`app_uuid`	path	string (uuid)	yes

Request body

application/json (required)

Field	Type	Required	Description
`vars`	array of EnvVarIn	yes
`vars[].key`	string	yes
`vars[].value`	string or null	no	Left out: the saved value is kept
`vars[].secret`	boolean or null	no	Redacted from build logs; new variables default to true
`vars[].target`	string or null	no
`replace`	boolean	no	Delete every variable not in vars

Responses

Section titled Set one environment variable, creating it when it is new

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Set one environment variable, creating it when it is new

PUT /api/v1/client/apps/{app_uuid}/env/{key}

Set one environment variable, creating it when it is new. A new variable needs a value and is secret unless secret is false; leave value out to keep the saved one while secret or target change. A key the platform sets itself, such as PORT or one starting CORITAN_, is refused with 422, except CORITAN_ORG_API_KEY, CORITAN_WEBHOOK_SECRET and CORITAN_MICROSOFT_ADS_FEED_URL, which your app reads at runtime. Replicas get the change with the next release.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`app_uuid`	path	string (uuid)	yes
`key`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`value`	string or null	no
`secret`	boolean or null	no
`target`	string or null	no

Responses

Section titled Delete one environment variable

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Delete one environment variable

DELETE /api/v1/client/apps/{app_uuid}/env/{key}

Delete one environment variable. Running replicas keep it until the next release. A key the app does not have answers 404.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`app_uuid`	path	string (uuid)	yes
`key`	path	string	yes

Responses

Section titled Start a release from the live release or from the branch again

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Start a release from the live release or from the branch again

POST /api/v1/client/apps/{app_uuid}/redeploy

Start a release from the live release or from the branch again.

{"rebuild": false}, the default, is Redeploy: the live release runs again with the environment, size, region and replica changes saved now, and nothing is built or pulled (source redeploy, trigger manual). {"rebuild": true} is Rebuild: it builds the newest commit on the app's branch again, or for an image app pulls the saved image again (Pull again), and the new release replaces the live one once it is healthy. Its trigger is rebuild. An app with nothing live yet builds or pulls afresh either way, as Deploy a branch does. Answers 201 with the new release under deployment; 409 while the app is not active.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`app_uuid`	path	string (uuid)	yes

Request body

application/json

Field	Type	Required	Description
`rebuild`	boolean	no	false is Redeploy: the live release runs again with the environment, size and locations saved now, and nothing is built or pulled. true is Rebuild: the newest commit on the app's branch is built again, or for an image app the saved image is pulled again (Pull again), and the new release replaces the live one once it is healthy. A rebuild is recorded with the trigger rebuild

Responses

Section titled A new secret for the push webhook, shown once; the old one stops verifying at once

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

A new secret for the push webhook, shown once; the old one stops verifying at once

POST /api/v1/client/apps/{app_uuid}/webhook/rotate

A new secret for the push webhook, shown once; the old one stops verifying at once.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Name	In	Type	Required
`app_uuid`	path	string (uuid)	yes

Responses