openapi: 3.0.3
info:
  title: Octane REST Admin Meters API
  description: REST API for managing meters, customers, pricing plans, subscriptions, measurements, and real-time usage data for usage-based billing workflows. Octane enables infrastructure and SaaS companies to implement flexible pay-as-you-go billing similar to Snowflake and AWS.
  version: 1.0.0
  contact:
    name: Octane Support
    url: https://www.getoctane.io
servers:
- url: https://api.getoctane.io
  description: Octane Production API
security:
- BearerApiKeyAuth: []
tags:
- name: Meters
  description: Manage usage meters that track events and aggregate data
paths:
  /meters:
    get:
      summary: Get Meters
      description: Get all meters for a given vendor.
      operationId: metersGet
      tags:
      - Meters
      responses:
        '200':
          description: List of meters
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Meter'
    post:
      summary: Create Meter
      description: Create a new usage meter.
      operationId: metersPost
      tags:
      - Meters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMeterArgs'
      responses:
        '200':
          description: Created meter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Meter'
  /meters/{meter_name}:
    get:
      summary: Get Meter
      description: Get a meter by its unique name.
      operationId: metersMeterNameGet
      tags:
      - Meters
      parameters:
      - name: meter_name
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Meter details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Meter'
    put:
      summary: Update Meter
      description: Update a meter by its unique name.
      operationId: metersMeterNamePut
      tags:
      - Meters
      parameters:
      - name: meter_name
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMeterArgs'
      responses:
        '200':
          description: Updated meter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Meter'
    delete:
      summary: Delete Meter
      description: Delete a meter by its unique name.
      operationId: metersMeterNameDelete
      tags:
      - Meters
      parameters:
      - name: meter_name
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Meter deleted
  /meters/{meter_name}/archive:
    post:
      summary: Archive Meter
      description: Archive a meter by its unique name.
      operationId: metersMeterNameArchivePost
      tags:
      - Meters
      parameters:
      - name: meter_name
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Meter archived
components:
  schemas:
    Meter:
      type: object
      required:
      - name
      - event_name
      - meter_type
      - data_type
      - aggregation
      - is_incremental
      - reporting_method
      properties:
        name:
          type: string
          description: Unique identifier name for the meter.
        display_name:
          type: string
          description: Human-readable display name for the meter.
        description:
          type: string
          description: Description of what this meter tracks.
        event_name:
          type: string
          description: The event name this meter listens to.
        meter_type:
          type: string
          description: Type of meter (e.g., counter, gauge).
        data_type:
          type: string
          enum:
          - INT
          - FLOAT
          - STRING
          description: Data type of the measurement value.
        aggregation:
          type: string
          enum:
          - SUM
          - COUNT
          - MAX
          - MIN
          - UNIQUE_COUNT
          description: Aggregation method applied to measurements.
        unit_name:
          type: string
          description: Human-readable unit name (e.g., "API calls", "GB").
        is_incremental:
          type: boolean
          description: Whether measurements are incremental or absolute.
        reporting_method:
          type: string
          enum:
          - periodic
          - total
          description: How usage is reported.
        expected_labels:
          type: array
          items:
            type: string
          description: Expected label keys on measurements.
        primary_labels:
          type: array
          items:
            type: string
          description: Primary label keys used for grouping.
        event_label_filter:
          type: object
          description: Filter expression for event labels.
    UpdateMeterArgs:
      type: object
      properties:
        description:
          type: string
          description: Updated description for the meter.
        display_name:
          type: string
          description: Updated display name for the meter.
    CreateMeterArgs:
      type: object
      properties:
        name:
          type: string
          description: Unique name for the meter.
        display_name:
          type: string
          description: Human-readable display name.
        description:
          type: string
          description: Description of the meter.
        event_name:
          type: string
          description: Event name this meter tracks.
        meter_type:
          type: string
          description: Type of meter.
        data_type:
          type: string
          enum:
          - INT
          - FLOAT
          - STRING
        aggregation:
          type: string
          enum:
          - SUM
          - COUNT
          - MAX
          - MIN
          - UNIQUE_COUNT
        unit_name:
          type: string
        is_incremental:
          type: boolean
        reporting_method:
          type: string
          enum:
          - periodic
          - total
        expected_labels:
          type: array
          items:
            type: string
        primary_labels:
          type: array
          items:
            type: string
        event_label_filter:
          type: object
  securitySchemes:
    BearerApiKeyAuth:
      type: http
      scheme: bearer
      description: API key passed as a Bearer token in the Authorization header.