Organization API: Organization apps

The organization's apps on the Apps API, which App Deployment replaces: use Organization deployments. It keeps answering under /api/v1/orgs/{org_slug}/apps.

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

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

GET /api/v1/orgs/{org_slug}/apps

The caller's apps, newest first, each with its live release (the current_deployment key), replica counts and domains.

POST /api/v1/orgs/{org_slug}/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.

application/json (required)

GET /api/v1/orgs/{org_slug}/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.

GET /api/v1/orgs/{org_slug}/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.

PATCH /api/v1/orgs/{org_slug}/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.

application/json (required)

DELETE /api/v1/orgs/{org_slug}/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.

GET /api/v1/orgs/{org_slug}/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.

POST /api/v1/orgs/{org_slug}/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.

application/json (required)

GET /api/v1/orgs/{org_slug}/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.

POST /api/v1/orgs/{org_slug}/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.

GET /api/v1/orgs/{org_slug}/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.

POST /api/v1/orgs/{org_slug}/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.

GET /api/v1/orgs/{org_slug}/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.

POST /api/v1/orgs/{org_slug}/apps/{app_uuid}/domains

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

application/json (required)

DELETE /api/v1/orgs/{org_slug}/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.

POST /api/v1/orgs/{org_slug}/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.

GET /api/v1/orgs/{org_slug}/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.

PUT /api/v1/orgs/{org_slug}/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.

application/json (required)

PUT /api/v1/orgs/{org_slug}/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.

application/json (required)

DELETE /api/v1/orgs/{org_slug}/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.

POST /api/v1/orgs/{org_slug}/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.

application/json

POST /api/v1/orgs/{org_slug}/apps/{app_uuid}/webhook/rotate

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