openapi: 3.1.0
info:
  title: Unkey analytics ratelimit API
  description: 'Unkey is an open-source developer platform for API key management, authentication, and rate limiting. This is an API Evangelist modeling of Unkey''s RPC-style REST API, grounded in Unkey''s own published OpenAPI. All operations use POST and are grouped into service namespaces (keys, apis, ratelimit, identities, permissions, analytics, deploy, liveness). The stable v2 API is served from https://api.unkey.com; the legacy v1 API is served from https://api.unkey.dev with /v1/* paths.


    Authentication uses HTTP Bearer authentication with a root key: `Authorization: Bearer unkey_xxxxxxxxxxx`. Most endpoints require specific permissions on the root key. Responses use a consistent envelope with a `meta.requestId`, a `data` object (or array plus `pagination` on list endpoints), and a structured `error` object on failures.'
  version: 2.0.0
  contact:
    name: Unkey
    url: https://www.unkey.com
  license:
    name: AGPL-3.0
    url: https://github.com/unkeyed/unkey/blob/main/LICENSE.md
servers:
- url: https://api.unkey.com
  description: Unkey v2 (current)
- url: https://api.unkey.dev
  description: Unkey v1 (legacy)
security:
- rootKey: []
tags:
- name: ratelimit
  description: Standalone rate limiting and override operations.
paths:
  /v2/ratelimit.limit:
    post:
      operationId: ratelimit.limit
      tags:
      - ratelimit
      summary: Ratelimit
      description: Checks and enforces a rate limit for an identifier within a namespace. Returns whether the request is allowed plus remaining, limit, and reset. Works standalone, without an API key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/ratelimit.multiLimit:
    post:
      operationId: ratelimit.multiLimit
      tags:
      - ratelimit
      summary: Multi ratelimit
      description: Evaluates several rate limits in a single request and returns the combined result.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/ratelimit.setOverride:
    post:
      operationId: ratelimit.setOverride
      tags:
      - ratelimit
      summary: Set ratelimit override
      description: Sets a per-identifier override of the limit and duration within a namespace.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/ratelimit.getOverride:
    post:
      operationId: ratelimit.getOverride
      tags:
      - ratelimit
      summary: Get ratelimit override
      description: Retrieves a rate limit override for an identifier in a namespace.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v2/ratelimit.listOverrides:
    post:
      operationId: ratelimit.listOverrides
      tags:
      - ratelimit
      summary: List ratelimit overrides
      description: Lists the rate limit overrides configured in a namespace, with cursor pagination.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/PaginatedSuccess'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/ratelimit.deleteOverride:
    post:
      operationId: ratelimit.deleteOverride
      tags:
      - ratelimit
      summary: Delete ratelimit override
      description: Deletes a rate limit override for an identifier in a namespace.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Unauthorized:
      description: Missing or invalid root key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Success:
      description: Successful response using the standard Unkey envelope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SuccessEnvelope'
    BadRequest:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    PaginatedSuccess:
      description: Successful list response with cursor pagination.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaginatedEnvelope'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  schemas:
    PaginatedEnvelope:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          type: array
          items:
            type: object
            additionalProperties: true
        pagination:
          $ref: '#/components/schemas/Pagination'
    ErrorEnvelope:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        error:
          type: object
          properties:
            title:
              type: string
              description: Human-readable error summary.
            detail:
              type: string
              description: Specific description of what went wrong.
            status:
              type: integer
              description: HTTP status code.
            type:
              type: string
              format: uri
              description: Link to error documentation.
            errors:
              type: array
              description: Array of validation errors (for 400 responses).
              items:
                type: object
                additionalProperties: true
    GenericRequest:
      type: object
      description: Request body for an RPC-style operation. The concrete fields depend on the operation (for example keyId, apiId, key, namespace, identifier, externalId, permissions, roles). See the Unkey API reference for the per-operation schema.
      additionalProperties: true
    SuccessEnvelope:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/Meta'
        data:
          type: object
          additionalProperties: true
    Meta:
      type: object
      properties:
        requestId:
          type: string
          description: Unique identifier for this request, useful for support and tracing.
    Pagination:
      type: object
      properties:
        cursor:
          type: string
          description: Token for requesting the next page.
        hasMore:
          type: boolean
          description: Whether more results are available.
  securitySchemes:
    rootKey:
      type: http
      scheme: bearer
      description: 'HTTP Bearer authentication with an Unkey root key, passed as `Authorization: Bearer unkey_xxxxxxxxxxx`. Most endpoints require specific permissions on the root key.'