---
title: "Create ratelimit namespace"
method: POST
path: "/v2/ratelimit.createNamespace"
tags: ["ratelimit"]
---

# Create ratelimit namespace

`POST /v2/ratelimit.createNamespace`

## Request

- Base URL: `https://api.unkey.com`
- URL: `https://api.unkey.com/v2/ratelimit.createNamespace`
- Auth: HTTP bearer

Create a rate limit namespace before you rate limit against it.

`ratelimit.limit` also creates a namespace the first time you use its name, when your root key can create namespaces. Use this endpoint when you want the namespace to exist up front, for example to set overrides before the first request.

**Important**: Names are unique within your workspace, deleted namespaces included. A name that is in use or was deleted returns 409.

**Required Permissions**

Your root key must have the following permission:
- `unkey:v1:<workspace_id>:projects/*/ratelimits/namespaces/*#write`

## Request body

- V2RatelimitCreateNamespaceRequestBody
  - `name` string, required: The name of the namespace, unique within your workspace. Names are case-sensitive. Pass it as `namespace` to `ratelimit.limit` and the override endpoints.

## Response `200`

Namespace created successfully.

- V2RatelimitCreateNamespaceResponseBody
  - `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` RatelimitNamespace, required
    - `id` string, required: The unique identifier of the namespace, generated by Unkey.
    - `name` string, required: The name of the namespace, unique within your workspace. Pass it as `namespace` to `ratelimit.limit` and the override endpoints.
    - `createdAt` integer, required: Unix timestamp in milliseconds when the namespace was created.
    - `updatedAt` integer: Unix timestamp in milliseconds when the namespace was last updated. Omitted if the namespace has never been updated.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `409`: Conflict - The name is in use or was deleted
- `429`: Too Many Requests
- `500`: Internal server error

## Changes

- **2026-10-13** `2f9f9e44cf29`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/unkeyed/apis/unkey-api/changes/v2/ratelimit.createNamespace/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.dev/unkeyed/apis/unkey-api/revisions/6fbaa27f19e0?raw)