Skip to main content
You need a root key with the permissions listed on this page. Create one in the dashboard under Settings > Root Keys. See Permission reference for every permission.
Create an inside a project. The app is created with a production and a preview . The slug is what you pass to later --app flags. It must be unique within the project, or you get a 409 conflict. Pass exactly one source:
  • --git for a GitHub repository. Pass a repository to connect it now (the Unkey GitHub App must be installed first), or pass --git='{}' and connect one later with update-app.
  • --oci for a prebuilt image, if you already build images elsewhere.

​
Usage

​
Flags

​
string
GitHub repository connection as a JSON object, for example {"repository":"unkeyed/api","defaultBranch":"main"}. Both fields are optional, so {} creates a Git app with no repository yet; defaultBranch requires repository. Mutually exclusive with --oci.
​
string
OCI image source as a JSON object with a required image field, for example {"image":"ghcr.io/acme/payments:v1.2.3"}. The reference needs an explicit tag or digest and is at most 256 characters. Mutually exclusive with --git.
​
string
required
Human-readable name for the app, 1 to 256 characters.
​
string
required
Project ID or slug. Both forms resolve to the same project.
​
string
required
Stable app slug, unique within the project. 3 to 255 characters matching ^[a-zA-Z0-9_-]+$. Used in --app flags and in generated deployment hostnames.

​
Shared flags

Every unkey api command accepts these; CLI output and shared flags describes them in full.
​
string
A JSON document sent as the request body instead of building it from the flags above. It is mutually exclusive with the request-building flags, and unknown fields are rejected locally. See Send a raw body.
​
string
Root key for the request. Falls back to UNKEY_ROOT_KEY, then to the config file written by unkey auth login. See CLI authentication.
​
string
default:"https://api.unkey.com"
Base URL of the API. Falls back to UNKEY_API_BASE_URL. You don’t normally need to set it.
​
string
default:"~/.unkey/config.toml"
Path of the TOML file that unkey auth login writes. Falls back to UNKEY_CONFIG.
​
string
Output format. Falls back to UNKEY_OUTPUT. Set json to print the full response envelope (meta and data) for piping; any other value prints the request ID followed by data.

​
Required permissions

Your root key needs one of:
  • project.*.create_app (apps in any project)
  • project.<project_id>.create_app (apps in a specific project)
If --git includes a repository, your key also needs app.*.connect_repository. --git='{}' doesn’t. Without a matching permission the API answers 403 and the CLI prints Permission denied: followed by the detail. See Root key permissions for the full catalog.

​
Examples

Create an app connected to a repository:
Create a Git app now and connect the repository later:
Create an app from a prebuilt image:
Send the request body as JSON:

​
API endpoint

The command calls POST /v2/apps.createApp and prints its response. The request fields carry the same names as the flags in camelCase, which is the shape --body expects.

Projects, apps, and environments

How the three objects nest and how slugs and IDs are resolved.

Deploy from GitHub

Connect a repository and ship the first deployment.
Last modified on September 29, 2026