Arkova Usage API

openapi: 3.2.0
info:
  title: Arkova Verification Usage API
  version: 1.0.1
  description: Programmatic credential verification API. Verify credentials anchored on the Bitcoin network. Worker-generated v1 JSON errors expose common top-level code and message fields. The legacy error field is retained unchanged (string or object), along with details and quota context, for existing integrations. Parse code and message for new integrations. Upstream gateway errors may not be JSON. Revision 1.0.1 restores legacy label and DIPLOMA inputs and clarifies receipts and webhook payloads; the endpoint version remains v1.
  contact:
    name: Arkova Support
    url: https://arkova.ai
servers:
- url: /api/v1
  description: Verification API v1
security:
- ApiKeyBearer: []
- ApiKeyHeader: []
tags:
- name: Usage
  description: API usage and quota monitoring
paths:
  /usage:
    get:
      summary: Get API usage
      description: 'Returns current month''s API usage and allowance terms. By default, organization callers see org usage: an API key or JWT owner/admin sees every active org key; a JWT member sees the org total and assigned keys. A JWT caller may use context=personal to see their own retained personal usage even after joining an organization. Personal API keys always see their owner''s personal usage; organization API keys cannot request personal context. For orgs, `capped` plans refuse requests above the included amount and `metered` plans accrue $0.002 overage per query, invoiced after the month closes. `overage_reported_to_stripe` is retained for compatibility and is always false for the current month.'
      operationId: getUsage
      tags:
      - Usage
      x-arkova-required-scopes:
      - usage:read
      security:
      - ApiKeyBearer: []
      - ApiKeyHeader: []
      - SupabaseJWT: []
      parameters:
      - name: X-Org-Id
        in: header
        required: false
        schema:
          type: string
          format: uuid
        description: Exact selected organization. Requires current membership there; never falls back to the profile organization. Cannot be combined with context=personal.
      - name: context
        in: query
        schema:
          type: string
          enum:
          - personal
        description: For Supabase JWT callers, select owner-scoped personal usage instead of default organization usage.
      responses:
        '200':
          description: Usage statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    UsageResponse:
      type: object
      required:
      - used
      - limit
      - remaining
      - reset_date
      - month
      - keys
      - allowance
      properties:
        used:
          type: integer
        limit:
          oneOf:
          - type: integer
          - type: string
            enum:
            - unlimited
        remaining:
          oneOf:
          - type: integer
          - type: string
            enum:
            - unlimited
        reset_date:
          type: string
          format: date-time
        month:
          type: string
          pattern: ^\d{4}-\d{2}$
        keys:
          type: array
          items:
            type: object
            properties:
              key_prefix:
                type: string
              name:
                type: string
              used:
                type: integer
        allowance:
          type: object
          description: 'UAT-21: monthly allowance and overage terms for the organization.'
          required:
          - included_monthly_queries
          - plan
          - overage_unit_price_usd
          - overage_queries
          - overage_reported_to_stripe
          properties:
            included_monthly_queries:
              type: integer
              example: 1000
            plan:
              type: string
              enum:
              - capped
              - metered
              - unmetered
            overage_unit_price_usd:
              type: number
              example: 0.002
            overage_queries:
              type: integer
              description: Queries above the included allowance this month (metered plan only).
            overage_reported_to_stripe:
              type: boolean
              description: Retained for v1 compatibility. Overage is sent to Stripe only after the month closes, so this is always false for the current month. It is never proof of an invoice charge.
            overage_approval_required:
              type: boolean
              description: 'True for a paying organization with no active overage approval: requests stop at the included queries (plan is capped, limit is the included allowance) until an organization owner or admin approves overage.'
        viewer:
          type: string
          enum:
          - admin
          - member
          description: Signed-in callers only.
    ApiError:
      type: object
      required:
      - error
      properties:
        error:
          oneOf:
          - type: string
          - type: object
            additionalProperties: true
            properties:
              code:
                type: string
              message:
                type: string
        code:
          type: string
          description: Common machine-readable error code; legacy error remains unchanged.
        message:
          type: string
  responses:
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      description: 'API key as Bearer token: `Authorization: Bearer ak_live_...`'
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'API key via header: `X-API-Key: ak_live_...`'
    SupabaseJWT:
      type: http
      scheme: bearer
      description: Supabase JWT for key management endpoints