Organization API: Organization apps

The organization's own Apps, as /api/v1/client/apps serves an account's: deployments, build logs, rollbacks, environment variables and domains.

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 current deployment, replica counts and domains.

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

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

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

application/json (required)

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

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

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

application/json (required)

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

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

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

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

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

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

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 deployment. A key the app does not have answers 404.

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

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

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.