openapi: 3.1.0
info:
  title: Datablist Credits API
  version: 1.0.0
  description: Read your account's aggregate available credits.
servers:
  - url: https://api.datablist.com
security:
  - apiKeyAuth: []
  - bearerAuth: []
tags:
  - name: Credits
    description: Monthly allocation and top-up credits shared with the Datablist app.
paths:
  /v1/credits/balance:
    get:
      operationId: getCreditBalance
      summary: Get credit balance
      tags: [Credits]
      x-required-scopes: [credits:read]
      description: |
        Call `GET https://api.datablist.com/v1/credits/balance` with
        `X-API-Key: PERSONAL_API_KEY` or `Authorization: Bearer ACCESS_TOKEN`.

        Get the aggregate credits available to the account identified by your
        access token. No account ID, workspace or collection is required.

        Received usage logs are reconciled before the response. Usage events
        still in transit are not reflected yet. Monthly allocation credits are
        consumed first, then top-up credits. Late-arriving logs consume the
        active allocation. This read does not reserve credits or guarantee that
        a subsequent task can spend the displayed balance.

        All amounts are decimal strings, with up to nine decimal places. The
        response contains no credits JWT. Completed top-ups appear after their
        normal settlement; this endpoint does not initiate or settle purchases.
        The token requires `credits:read` or account-wide `admin` scope.
      responses:
        '200':
          description: Aggregate balance after reconciling received usage.
          headers:
            Cache-Control:
              schema: {type: string, const: no-store}
            X-Request-ID:
              description: Request identifier for support and tracing.
              schema: {type: string}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/CreditBalance'}
              example:
                remainingCredits: '12500.5'
                monthlyBalanceRemainingCredits: '10000'
                balanceRemainingCredits: '2500.5'
        '400':
          description: Both X-API-Key and Authorization were supplied.
        '401':
          description: Missing, invalid or expired access token.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ApiError'}
        '403':
          description: The access token does not allow reading account credits.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ApiError'}
        '503':
          description: Balance reconciliation is temporarily unavailable. Retry later; no stale balance is returned.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ApiError'}
              example:
                http_status: 503
                code: ServiceUnavailable
                description: Credit usage changed; retry later.
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Personal API Key. Datablist handles token exchange and renewal. Send either this header or Authorization, not both.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Exchange your Personal API Key at POST /v1/account/token.
  schemas:
    CreditBalance:
      type: object
      additionalProperties: false
      required: [remainingCredits, monthlyBalanceRemainingCredits, balanceRemainingCredits]
      properties:
        remainingCredits:
          type: string
          pattern: '^[0-9]+(?:\.[0-9]{1,9})?$'
          description: Monthly allocation plus top-up credits currently available.
        monthlyBalanceRemainingCredits:
          type: string
          pattern: '^[0-9]+(?:\.[0-9]{1,9})?$'
          description: Credits remaining in the active allocation, consumed first.
        balanceRemainingCredits:
          type: string
          pattern: '^[0-9]+(?:\.[0-9]{1,9})?$'
          description: Settled top-up credits remaining.
    ApiError:
      type: object
      required: [http_status, code, description]
      properties:
        http_status: {type: integer}
        code: {type: string}
        description: {type: string}
        trace_id: {type: string}