Create an app with the Apps API

Create an app to run a web service from a git repository or from a container image. Creating it also starts its first release unless you turn that off, so a working app is live once its replicas pass their health check. The app then appears under App Deployment in the dashboard, as a Web service.

The Apps API's create request keeps working for scripts written for Apps. A new app can also be ordered as a deployment, which chooses its locations and scaling from the start (Deploy from a git repository). An order has no size and no plan to choose: it names a source, a name and a location, and takes two optional settings, the largest memory and a monthly budget (Order your code).

• Send your access token as Authorization: Bearer $CORITAN_TOKEN (Authentication). Apps must be on for the platform (Limits and availability).
• For a git app, the repository must be on a public host and reachable over HTTPS. For a private repository, create an access token on your git host that can read it.
• For an image app, the image must be one that anyone can pull, such as a public image on GitHub Container Registry or Docker Hub.
• Make sure the app listens on the port in its PORT variable and answers its health check path (What your app must do).
• For an organization's app, you need the owner or admin role in the organization.
• You can have a set number of apps. Regions, sizes and limits shows how many you have and may have.

POST /api/v1/client/apps creates an app of your own. For an organization's app, send the same body to POST /api/v1/orgs/{org_slug}/apps.

curl -X POST https://api.coritan.com/api/v1/client/apps \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Web shop",
    "source_type": "git",
    "repo_url": "https://github.com/example/web-shop",
    "repo_branch": "main",
    "repo_token": "github_pat_EXAMPLE",
    "health_check_path": "/healthz",
    "instance_size": "small",
    "regions": ["fra", "iad"],
    "min_replicas": 2,
    "env": [{"key": "DATABASE_URL", "value": "postgres://app:secret@db.example.com/shop"}]
  }'

The body takes these fields. Only name is required, and a git app also needs repo_url, an image app image_ref. Whether the app builds from git or runs an image cannot change later.

name

What you call the app, 1–100 characters. You can change it later.

slug

The name on the platform, which the app's platform name <slug>.<app domain> is made from. Made from name when left out (Names on the platform). It cannot change after you create the app.

source_type

git, the default, or image.

repo_url

For a git app, the repository's HTTPS address, such as https://github.com/example/web-shop, with no user name, token, query or fragment in it.

repo_branch

The branch to build, main when left out. Pushes to it deploy the app once you set up the push webhook.

repo_subdir

Where the app lives inside the repository. Leave it out when the app is at the top.

repo_token

For a private repository. We keep it encrypted, use it only to fetch the code, and never show it again. The app shows its last four characters as repo_token_hint, so you can tell which token it holds. An image app refuses the repository fields.

image_ref

For an image app, a reference such as ghcr.io/example/web:1.4.0, or one pinned to a digest such as ghcr.io/example/web@sha256:…. It must be one anyone can pull, such as an image your CI builds from a Dockerfile and pushes to GitHub Packages or Docker Hub. A git app refuses it.

dockerfile_path

Leave it out. Dockerfiles are not built, so a path answers 422 with dockerfile_unsupported: build the image in your CI and create an image app instead (Dockerfile? Deploy a container image).

install_command, build_command and start_command

Commands that replace the framework's defaults, up to 500 characters each (Frameworks we build).

framework

The framework preset to build with, such as next, sveltekit, fastapi or go. Leave it out and the build detects it from the files. GET /api/v1/deploy-presets lists the presets.

port

A number from 1 to 65535, 3000 when left out. Each replica gets the port to listen on in its PORT variable, whatever this setting says.

health_check_path

The path we request to decide that a replica is healthy, / when left out. It starts with /, such as /healthz.

instance_size

small, medium or large, small when left out. It sets the memory, CPU and disk each replica gets (Replicas and regions). The app is billed by what it uses from the moment it is created, and the size becomes its starting memory limit. A larger limit costs nothing until the replicas use it (How App Deployment is billed). A prepaid account that has not added the first deposit gets 403 with the code deposit_required and nothing is created. When billing by use is not available for the size, nothing is created and the API answers 409 size_not_offered.

regions

["*"] for every region that can run apps at the time of each release, the default, or a list of up to 20 region codes.

min_replicas and max_replicas

Replicas in each region, 1–5 for min_replicas (1 when left out). max_replicas takes up to 10, and one below min_replicas is raised to it. To let each region scale with traffic up to its maximum, save the app's locations on its Instances tab afterwards, with a maximum above the minimum (Scale with traffic).

env

A list of variables, each with key, value and optionally secret and target (Set environment variables with the Apps API).

deploy

true, the default, starts the first release. false creates the app without one.

It answers 201:

{
  "app": {
    "uuid": "3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21",
    "name": "Web shop",
    "slug": "web-shop",
    "status": "active",
    "source_type": "git",
    "repo_token_set": true,
    "repo_token_hint": "MPLE",
    "url": "https://web-shop.apps.example.net"
  },
  "deployment": {
    "uuid": "0b6f3d2e-7a41-4c59-8e1d-2f9a6b3c4d5e",
    "status": "queued",
    "source": "git",
    "trigger": "manual",
    "git_ref": "main"
  },
  "deploy_error": null,
  "webhook": {
    "url": "https://api.coritan.com/api/v1/apps/hooks/3c9e2f4a-8b1d-4f6e-a2c7-5d8b9e0f1a21",
    "secret": "4f1d2c3b5a69788796a5b4c3d2e1f0a94f1d2c3b5a69788796a5b4c3d2e1f0a9"
  }
}

The example shortens app and the first release, which the API names deployment. Both carry every field (App and release fields). webhook.secret appears in this answer only, and webhook is null for an image app. deployment is null when you sent "deploy": false, and also when the first release could not start, when deploy_error says why, as in The GitHub App is suspended on example-org. Unsuspend it on GitHub, or connect the repository again..

A name on the platform has 3 to 63 lowercase letters, digits and hyphens, and starts and ends with a letter or a digit. It cannot have hyphens in both its third and fourth places, and no other app on the platform can have it. Some words are reserved for the platform, such as api, admin, app, status and www.

When you leave it out, we make one from the app's name, such as web-shop for Web shop. When that one is taken or reserved, we add a hyphen and four random characters, as in web-shop-k3x9.

A git app starts with a build of its branch, then starts replicas. An image app starts replicas at once. Follow the first release with Read a release and its build log with the Apps API, or on the app's Releases tab.

A git app also gets a push webhook, and its secret is in the answer to the create request only. Save it if you want pushes to deploy the app (Deploy on every push). You can make a new secret later.

If the first release cannot start, we still create the app and say why in deploy_error. Fix the cause, then deploy it (Deploy an app with the Apps API).

An app is a deployment, and How App Deployment is billed explains how deployments are billed. Its Billing tab in the dashboard, or GET /api/v1/billing/deployments/{app_uuid}, shows how it is billed and what it has cost this month. An app created through the Apps API has no pay as you go or monthly price to choose.

The app is in your apps with its platform address, and its first release is on its way unless you turned it off. Once that release is ready, which the dashboard shows as Live, the app is live and answers at https://<name on the platform>.<app domain>.

The repository must be on a public host. or The repository URL must start with https://.

Give the repository's HTTPS address on a public host.

Put the access token in the app's repository token, not in the URL.

Remove the user name or token from the address and send the token as repo_token.

The image must be on a public registry

The image's host is on a private network. Push the image to a public host, such as GitHub Packages or Docker Hub.

An organization's route also answers 403 with Admin access required for a member who is not an owner or admin. Apps API limits lists the other rate limits.

• How the Apps API runs an app
• Deploy an app with the Apps API
• Set environment variables with the Apps API
• Deploy from a git repository