---
title: "Create API namespace"
method: POST
path: "/v2/apis.createApi"
tags: ["apis"]
---

# Create API namespace

`POST /v2/apis.createApi`

Create an API namespace for organizing keys by environment, service, or product.

Use this to separate production from development keys, isolate different services, or manage multiple products. Each API gets a unique identifier and dedicated infrastructure for secure key operations.

**Important**: API names must be unique within your workspace and cannot be changed after creation.

**Required Permissions**

Your root key must have one of the following permissions:
- `api.*.create_api` (to create APIs in any workspace)

## Request body

- V2ApisCreateApiRequestBody
  - `name` string, required — Human-readable name for this API within your workspace. Use descriptive names like 'Payment Service (prod)' or 'user-api-dev' to clearly identify purpose and environment.

## Response `200`

API namespace created successfully. The response contains the unique API ID for referencing this namespace in key operations.

- V2ApisCreateApiResponseBody
  - `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` V2ApisCreateApiResponseData, required
    - `apiId` string, required — The unique identifier assigned to the newly created API. Use this ID for all subsequent operations including key creation, verification, and API management. Always begins with 'api_' followed by a unique alphanumeric sequence. Store this ID securely as it's required when: - Creating API keys within this namespace - Verifying keys associated with this API - Managing API settings and metadata - Listing keys belonging to this API This identifier is permanent and cannot be changed after creation.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `429` — Too Many Requests
- `500` — Internal server error

## Changes

- **2026-08-11** `2e09f5100f6f` — 2 info
  - the `name` request property's maxLength was increased from `255` to `256`
  - removed the pattern `^[a-zA-Z][a-zA-Z0-9._-]*$` from the request property `name`
- **2026-07-14** `43ad1ce9a152` — 2 info
  - the endpoint scheme security `bearer` was added to the API
  - the endpoint scheme security `rootKey` was removed from the API
- **2026-02-27** `551df53dd45d` — 1 info
  - added the non-success response with the status `429`
- **2026-01-14** `9a9c22b6dd09` — 1 info
  - api operation id `createApi` removed and replaced with `apis.createApi`

[Change history](https://skmtc.dev/unkeyed/apis/unkey-api/changes/v2/apis.createApi/post.md)

---

[API](https://skmtc.dev/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.dev/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/revisions/982b36cad359/schema)