openapi: 3.2.0
info:
  description: 'The Sybilion API powers the Sybilion Developers Portal: forecasts, drivers, catalog, account

    and usage. Authenticate every request with `Authorization: Bearer <token>` using either an

    API key created in the Developers Portal or an Auth0 access token from your dashboard session.

    '
  title: Sybilion Usage API
  version: 0.1.0
servers:
- url: /
tags:
- name: Usage
paths:
  /api/v1/usage:
    get:
      description: 'Returns billing history as a paginated list of usage events. Each event

        represents one charge — either a completed async job or a synchronous billed

        API call. Use `sort` and `order` to control the result order.

        '
      parameters:
      - description: 1-indexed page number.
        in: query
        name: page
        required: false
        schema:
          default: 1
          minimum: 1
          type: integer
      - description: Page size. Capped at 200.
        in: query
        name: limit
        required: false
        schema:
          default: 50
          maximum: 200
          minimum: 1
          type: integer
      - description: Column to sort by.
        in: query
        name: sort
        required: false
        schema:
          default: id
          enum:
          - id
          - created_at
          - eur_cents_charged
          - credits_charged
          - units
          type: string
      - description: Sort direction.
        in: query
        name: order
        required: false
        schema:
          default: desc
          enum:
          - asc
          - desc
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                pagination:
                  page: 1
                  limit: 50
                  total: 2
                  total_pages: 1
                  sort: id
                  order: desc
                usage_events:
                - id: 8471
                  endpoint: drivers
                  units: 20
                  credits_charged: 22
                  eur_cents_charged: 22
                  created_at: '2026-05-24T14:32:10Z'
                  async_job_id: null
                - id: 8320
                  endpoint: forecast
                  units: 1
                  credits_charged: 250
                  eur_cents_charged: 250
                  created_at: '2026-05-01T10:04:32Z'
                  async_job_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
              schema:
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  usage_events:
                    items:
                      $ref: '#/components/schemas/UsageEvent'
                    type: array
                required:
                - usage_events
                - pagination
                type: object
          description: Paginated billing history.
        '400':
          description: Invalid query parameter — bad `page`, `limit`, `sort`, or `order` value.
        '401':
          description: Missing or invalid bearer token.
      security:
      - bearerAuth: []
      summary: Billing history (paginated usage events)
      tags:
      - Usage
components:
  schemas:
    Pagination:
      properties:
        limit:
          description: Page size echoed back from the request.
          maximum: 200
          minimum: 1
          type: integer
        order:
          description: Sort direction.
          enum:
          - asc
          - desc
          type: string
        page:
          description: 1-indexed current page number echoed back from the request.
          minimum: 1
          type: integer
        sort:
          description: Column the rows are sorted by.
          enum:
          - id
          - created_at
          - eur_cents_charged
          - credits_charged
          - units
          type: string
        total:
          description: Total matching rows for the authenticated user (full set, not just this page).
          format: int64
          minimum: 0
          type: integer
        total_pages:
          description: ceil(total / limit). Zero when total is zero.
          format: int64
          minimum: 0
          type: integer
      required:
      - page
      - limit
      - total
      - total_pages
      - sort
      - order
      type: object
    UsageEvent:
      description: A single billing charge, corresponding to one API call or one completed async job.
      example:
        id: 8471
        endpoint: drivers
        units: 20
        credits_charged: 22
        eur_cents_charged: 22
        created_at: '2026-05-24T14:32:10Z'
        async_job_id: null
      properties:
        async_job_id:
          description: The `async_jobs.id` (UUID) for async pipeline charges; null for synchronous endpoint charges.
          format: uuid
          type:
          - string
          - 'null'
        created_at:
          description: Timestamp of the charge (ISO 8601).
          type: string
        credits_charged:
          description: Whole credits debited for this row before EUR conversion.
          format: int64
          type: integer
        endpoint:
          description: Billing route key (e.g. `drivers`, `alerts`, or a forecast pipeline type).
          type: string
        eur_cents_charged:
          description: EUR cents debited for this row (1 EUR = 100 cents).
          format: int64
          type: integer
        id:
          description: Auto-increment row identifier.
          format: int64
          type: integer
        units:
          description: Metered quantity — item count for per-unit pricing, 1 for flat-fee strategies.
          format: int64
          type: integer
      required:
      - id
      - units
      - credits_charged
      - eur_cents_charged
      - created_at
      type: object
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http