Change or delete an app with the Apps API

You can change most of an app's settings after you create it. Some changes apply at once, and others reach the running replicas only with the next release or the next build. The app's source type and its name on the platform stay as you created them.

In the dashboard, the same settings are on the Settings tab of the app's page under App Deployment, where Delete deployment… deletes it (Change or delete a deployment). Where it runs and how many instances it has are on its Instances tab (Choose locations and scaling). This page covers the Apps API, which scripts written for Apps keep using.

• Send your access token as Authorization: Bearer $CORITAN_TOKEN (Authentication). Each request takes the app's uuid, which GET /api/v1/client/apps lists.
• For an organization's app, you need the owner or admin role in the organization.
• To delete an organization's app from the staff console, you need to have confirmed it is you in the last 10 minutes (Confirm it is you).

PATCH /api/v1/client/apps/{app_uuid} changes any of these, with the same rules as when you create an app (Create an app with the Apps API):

• name. The name on the platform, slug, cannot change.
• For a git app, the repository, branch, directory and access token: repo_url, repo_branch, repo_subdir and repo_token. For an image app, image_ref.
• For a git app, how it builds and starts: framework, install_command, build_command and start_command. A dockerfile_path is refused with 422 and dockerfile_unsupported, since Dockerfiles are not built; an empty one clears a path saved before.
• port, health_check_path and instance_size.

Where the app runs, and how many replicas each region keeps, are its locations. Change them on the app's Instances tab or with PUT /api/v1/client/deployments/{deployment_uuid}/placements, where the deployment's ID is the app's uuid. That also rewrites the app's regions, min_replicas and max_replicas, which the Apps API keeps as a summary for scripts written for Apps (Choose locations and scaling).

Environment variables have their own requests (Set environment variables with the Apps API), and so do custom domains (Add a custom domain with the Apps API).

The answer to each change says which kind of release applies it, as redeploy_required and rebuild_required (Redeploy and Rebuild). A redeploy of an image app runs the image that is running now, so after changing the image, rebuild or deploy the image.

A change to the port also asks for a redeploy, and a change to the framework for a new build. Neither setting changes how the app runs: replicas listen on the port in their PORT variable (What your app must do), and the build does not read the framework.

We can suspend an app. Suspending it cancels its releases on their way, stops its domains reaching it and stops its replicas. Its status is then suspended, and its page in the dashboard shows This deployment is suspended. An app with a billing mode is suspended and resumed with its service, for example while an invoice is unpaid (How App Deployment is billed).

While an app is suspended, you can read it, change its settings and delete it. It cannot deploy or roll back: the API answers 409 with The deployment is suspended; it cannot deploy, and the push webhook ignores pushes. When we resume the app, the instances the suspension stopped start again. Instances that were already stopped before it (a process you disabled, a replica count you lowered, a location that was asleep) stay as they were. Contact support to find out why an app was suspended.

A budget set to Pause stops an app in the same way once this month's spend reaches it. Its status is then paused, the dashboard shows Paused, and deploying answers 409 with The deployment is paused; it cannot deploy. Its replicas start again when you raise or remove the budget, or when the month turns (Set a budget).

A game server's or a database's deployment is paused the same way: each of its servers that was running is stopped, and when the limit lets go those servers, and only those, are started again. A server you had stopped yourself stays stopped. While the deployment is paused, its servers cannot be started or restarted, from their panel, a schedule or the API, and stopping one still works. If the deployment is suspended while it is paused, it comes back paused, and its servers start when the limit lets go.

Deleting an app does all of this:

• Cancels its releases on their way.
• Removes its platform name and custom domains, with their routes and certificates, so visitors can no longer reach it.
• Stops its replicas and removes them.
• Erases its environment variables, its access token, its push webhook secret and its deploy hooks.
• Frees its name on the platform, so another app can take it.

Delete it with DELETE /api/v1/client/apps/{app_uuid}, typing the app's name on the platform as confirm. You can also give a reason of up to 500 characters, which goes into the audit log with the deletion.

An app that has a billing mode (usage, pay as you go or monthly) is billed through a service. Deleting it ends that service now, as cancelling it on your services page does, and the app goes once the service has ended. Deleting it from its deployment, on its Settings tab or with DELETE /api/v1/client/deployments/{deployment_uuid}, does the same (Change or delete a deployment).

For an organization's app, only an owner or admin can delete it. From a staff console session, they also need to have confirmed it is them in the last 10 minutes. A request made with the member's own Coritan access token needs only the typed name.

The answer holds the app with the new settings. Settings that need a new release or build apply once you start one.

After you delete an app that no service bills, it no longer appears in your apps, and a request for it answers 404 with App not found. Its domains stop reaching it at once. An app that a service bills goes the same way once its service has ended, which starts as soon as you delete it: until then it is still listed and its domains still reach it, and deleting it again answers 409 with already_ending.

No app node in syd has room for another replica of this deployment

A region the app runs in had no room for a replica, so the release could not start one there. An app in every region goes live without it, and an app with named regions fails. Take the region out on the app's Instances tab, or run the app in every region (Choose locations and scaling).

Type the app's name, web-shop, to confirm

confirm is not the app's name on the platform. Send it as the message shows it.

Confirm your password or a code from your authenticator to do this.

The staff console session has not confirmed it is you in the last 10 minutes. Confirm it, then delete the app again.

Admin access required

Only an owner or admin of the organization can change or delete its apps.

image_ref is for apps that run an image; this app builds from git

A git app cannot switch to an image, or back. Create a new app with the other source.

'release 2' is not a branch name git accepts

A branch name cannot have spaces and some other characters. Check the branch's name at your git host.

These regions cannot run apps: syd

A region you chose cannot run apps now. Choose from the regions the platform offers (Regions, sizes and limits).

min_replicas must be between 1 and 5

Choose from 1 to 5 replicas in each region.

Too many changes to apps. Wait a while and try again.

You made 120 changes to apps in the last hour. Wait, then try again (Requests).

• Deploy an app with the Apps API
• Set environment variables with the Apps API
• App and release fields
• Organization roles and permissions

PATCH /api/v1/client/apps/{app_uuid} changes an app's settings. For an organization's app, send it to PATCH /api/v1/orgs/{org_slug}/apps/{app_uuid}. Send only the settings you change.

curl -X PATCH https://api.coritan.com/api/v1/client/apps/3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21 \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_branch": "production"}'

The body takes the fields of the create request except slug, source_type, env and deploy. Sending one of those answers 422 with a field error whose type is extra_forbidden (A list of field errors).

• A new repo_token replaces the token, and an empty one removes it. The app's repo_token_hint shows the last four characters of the token it holds.
• An empty repo_subdir, dockerfile_path, framework, install_command, build_command or start_command clears it.
• An empty health_check_path sets it to /.
• An app that is billed takes its size from its plan: change the plan instead (POST /api/v1/services/{id}/change-plan). A different instance_size answers 409 plan_change_required with the service_id; sending the current size changes nothing. An app billed by use has no plan to change, and the same refusal says The size of a deployment that is billed by use is managed by the platform.
• To change where the app runs, use the placements request rather than regions, min_replicas and max_replicas (Choose locations and scaling). It saves the app's locations, and saved locations are what each release follows.

It answers with the app and what changed:

{
  "app": {
    "uuid": "3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21",
    "repo_branch": "production",
    "instance_size": "small"
  },
  "changed": ["repo_branch"],
  "redeploy_required": false,
  "rebuild_required": true
}

The example shortens app, which carries every field (App and release fields). changed lists the fields whose value changed, and names a new or removed token as repo_token. On an app no service bills, a new size sets memory_mb, cpu_percent and disk_mb with it.

rebuild_required is true when the change reaches the app only through a new build, so rebuild or push a commit. redeploy_required is true when a new release of the live release's image is enough, so a redeploy applies it. After changing an app's image, rebuild or deploy the image, because a redeploy runs the image that is running now. redeploy_required is also true after a change to the port, and rebuild_required after a change to the framework.

DELETE /api/v1/client/apps/{app_uuid} deletes an app. Give the app's name on the platform as confirm, and a reason as reason if you like. For an organization's app, send it to DELETE /api/v1/orgs/{org_slug}/apps/{app_uuid}.

curl -X DELETE "https://api.coritan.com/api/v1/client/apps/3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21?confirm=web-shop&reason=Moved%20to%20a%20new%20app" \
  -H "Authorization: Bearer $CORITAN_TOKEN"

An app that a service bills answers with deleted false, ending true and its service, whose ends_at is now. Its routes go once the service has ended, so routes_removed is empty:

{
  "deleted": false,
  "ending": true,
  "uuid": "3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21",
  "slug": "web-shop",
  "routes_removed": [],
  "service": {"id": 812, "status": "pending_termination", "ends_at": "2026-09-28T04:00:12.481903+00:00"}
}

An app that no service bills is deleted at once:

{
  "deleted": true,
  "ending": false,
  "uuid": "3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21",
  "slug": "web-shop",
  "routes_removed": ["web-shop.apps.example.net", "www.example.com"]
}

routes_removed lists the hostnames that stopped reaching the app.