Skip to main content

​
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

​
name
string
required
Unique identifier for this API namespace within your workspace. Use descriptive names like ‘payment-service-prod’ or ‘user-api-dev’ to clearly identify purpose and environment.
  • Must be 3-255 characters long
  • Must start with a letter
  • Can contain letters, numbers, underscores, dots, and hyphens
Example: payment-service-production

​
Response

​
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.Example: api_2cGKbMxRjIzhCxo1IdjH3a

​
Example

cURL
curl -X POST https://api.unkey.com/v2/apis.createApi \
  -H "Authorization: Bearer <your-root-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "payment-service-prod"
  }'
Response
{
  "meta": {
    "requestId": "req_abc123def456"
  },
  "data": {
    "apiId": "api_1234abcd"
  }
}

​
Error Codes

  • 400 - Bad request (invalid name format or missing required fields)
  • 401 - Unauthorized (missing or invalid root key)
  • 403 - Forbidden (insufficient permissions)
  • 429 - Too many requests (rate limit exceeded)
  • 500 - Internal server error

Build docs developers (and LLMs) love

Get started for freeTalk to us