openapi: 3.1.0
info:
  title: Mixedbread admin billing API
  version: 0.1.0
  description: Mixedbread admin endpoints extracted from the canonical OpenAPI spec at https://api.mixedbread.com/openapi.json
servers:
- url: https://api.mixedbread.com
  description: mixedbread ai production server
- url: https://api.dev.mixedbread.com
  description: mixedbread ai development server
- url: http://127.0.0.1:8000
  description: mixedbread local server
- url: http://localhost:8000
  description: mixedbread local server
tags:
- name: billing
paths:
  /v1/billing/summary:
    get:
      tags:
      - billing
      summary: Get billing summary
      operationId: get_billing_summary
      responses:
        '200':
          description: Billing summary for the current period
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPeriodSummary'
      security:
      - ApiKeyAuth: []
  /v1/billing/stores:
    get:
      tags:
      - billing
      summary: List store cost information
      operationId: list_store_cost_info
      responses:
        '200':
          description: The list of store cost information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreCostListResponse'
      security:
      - ApiKeyAuth: []
  /v1/billing/stores/{store_id}/costs/histogram:
    get:
      tags:
      - billing
      summary: Get store cost histogram
      operationId: get_store_cost_histogram
      security:
      - ApiKeyAuth: []
      parameters:
      - name: store_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: The ID of the store
          title: Store Id
        description: The ID of the store
      responses:
        '200':
          description: Histogram of store costs over time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostHistogramResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/billing/parsing/costs/histogram:
    get:
      tags:
      - billing
      summary: Get parsing cost histogram
      operationId: get_parsing_cost_histogram
      responses:
        '200':
          description: Histogram of parsing costs over time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CostHistogramResponse'
      security:
      - ApiKeyAuth: []
components:
  schemas:
    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
    ProductCostInfo:
      properties:
        product_name:
          type: string
          title: Product Name
          description: The name of the product. Store, Parsing, Reranking, Embeddings
        gross_usage_cost:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Gross Usage Cost
          description: The gross usage cost of the product
        net_usage_cost:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Net Usage Cost
          description: The net usage cost of the product
        balance_applied:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Balance Applied
          description: The balance applied to the product
      type: object
      required:
      - product_name
      - gross_usage_cost
      - net_usage_cost
      - balance_applied
      title: ProductCostInfo
      description: Cost information for a product.
    CostHistogramResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/DailyCostBucket'
          type: array
          title: Data
          description: The histogram of cost information
        object:
          type: string
          const: cost.histogram
          title: Object
          description: The object type of the response
          default: cost.histogram
      type: object
      required:
      - data
      title: CostHistogramResponse
    UsageInfo:
      properties:
        current:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Current
          description: The current usage of the resource
          default: '0'
        limit:
          anyOf:
          - type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          - type: 'null'
          title: Limit
          description: The limit of the resource
        unit:
          type: string
          title: Unit
          description: The unit of the resource
          default: ''
      type: object
      title: UsageInfo
      description: Resource usage information.
    BalanceInfo:
      properties:
        current_balance:
          type: number
          title: Current Balance
          description: The current balance
        next_effective_balance:
          type: number
          title: Next Effective Balance
          description: The next effective balance
        next_effective_date:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Next Effective Date
          description: The next effective date
      type: object
      title: BalanceInfo
      description: Information about an organization's credit balance.
    Period:
      properties:
        start:
          type: string
          format: date-time
          title: Start
          description: The start of the billing period
        end:
          type: string
          format: date-time
          title: End
          description: The end of the billing period
      type: object
      required:
      - start
      - end
      title: Period
      description: Inclusive/exclusive window describing a billing period.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CostInfo:
      properties:
        net_usage_cost:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Net Usage Cost
          description: The net usage cost
          default: '0'
        gross_usage_cost:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Gross Usage Cost
          description: The gross usage cost
          default: '0'
        balance_applied:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Balance Applied
          description: The balance applied
          default: '0'
        phases:
          items:
            $ref: '#/components/schemas/PhaseCostInfo'
          type: array
          title: Phases
          description: The cost for each phase in descending order of end date
          default: []
        products:
          items:
            $ref: '#/components/schemas/ProductCostInfo'
          type: array
          title: Products
          description: The cost for each product. Store, Parsing, Reranking, Embeddings
          default: []
      type: object
      title: CostInfo
      description: "Cost information for a billing period.\n\n- net_usage_cost: portion of usage that actually ends up on the invoice after credits,\n    computed as gross_usage_cost - balance_applied.\n- gross_usage_cost: metered usage value before balance applied."
    StoreCostListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/StoreCostInfo'
          type: array
          title: Data
          description: The list of store cost information
        object:
          type: string
          const: list
          title: Object
          description: The object type of the response
          default: list
      type: object
      required:
      - data
      title: StoreCostListResponse
    DailyCostBucket:
      properties:
        day:
          type: string
          format: date-time
          title: Day
          description: The date of the cost bucket
        cost:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Cost
          description: The cost of the cost bucket
        cost_per_metric:
          additionalProperties:
            type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          type: object
          title: Cost Per Metric
          description: The cost per metric
      type: object
      required:
      - day
      - cost
      - cost_per_metric
      title: DailyCostBucket
      description: Daily cost bucket.
    StoreCostInfo:
      properties:
        store_id:
          type: string
          title: Store Id
          description: The ID of the store
        cost:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Cost
          description: The cost
        cost_per_metric:
          additionalProperties:
            type: string
            pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          type: object
          title: Cost Per Metric
          description: The cost per metric
      type: object
      required:
      - store_id
      - cost
      - cost_per_metric
      title: StoreCostInfo
      description: Cost information for a store.
    BillingPeriodSummary:
      properties:
        period:
          $ref: '#/components/schemas/Period'
          description: The billing period
        cost:
          $ref: '#/components/schemas/CostInfo'
          description: The cost information
        balance:
          $ref: '#/components/schemas/BalanceInfo'
          description: The balance information
        usages:
          additionalProperties:
            $ref: '#/components/schemas/UsageInfo'
          type: object
          title: Usages
          description: The monthly usages information per metric
        generated_at:
          type: string
          format: date-time
          title: Generated At
          description: The date and time the summary was generated
      type: object
      required:
      - period
      - cost
      - balance
      - usages
      - generated_at
      title: BillingPeriodSummary
      description: High level billing summary for the currently active period.
    PhaseCostInfo:
      properties:
        period:
          $ref: '#/components/schemas/Period'
          description: The period
        net_usage_cost:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Net Usage Cost
          description: The net usage cost
        gross_usage_cost:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Gross Usage Cost
          description: The gross usage cost
        balance_applied:
          type: string
          pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
          title: Balance Applied
          description: The balance applied
      type: object
      required:
      - period
      - net_usage_cost
      - gross_usage_cost
      - balance_applied
      title: PhaseCostInfo
      description: Cost information for a billing phase.
  securitySchemes:
    ApiKeyAuth:
      type: http
      description: Api key to access Mixedbreads API
      scheme: bearer