openapi: 3.2.0
info:
  title: Compabase Usage API
  version: 1.0.0
  description: '### Introduction

    Versioned JSON API for Polish company data: KRS search and full profiles, CEIDG (sole

    proprietors) by NIP, financial statements and document inventory, peer statistics,

    company connections, news/UGC, Warsaw Stock Exchange (GPW) listings, and watchlist management.'
servers:
- url: https://compabase.com/api/v1
  description: Full URL
tags:
- name: Usage
paths:
  /usage:
    get:
      tags:
      - Usage
      summary: Monthly quota usage for this API key
      description: 'Returns how many requests this key has used in the current UTC calendar month against its limit.

        This endpoint does not consume quota (usage counter is not incremented).'
      security:
      - ApiKeyAuth: []
      - BearerAuth: []
      responses:
        '200':
          description: Usage snapshot
          content:
            application/json:
              schema:
                type: object
                required:
                - used
                - limit
                - remaining
                - monthUtc
                - resetsAtUtc
                properties:
                  used:
                    type: integer
                  limit:
                    type: integer
                  remaining:
                    type: integer
                  monthUtc:
                    type: string
                    description: Current billing period date (ISO 8601 date).
                    example: '2026-08-31'
                  resetsAtUtc:
                    type: string
                    format: date-time
                    description: When the billing period resets (ISO 8601 datetime with timezone).
                    example: '2026-09-01T00:00:00+00:00'
        '401':
          $ref: '#/components/responses/Unauthorized'
      operationId: getUsage
      x-operation-id-source: derived
components:
  schemas:
    ErrorResponse:
      type: object
      required:
      - statusCode
      - statusMessage
      - message
      properties:
        statusCode:
          type: integer
          description: HTTP status code.
        statusMessage:
          type: string
          description: HTTP status text.
        message:
          type: string
          description: Short error summary (same as statusMessage for most errors).
        data:
          type: object
          description: Domain error payload set by the handler.
          properties:
            message:
              type: string
              description: Human-readable message (used by 401 responses).
            error:
              type: object
              description: Structured domain error (used by 400/404/429 responses).
              properties:
                code:
                  type: string
                  description: Machine-readable domain error code.
                  enum:
                  - INVALID_KRS
                  - INVALID_NIP
                  - INVALID_CURSOR
                  - INVALID_RANGE
                  - INVALID_PARAMETER
                  - CONFLICTING_PARAMETERS
                  - INVALID_BOOLEAN
                  - INVALID_KEYWORDS
                  - INVALID_API_KEY
                  - UNAUTHORIZED
                  - NOT_FOUND
                  - QUOTA_EXCEEDED
                message:
                  type: string
                details:
                  type: object
                  additionalProperties: true
  responses:
    Unauthorized:
      description: Missing, invalid, or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            statusCode: 401
            statusMessage: Unauthorized
            message: Unauthorized
            data:
              message: Missing or invalid API key.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer