openapi: 3.1.0
info:
  title: Unkey analytics apis 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: apis
  description: API (namespace) management operations.
paths:
  /v2/apis.createApi:
    post:
      operationId: apis.createApi
      tags:
      - apis
      summary: Create an API
      description: Creates a new API (namespace / keyspace) that keys are issued into and verified against.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenericRequest'
      responses:
        '200':
          $ref: '#/components/responses/Success'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/apis.getApi:
    post:
      operationId: apis.getApi
      tags:
      - apis
      summary: Get an API
      description: Retrieves an API (namespace) by its apiId.
      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/apis.deleteApi:
    post:
      operationId: apis.deleteApi
      tags:
      - apis
      summary: Delete an API
      description: Deletes an API namespace and, depending on settings, its keys.
      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/apis.listKeys:
    post:
      operationId: apis.listKeys
      tags:
      - apis
      summary: List keys for an API
      description: Lists the keys belonging to an API 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'
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'
    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.'