openapi: 3.1.0
info:
description: "Unkey's API provides programmatic access for all resources within our platform.\n\n\n### Authentication\n#\nThis API uses HTTP Bearer authentication with root keys. Most endpoints require specific permissions associated with your root key. When making requests, include your root key in the `Authorization` header:\n```\nAuthorization: Bearer unkey_xxxxxxxxxxx\n```\n\nAll responses follow a consistent envelope structure that separates operational metadata from actual data. This design provides several benefits:\n- Debugging: Every response includes a unique requestId for tracing issues\n- Consistency: Predictable response format across all endpoints\n- Extensibility: Easy to add new metadata without breaking existing integrations\n- Error Handling: Unified error format with actionable information\n\n### Success Response Format:\n```json\n{\n \"meta\": {\n \"requestId\": \"req_123456\"\n },\n \"data\": {\n // Actual response data here\n }\n}\n```\n\nThe meta object contains operational information:\n- `requestId`: Unique identifier for this request (essential for support)\n\nThe data object contains the actual response data specific to each endpoint.\n\n### Paginated Response Format:\n```json\n{\n \"meta\": {\n \"requestId\": \"req_123456\"\n },\n \"data\": [\n // Array of results\n ],\n \"pagination\": {\n \"cursor\": \"next_page_token\",\n \"hasMore\": true\n }\n}\n```\n\nThe pagination object appears on list endpoints and contains:\n- `cursor`: Token for requesting the next page\n- `hasMore`: Whether more results are available\n\n### Error Response Format:\n```json\n{\n \"meta\": {\n \"requestId\": \"req_2c9a0jf23l4k567\"\n },\n \"error\": {\n \"detail\": \"The resource you are attempting to modify is protected and cannot be changed\",\n \"status\": 403,\n \"title\": \"Forbidden\",\n \"type\": \"https://unkey.com/docs/errors/unkey/application/protected_resource\"\n }\n}\n```\n\nError responses include comprehensive diagnostic information:\n- `title`: Human-readable error summary\n- `detail`: Specific description of what went wrong\n- `status`: HTTP status code\n- `type`: Link to error documentation\n- `errors`: Array of validation errors (for 400 responses)\n\nThis structure ensures you always have the context needed to debug issues and take corrective action."
title: Unkey analytics ratelimit API
version: 2.0.0
servers:
- url: https://api.unkey.com
security:
- rootKey: []
tags:
- description: Rate limiting operations
name: ratelimit
paths:
/v2/ratelimit.deleteOverride:
post:
description: 'Permanently remove a rate limit override. Affected identifiers immediately revert to the namespace default.
Use this to remove temporary overrides, reset identifiers to standard limits, or clean up outdated rules.
**Important:** Deletion is immediate and permanent. The override cannot be recovered and must be recreated if needed again.
**Permissions:** Requires `ratelimit.*.delete_override` or `ratelimit.<namespace_id>.delete_override`
'
operationId: ratelimit.deleteOverride
requestBody:
content:
application/json:
examples:
specific:
summary: Delete specific override
value:
identifier: premium_user_123
namespace: api.requests
wildcard:
summary: Delete wildcard pattern override
value:
identifier: premium_*
namespace: api.requests
schema:
$ref: '#/components/schemas/V2RatelimitDeleteOverrideRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/V2RatelimitDeleteOverrideResponseBody'
description: Override successfully deleted. Affected identifiers now use default limits.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized
'403':
content:
application/json:
examples:
missingPermission:
summary: Missing required permission
value:
error:
detail: Your root key requires the 'ratelimit.*.delete_override' permission to perform this operation
status: 403
title: Forbidden
type: forbidden
meta:
requestId: req_0uVwX4yZaAbCdEfGhIjKl
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden - Insufficient permissions (requires `ratelimit.*.delete_override`)
'404':
content:
application/json:
examples:
overrideNotFound:
summary: Override not found
value:
error:
detail: No override found for the specified identifier in this namespace.
status: 404
title: Not Found
type: not_found
meta:
requestId: req_2wXyZaAbCdEfGhIjKlMnOp
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not Found - Override or namespace not found
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Internal Server Error
security:
- rootKey: []
summary: Delete Ratelimit Override
tags:
- ratelimit
x-speakeasy-name-override: deleteOverride
/v2/ratelimit.getOverride:
post:
description: 'Retrieve the configuration of a specific rate limit override by its identifier.
Use this to inspect override configurations, audit rate limiting policies, or debug rate limiting behavior.
**Important:** The identifier must match exactly as specified when creating the override, including wildcard patterns.
**Permissions:** Requires `ratelimit.*.read_override` or `ratelimit.<namespace_id>.read_override`
'
operationId: ratelimit.getOverride
requestBody:
content:
application/json:
examples:
specific:
summary: Get specific override
value:
identifier: premium_user_123
namespace: api.requests
wildcard:
summary: Get wildcard pattern override
value:
identifier: premium_*
namespace: api.requests
schema:
$ref: '#/components/schemas/V2RatelimitGetOverrideRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/V2RatelimitGetOverrideResponseBody'
description: Override found and returned successfully.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized
'403':
content:
application/json:
examples:
missingPermission:
summary: Missing required permission
value:
error:
detail: Your root key requires the 'ratelimit.*.read_override' permission to perform this operation
status: 403
title: Forbidden
type: forbidden
meta:
requestId: req_0uVwX4yZaAbCdEfGhIjKl
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden - Insufficient permissions (requires `ratelimit.*.read_override`)
'404':
content:
application/json:
examples:
overrideNotFound:
summary: Override not found
value:
error:
detail: No override found for the specified identifier in this namespace.
status: 404
title: Not Found
type: not_found
meta:
requestId: req_2wXyZaAbCdEfGhIjKlMnOp
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not Found - Override or namespace not found
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Internal Server Error
security:
- rootKey: []
summary: Get Ratelimit Override
tags:
- ratelimit
x-speakeasy-name-override: getOverride
/v2/ratelimit.limit:
post:
description: 'Check and enforce rate limits for any identifier (user ID, IP address, API client, etc.).
Use this for rate limiting beyond API keys - limit users by ID, IPs by address, or any custom identifier. Supports namespace organization, variable costs, and custom overrides.
**Response Codes**: Rate limit checks return HTTP 200 regardless of whether the limit is exceeded — check the `success` field in the response to determine if the request should be allowed. A 429 may be returned if the workspace exceeds its API rate limit. Other 4xx responses indicate auth, namespace existence/deletion, or validation errors (e.g., 410 Gone for deleted namespaces). 5xx responses indicate server errors.
**Required Permissions**
Your root key must have one of the following permissions:
- `ratelimit.*.limit` (to check limits in any namespace)
- `ratelimit.<namespace_id>.limit` (to check limits in a specific namespace)
'
operationId: ratelimit.limit
requestBody:
content:
application/json:
examples:
basic:
summary: Basic rate limit check
value:
duration: 60000
identifier: user_abc123
limit: 100
namespace: api.requests
ipLimit:
summary: IP-based rate limiting
value:
duration: 60000
identifier: 203.0.113.42
limit: 5
namespace: auth.login
weightedCost:
summary: Operation with variable cost
value:
cost: 5
duration: 3600000
identifier: user_def456
limit: 50
namespace: api.heavy_operations
schema:
$ref: '#/components/schemas/V2RatelimitLimitRequestBody'
required: true
responses:
'200':
content:
application/json:
examples:
allowed:
summary: Request allowed
value:
data:
limit: 100
remaining: 99
reset: 1714582980000
success: true
meta:
requestId: req_01H9TQPP77V5E48E9SH0BG0ZQX
limitReached:
summary: Rate limit exceeded
value:
data:
limit: 100
remaining: 0
reset: 1714582980000
success: false
meta:
requestId: req_01H9TQPP77V5E48E9SH0BG0ZQY
withOverride:
summary: With custom override applied
value:
data:
limit: 1000
overrideId: ovr_2cGKbMxRyIzhCxo1Idjz8q
remaining: 995
reset: 1714582980000
success: true
meta:
requestId: req_01H9TQPP77V5E48E9SH0BG0ZQZ
schema:
$ref: '#/components/schemas/V2RatelimitLimitResponseBody'
description: 'Rate limit check completed successfully. Check the `success` field to determine if the request is allowed.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not Found
'410':
content:
application/json:
schema:
$ref: '#/components/schemas/GoneErrorResponse'
description: Gone - Namespace has been deleted
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Internal server error
security:
- rootKey: []
summary: Apply Rate Limiting
tags:
- ratelimit
x-speakeasy-name-override: limit
/v2/ratelimit.listOverrides:
post:
description: 'Retrieve a paginated list of all rate limit overrides in a namespace.
Use this to audit rate limiting policies, build admin dashboards, or manage override configurations.
**Important:** Results are paginated. Use the cursor parameter to retrieve additional pages when more results are available.
**Permissions:** Requires `ratelimit.*.read_override` or `ratelimit.<namespace_id>.read_override`
'
operationId: ratelimit.listOverrides
requestBody:
content:
application/json:
examples:
basic:
summary: List all overrides
value:
limit: 20
namespace: api.requests
pagination:
summary: Get next page
value:
cursor: cursor_eyJsYXN0SWQiOiJvdnJfM2RITGNOeVN6SnppRHlwMkpla2E5ciJ9
namespace: api.requests
schema:
$ref: '#/components/schemas/V2RatelimitListOverridesRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/V2RatelimitListOverridesResponseBody'
description: Overrides retrieved successfully. Includes pagination metadata if more results are available.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized
'403':
content:
application/json:
examples:
missingPermission:
summary: Missing required permission
value:
error:
detail: Your root key requires the 'ratelimit.*.read_override' permission to perform this operation
status: 403
title: Forbidden
type: forbidden
meta:
requestId: req_0uVwX4yZaAbCdEfGhIjKl
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden - Insufficient permissions (requires `ratelimit.*.read_override`)
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not Found
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Error
security:
- rootKey: []
summary: List Ratelimit Overrides
tags:
- ratelimit
x-speakeasy-name-override: listOverrides
/v2/ratelimit.multiLimit:
post:
description: 'Check and enforce multiple rate limits in a single request for any identifiers (user IDs, IP addresses, API clients, etc.).
Use this to efficiently check multiple rate limits at once. Each rate limit check is independent and returns its own result with a top-level `passed` indicator showing if all checks succeeded.
**Response Codes**: Rate limit checks return HTTP 200 regardless of whether limits are exceeded — check the `passed` field to see if all limits passed, or the `success` field in each individual result. A 429 may be returned if the workspace exceeds its API rate limit. Other 4xx responses indicate auth, namespace existence/deletion, or validation errors (e.g., 410 Gone for deleted namespaces). 5xx responses indicate server errors.
**Required Permissions**
Your root key must have one of the following permissions:
- `ratelimit.*.limit` (to check limits in any namespace)
- `ratelimit.<namespace_id>.limit` (to check limits in all specific namespaces being checked)
'
operationId: ratelimit.multiLimit
requestBody:
content:
application/json:
examples:
ipHashAndUserLimits:
summary: Check both hashed IP and user rate limits
value:
- duration: 60000
identifier: sha256_8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4
limit: 10
namespace: auth.login
- duration: 3600000
identifier: user_def456
limit: 1000
namespace: api.requests
multipleChecks:
summary: Multiple rate limit checks
value:
- duration: 60000
identifier: user_abc123
limit: 100
namespace: api.requests
- duration: 60000
identifier: user_abc123
limit: 5
namespace: auth.login
withWeightedCost:
summary: Multiple checks with variable costs
value:
- cost: 1
duration: 60000
identifier: user_xyz789
limit: 100
namespace: api.light_operations
- cost: 5
duration: 3600000
identifier: user_xyz789
limit: 50
namespace: api.heavy_operations
schema:
$ref: '#/components/schemas/V2RatelimitMultiLimitRequestBody'
required: true
responses:
'200':
content:
application/json:
examples:
allAllowed:
summary: All requests allowed
value:
data:
limits:
- identifier: user_abc123
limit: 100
namespace: api.requests
remaining: 99
reset: 1714582980000
success: true
- identifier: user_abc123
limit: 5
namespace: auth.login
remaining: 4
reset: 1714582980000
success: true
passed: true
meta:
requestId: req_01H9TQPP77V5E48E9SH0BG0ZQX
mixedResults:
summary: Some limits exceeded
value:
data:
limits:
- identifier: sha256_8f434346648f6b96df89dda901c5176b10a6d83961dd3c1ac88b59b2dc327aa4
limit: 10
namespace: auth.login
remaining: 5
reset: 1714582980000
success: true
- identifier: user_def456
limit: 1000
namespace: api.requests
remaining: 0
reset: 1714583040000
success: false
passed: false
meta:
requestId: req_01H9TQPP77V5E48E9SH0BG0ZQY
withOverride:
summary: With custom override applied
value:
data:
limits:
- identifier: user_xyz789
limit: 100
namespace: api.light_operations
remaining: 95
reset: 1714582980000
success: true
- identifier: user_xyz789
limit: 1000
namespace: api.heavy_operations
overrideId: ovr_2cGKbMxRyIzhCxo1Idjz8q
remaining: 995
reset: 1714582980000
success: true
passed: true
meta:
requestId: req_01H9TQPP77V5E48E9SH0BG0ZQZ
schema:
$ref: '#/components/schemas/V2RatelimitMultiLimitResponseBody'
description: 'All rate limit checks completed successfully. Check the `success` field in each result to determine if the corresponding request is allowed.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not Found
'410':
content:
application/json:
schema:
$ref: '#/components/schemas/GoneErrorResponse'
description: Gone - Namespace has been deleted
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Internal server error
security:
- rootKey: []
summary: Apply Multiple Rate Limit Checks
tags:
- ratelimit
x-speakeasy-name-override: multiLimit
/v2/ratelimit.setOverride:
post:
description: 'Create or update a custom rate limit for specific identifiers, bypassing the namespace default.
Use this to create premium tiers with higher limits, apply stricter limits to specific users, or implement emergency throttling.
**Important:** Overrides take effect immediately and completely replace the default limit for matching identifiers. Use wildcard patterns (e.g., `premium_*`) to match multiple identifiers.
**Permissions:** Requires `ratelimit.*.set_override` or `ratelimit.<namespace_id>.set_override`
'
operationId: ratelimit.setOverride
requestBody:
content:
application/json:
examples:
premium:
summary: Higher limit for premium user
value:
duration: 60000
identifier: premium_user_123
limit: 1000
namespace: api.requests
wildcard:
summary: Pattern for multiple identifiers
value:
duration: 60000
identifier: premium_*
limit: 500
namespace: api.requests
schema:
$ref: '#/components/schemas/V2RatelimitSetOverrideRequestBody'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/V2RatelimitSetOverrideResponseBody'
description: Override successfully created or updated and is now active.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestErrorResponse'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedErrorResponse'
description: Unauthorized
'403':
content:
application/json:
examples:
missingPermission:
summary: Missing required permission
value:
error:
detail: Your root key requires the 'ratelimit.*.set_override' permission to perform this operation
status: 403
title: Forbidden
type: forbidden
meta:
requestId: req_0uVwX4yZaAbCdEfGhIjKl
schema:
$ref: '#/components/schemas/ForbiddenErrorResponse'
description: Forbidden - Insufficient permissions (requires `ratelimit.*.set_override`)
'404':
content:
application/json:
examples:
namespaceNotFound:
summary: Namespace not found
value:
error:
detail: This namespace does not exist.
status: 404
title: Not Found
type: not_found
meta:
requestId: req_2wXyZaAbCdEfGhIjKlMnOp
schema:
$ref: '#/components/schemas/NotFoundErrorResponse'
description: Not Found - Namespace not found
'429':
content:
application/problem+json:
schema:
$ref: '#/components/schemas/TooManyRequestsErrorResponse'
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Internal Server Error
security:
- rootKey: []
summary: Set Ratelimit Override
tags:
- ratelimit
x-speakeasy-name-override: setOverride
components:
schemas:
V2RatelimitListOverridesRequestBody:
additionalProperties: false
properties:
namespace:
description: The id or name of the rate limit namespace to list overrides for.
type: string
minLength: 1
maxLength: 255
cursor:
description: Pagination cursor from a previous response. Include this when fetching subsequent pages of results. Each response containing more results than the requested limit will include a cursor value in the pagination object that can be used here.
type: string
limit:
description: 'Maximum number of override entries to return in a single response. Use this to control response size and loading performance.
- Lower values (10-20): Better for UI displays and faster response times
- Higher values (50-100): Better for data exports or bulk operations
- Default (10): Suitable for most dashboard views
Results exceeding this limit will be paginated, with a cursor provided for fetching subsequent pages.'
type: integer
default: 10
minimum: 1
maximum: 100
required:
- namespace
type: object
V2RatelimitGetOverrideResponseBody:
type: object
required:
- meta
- data
properties:
meta:
$ref: '#/components/schemas/Meta'
data:
$ref: '#/components/schemas/RatelimitOverride'
ValidationError:
additionalProperties: false
properties:
location:
description: 'JSON path indicating exactly where in the request the error occurred. This helps pinpoint the problematic field or parameter. Examples include:
- ''body.name'' (field in request body)
- ''body.items[3].tags'' (nested array element)
- ''path.apiId'' (path parameter)
- ''query.limit'' (query parameter)
Use this location to identify exactly which part of your request needs correction.'
type: string
example: body.permissions[0].name
message:
description: Detailed error message explaining what validation rule was violated. This provides specific information about why the field or parameter was rejected, such as format errors, invalid values, or constraint violations.
type: string
example: Must be at least 3 characters long
fix:
description: A human-readable suggestion describing how to fix the error. This provides practical guidance on what changes would satisfy the validation requirements. Not all validation errors include fix suggestions, but when present, they offer specific remediation advice.
type: string
example: Ensure the name uses only alphanumeric characters, underscores, and hyphens
required:
- location
- message
type: object
description: Individual validation error details. Each validation error provides precise information about what failed, where it failed, and how to fix it, enabling efficient error resolution.
Meta:
type: object
required:
- requestId
properties:
requestId:
desc
# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/unkey/refs/heads/main/openapi/unkey-ratelimit-api-openapi.yml