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

Source: https://www.coritan.com/docs/api/reference/client/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](https://api.coritan.com/docs).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/client/apps`](#op-get-api-v1-client-apps) | List apps |
| POST | [`/api/v1/client/apps`](#op-post-api-v1-client-apps) | Create an app and, unless deploy is false, its first deployment |
| GET | [`/api/v1/client/apps/regions`](#op-get-api-v1-client-apps-regions) | Regions |
| GET | [`/api/v1/client/apps/{app_uuid}`](#op-get-api-v1-client-apps-app-uuid) | Get one app with its domains, recent deployments and current replicas |
| PATCH | [`/api/v1/client/apps/{app_uuid}`](#op-patch-api-v1-client-apps-app-uuid) | Change an app's settings |
| DELETE | [`/api/v1/client/apps/{app_uuid}`](#op-delete-api-v1-client-apps-app-uuid) | Delete app |
| GET | [`/api/v1/client/apps/{app_uuid}/deployments`](#op-get-api-v1-client-apps-app-uuid-deployments) | List an app's deployments, newest first, a page at a time |
| POST | [`/api/v1/client/apps/{app_uuid}/deployments`](#op-post-api-v1-client-apps-app-uuid-deployments) | Create app deployment |
| GET | [`/api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}`](#op-get-api-v1-client-apps-app-uuid-deployments-deployment-uuid) | Get one deployment of an app, with each of its replicas |
| POST | [`/api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}/cancel`](#op-post-api-v1-client-apps-app-uuid-deployments-deployment-uuid-cancel) | Cancel a deployment that is still queued, building or deploying |
| GET | [`/api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}/log`](#op-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) |
| POST | [`/api/v1/client/apps/{app_uuid}/deployments/{deployment_uuid}/rollback`](#op-post-api-v1-client-apps-app-uuid-deployments-deployment-uuid-rollback) | Rollback app |
| GET | [`/api/v1/client/apps/{app_uuid}/domains`](#op-get-api-v1-client-apps-app-uuid-domains) | List an app's domains: its platform name first, then its custom domains |
| POST | [`/api/v1/client/apps/{app_uuid}/domains`](#op-post-api-v1-client-apps-app-uuid-domains) | Add a custom domain |
| DELETE | [`/api/v1/client/apps/{app_uuid}/domains/{hostname}`](#op-delete-api-v1-client-apps-app-uuid-domains-hostname) | Remove a custom domain from an app |
| POST | [`/api/v1/client/apps/{app_uuid}/domains/{hostname}/verify`](#op-post-api-v1-client-apps-app-uuid-domains-hostname-verify) | Look for the domain's TXT record |
| GET | [`/api/v1/client/apps/{app_uuid}/env`](#op-get-api-v1-client-apps-app-uuid-env) | List an app's environment variables without their values |
| PUT | [`/api/v1/client/apps/{app_uuid}/env`](#op-put-api-v1-client-apps-app-uuid-env) | Set many variables; a variable given without value keeps its saved one |
| PUT | [`/api/v1/client/apps/{app_uuid}/env/{key}`](#op-put-api-v1-client-apps-app-uuid-env-key) | Set one environment variable, creating it when it is new |
| DELETE | [`/api/v1/client/apps/{app_uuid}/env/{key}`](#op-delete-api-v1-client-apps-app-uuid-env-key) | Delete one environment variable |
| POST | [`/api/v1/client/apps/{app_uuid}/redeploy`](#op-post-api-v1-client-apps-app-uuid-redeploy) | Redeploy app |
| POST | [`/api/v1/client/apps/{app_uuid}/webhook/rotate`](#op-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 |

### List apps {#op-get-api-v1-client-apps}

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

#### Parameters

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

#### Responses

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

### Create an app and, unless deploy is false, its first deployment {#op-post-api-v1-client-apps}

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

#### 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 |  |
| `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 |  |
| `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 deployment at once |

#### Responses

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

### Regions {#op-get-api-v1-client-apps-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

| Status | Meaning |
| --- | --- |
| `200` | Success. |

### Get one app with its domains, recent deployments and current replicas {#op-get-api-v1-client-apps-app-uuid}

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

#### Parameters

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

#### Responses

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

### Change an app's settings {#op-patch-api-v1-client-apps-app-uuid}

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

#### 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 |  |
| `regions` | array of string or null | no |  |
| `min_replicas` | integer or null | no |  |
| `max_replicas` | integer or null | no |  |

#### Responses

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

### Delete app {#op-delete-api-v1-client-apps-app-uuid}

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

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

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

### List an app's deployments, newest first, a page at a time {#op-get-api-v1-client-apps-app-uuid-deployments}

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

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

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

### Create app deployment {#op-post-api-v1-client-apps-app-uuid-deployments}

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

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

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

### Get one deployment of an app, with each of its replicas {#op-get-api-v1-client-apps-app-uuid-deployments-deployment-uuid}

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

#### Parameters

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

#### Responses

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

### Cancel a deployment that is still queued, building or deploying {#op-post-api-v1-client-apps-app-uuid-deployments-deployment-uuid-cancel}

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

#### Parameters

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

#### Responses

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

### The end of the deployment's build log (secrets redacted as it was written) {#op-get-api-v1-client-apps-app-uuid-deployments-deployment-uuid-log}

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

#### Parameters

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

#### Responses

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

### Rollback app {#op-post-api-v1-client-apps-app-uuid-deployments-deployment-uuid-rollback}

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

#### Parameters

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

#### Responses

| 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 {#op-get-api-v1-client-apps-app-uuid-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

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

### Add a custom domain {#op-post-api-v1-client-apps-app-uuid-domains}

`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

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

### Remove a custom domain from an app {#op-delete-api-v1-client-apps-app-uuid-domains-hostname}

`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

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

### Look for the domain's TXT record {#op-post-api-v1-client-apps-app-uuid-domains-hostname-verify}

`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

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

### List an app's environment variables without their values {#op-get-api-v1-client-apps-app-uuid-env}

`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

| 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 {#op-put-api-v1-client-apps-app-uuid-env}

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

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

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

### Set one environment variable, creating it when it is new {#op-put-api-v1-client-apps-app-uuid-env-key}

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

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

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

### Delete one environment variable {#op-delete-api-v1-client-apps-app-uuid-env-key}

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

#### Parameters

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

#### Responses

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

### Redeploy app {#op-post-api-v1-client-apps-app-uuid-redeploy}

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

#### Parameters

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

#### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `rebuild` | boolean | no | Build the branch again instead of reusing the current image |

#### Responses

| 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 {#op-post-api-v1-client-apps-app-uuid-webhook-rotate}

`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

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