---
title: "Create app"
method: POST
path: "/v2/apps.createApp"
tags: ["apps"]
---

# Create app

`POST /v2/apps.createApp`

Create an app within a project. The app is created with default `production` and `preview` environments.

The slug you provide is the stable, caller-defined handle used to reference this app. It must be unique within the project.

**Important**: The slug cannot collide with an existing app in the same project. A duplicate slug returns a 409 conflict.

**Required Permissions**

Your root key must have one of the following permissions:
- `project.*.create_app` (to create apps in any project)
- `project.<project_id>.create_app` (to create apps in a specific project)

## Request body

- V2AppsCreateAppRequestBody
  - `project` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
  - `name` string, required — Human-readable name for this app. Use a descriptive name like 'Payments API' to identify its purpose.
  - `slug` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
  - `git` AppGitCreateInput — Connect a GitHub repository to the app on creation. Omit to create the app without a repository and connect one later with apps.updateApp.
    - `repository` string, required — The GitHub repository to connect, as "owner/repo". The workspace must have the Unkey GitHub App installed with access to it.
    - `defaultBranch` string — The branch this app's deployments track. Omit to adopt the repository's default branch on GitHub.

## Response `200`

App created successfully. The response contains the app id used to reference it in subsequent operations.

- V2AppsCreateAppResponseBody
  - `meta` Meta, required — Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required — A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` V2AppsCreateAppResponseData, required
    - `appId` string, required — The unique identifier of the newly created app, generated by Unkey. Always begins with 'app_' followed by a unique alphanumeric sequence.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden - Insufficient permissions (requires `project.*.create_app`)
- `404` — Not Found - The requested project does not exist in your workspace
- `409` — Conflict - App with this slug already exists in the project
- `429` — Too Many Requests
- `500` — Internal server error

---

[API](https://skmtc.net/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.net/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/versions/fa78aafac89c/schema)