Client API: Apps

Apps built once from a git repository or an image and run as replicas in the regions you choose: deployments, build logs, rollbacks, environment variables and domains. Paths are under /api/v1/client/apps.

Base URL: https://api.coritan.com/api/v1. Paths below are complete.

To try these requests in the browser, open the interactive Client API reference.

GET /api/v1/client/apps

The caller's apps, newest first, each with its current deployment, replica counts and domains.

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

POST /api/v1/client/apps

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

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

application/json (required)

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>.

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

Get one app with its domains, recent deployments and current replicas. deployments holds the five newest and deployments_total counts them all; replicas are those of the deployment that serves the app, 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>.

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 deployment or a new build.

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

application/json (required)

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

Delete the app: deployments 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.

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

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

List an app's deployments, newest first, a page at a time. limit takes 1 to 100 (20 when left out) and total counts every deployment. Each one carries its status, source, build and replica counts.

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

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

Deploy: a git app builds git_ref (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.

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

application/json (required)

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

Get one deployment 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 deployment of another app answers 404.

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

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

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

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

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

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

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

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

A new deployment of this earlier ready deployment's image; its replicas that still have servers are started again instead of placed.

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

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>.

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>.

application/json (required)

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>.

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>.

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>.

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 deployment.

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

application/json (required)

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. Replicas get the change with the next deployment.

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

application/json (required)

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

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

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

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

Deploy the current version again (picking up environment, size, region and replica changes), or build the branch afresh with rebuild.

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

application/json

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>.