Kaminari Ad Billing API

openapi: 3.2.0
info:
  title: Kaminari Ad Billing API
  description: 'REST API for Kaminari Ad, the ad quality and ad security platform for publishers, ad networks, SSPs and DSPs. Submit ad creatives, ad tags and landing pages for scanning, read verdicts with evidence, manage policies, alerts and webhooks.


    Authenticate with an API key as a Bearer token: https://kaminari.ad/docs/developers/authentication'
  contact:
    name: Kaminari Ad Support
    url: https://kaminari.ad/contact
    email: support@kaminari.ad
  version: 0.1.0
servers:
- url: https://app.kaminari.ad
tags:
- name: Billing
paths:
  /api/v1/billing:
    get:
      tags:
      - Billing
      summary: Get Billing Summary
      description: Get billing summary for caller's organization.
      operationId: get_billing_summary_api_v1_billing_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingSummaryResponse'
      security:
      - HTTPBearer: []
  /api/v1/billing/usage:
    get:
      tags:
      - Billing
      summary: List Usage
      description: List usage records for caller's organization.
      operationId: list_usage_api_v1_billing_usage_get
      security:
      - HTTPBearer: []
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Page
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: date_from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Date From
      - name: date_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Date To
      - name: scan_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Scan Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_UsageResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/billing/usage/summary:
    get:
      tags:
      - Billing
      summary: Get Usage Summary
      description: Return a one-line aggregate of caller-org usage over the current period.
      operationId: get_usage_summary_api_v1_billing_usage_summary_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsagePeriodSummaryResponse'
      security:
      - HTTPBearer: []
  /api/v1/billing/history:
    get:
      tags:
      - Billing
      summary: List Balance History
      description: Return caller-org balance history (ledger rows) with filters + pagination.
      operationId: list_balance_history_api_v1_billing_history_get
      security:
      - HTTPBearer: []
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Page
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: date_from
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Date From
      - name: date_to
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Date To
      - name: type
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              $ref: '#/components/schemas/BalanceTransactionType'
          - type: 'null'
          title: Type
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_BalanceTransactionResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    BillingSummaryResponse:
      properties:
        balance_micros:
          type: integer
          title: Balance Micros
        plan_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Plan Name
        plan_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Plan Id
        checks_per_period:
          anyOf:
          - type: integer
          - type: 'null'
          title: Checks Per Period
        checks_used:
          anyOf:
          - type: integer
          - type: 'null'
          title: Checks Used
        period_start:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Period Start
        period_end:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Period End
        price_per_extra_check_micros:
          anyOf:
          - type: integer
          - type: 'null'
          title: Price Per Extra Check Micros
        current_plan_is_custom:
          type: boolean
          title: Current Plan Is Custom
          default: false
        is_suspended:
          type: boolean
          title: Is Suspended
          default: false
        scheduled_next_plan_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Scheduled Next Plan Id
        scheduled_next_plan_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Scheduled Next Plan Name
        scheduled_effective_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Scheduled Effective At
        can_create_scan:
          type: boolean
          title: Can Create Scan
          default: true
        block_reason:
          anyOf:
          - $ref: '#/components/schemas/BlockReason'
          - type: 'null'
        billing_mode:
          type: string
          title: Billing Mode
          default: prepaid
        credit_limit_micros:
          type: integer
          title: Credit Limit Micros
          default: 0
        effective_minimum_balance_micros:
          type: integer
          title: Effective Minimum Balance Micros
          default: 0
      type: object
      required:
      - balance_micros
      - plan_name
      - plan_id
      - checks_per_period
      - checks_used
      - period_start
      - period_end
      - price_per_extra_check_micros
      title: BillingSummaryResponse
      description: Aggregated billing state for an organization.
    PaginatedResponse_UsageResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/UsageResponse'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        limit:
          type: integer
          title: Limit
        pages:
          type: integer
          title: Pages
      type: object
      required:
      - items
      - total
      - page
      - limit
      - pages
      title: PaginatedResponse[UsageResponse]
    UsageResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        scan_id:
          type: string
          format: uuid
          title: Scan Id
        charged_micros:
          type: integer
          title: Charged Micros
        balance_after_micros:
          type: integer
          title: Balance After Micros
        within_plan:
          type: boolean
          title: Within Plan
        event_type:
          type: string
          title: Event Type
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - scan_id
      - charged_micros
      - balance_after_micros
      - within_plan
      - event_type
      - created_at
      title: UsageResponse
      description: Single usage record in API response.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    UsagePeriodSummaryResponse:
      properties:
        period_start:
          type: string
          format: date-time
          title: Period Start
        period_end:
          type: string
          format: date-time
          title: Period End
        checks:
          type: integer
          title: Checks
        rechecks:
          type: integer
          title: Rechecks
        within_plan:
          type: integer
          title: Within Plan
        overage:
          type: integer
          title: Overage
        charged_micros:
          type: integer
          title: Charged Micros
      type: object
      required:
      - period_start
      - period_end
      - checks
      - rechecks
      - within_plan
      - overage
      - charged_micros
      title: UsagePeriodSummaryResponse
      description: One-line aggregate of usage events in the window (`[start, end)`).
    BalanceTransactionType:
      type: string
      enum:
      - initial_balance
      - top_up_manual
      - usage_charge
      - subscription_renewal
      - subscription_upgrade
      - admin_adjustment
      - refund
      - invoice_settlement
      - invoice_payment_adjustment
      - crypto_top_up
      - card_top_up
      title: BalanceTransactionType
      description: 'What kind of balance motion generated this ledger row.


        The ledger is append-only. Every motion that changes

        ``balances.amount_micros`` MUST produce exactly one row of one of

        the variants below. Signed ``amount`` decides direction (positive

        credits the org, negative debits it).'
    BlockReason:
      type: string
      enum:
      - no_subscription
      - suspended
      - insufficient_funds
      title: BlockReason
      description: Why a scan admission decision came back ``allowed=False``.
    BalanceTransactionResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        type:
          type: string
          title: Type
        amount_micros:
          type: integer
          title: Amount Micros
        balance_after_micros:
          type: integer
          title: Balance After Micros
        description:
          type: string
          title: Description
        reference_kind:
          anyOf:
          - type: string
          - type: 'null'
          title: Reference Kind
        reference_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Reference Id
        document_number:
          anyOf:
          - type: string
          - type: 'null'
          title: Document Number
        actor_user_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Actor User Id
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - type
      - amount_micros
      - balance_after_micros
      - description
      - reference_kind
      - reference_id
      - actor_user_id
      - created_at
      title: BalanceTransactionResponse
      description: 'One ledger row as seen through the API.


        ``document_number`` is the unified top-up proforma number

        (``PF-YYYY-NNNNNN``) — the single human-readable identifier shown

        on the INXY statement, in the cabinet, in admin, and on the

        paid-proforma receipt PDF. Populated via the read-side port

        :class:`BalanceHistoryQueryService` (cross-domain JOIN to

        ``invoices``, directly for bank and via ``payment_sessions`` for

        crypto). ``None`` for non-top-up rows (scan charges, subscription

        renewals) and legacy crypto sessions issued before the unified

        model.'
    PaginatedResponse_BalanceTransactionResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/BalanceTransactionResponse'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        limit:
          type: integer
          title: Limit
        pages:
          type: integer
          title: Pages
      type: object
      required:
      - items
      - total
      - page
      - limit
      - pages
      title: PaginatedResponse[BalanceTransactionResponse]
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer