openapi: 3.0.1
info:
  title: Bayou Energy API
  description: >-
    REST API for collecting utility account, bill, and interval meter data on
    behalf of customers. Create a customer, have them connect their utility
    credentials through a hosted onboarding link, then retrieve bills and
    interval usage data. Authentication uses HTTP Basic with your API key as the
    username and an empty password.
  termsOfService: https://www.bayou.energy/
  contact:
    name: Bayou Energy Support
    url: https://docs.bayou.energy/
  version: '2.0'
servers:
  - url: https://bayou.energy/api/v2
security:
  - basicAuth: []
paths:
  /customers:
    get:
      operationId: listCustomers
      tags:
        - Customers
      summary: List customers
      description: Retrieve the list of customers created on your account.
      responses:
        '200':
          description: A list of customers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Customer'
    post:
      operationId: createCustomer
      tags:
        - Customers
      summary: Create a customer
      description: >-
        Create a customer for a given utility. The response includes an
        onboarding link the customer uses to connect their utility credentials.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
      responses:
        '201':
          description: The created customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
  /customers/{id}:
    get:
      operationId: getCustomer
      tags:
        - Customers
      summary: Retrieve a customer
      description: >-
        Retrieve a customer, including status fields such as
        has_filled_credentials, bills_are_ready, and intervals_are_ready.
      parameters:
        - $ref: '#/components/parameters/CustomerId'
      responses:
        '200':
          description: The requested customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
    patch:
      operationId: updateCustomer
      tags:
        - Customers
      summary: Update a customer
      description: Update a customer's attributes.
      parameters:
        - $ref: '#/components/parameters/CustomerId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerRequest'
      responses:
        '200':
          description: The updated customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
  /customers/{id}/bills:
    get:
      operationId: getCustomerBills
      tags:
        - Bills
      summary: Retrieve a customer's bills
      description: >-
        Retrieve all bills discovered for a customer. Poll until the customer's
        bills_are_ready flag is true, or subscribe to the bills_ready webhook.
      parameters:
        - $ref: '#/components/parameters/CustomerId'
      responses:
        '200':
          description: The customer's bills.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Bill'
  /customers/{id}/intervals:
    get:
      operationId: getCustomerIntervals
      tags:
        - Intervals
      summary: Retrieve a customer's interval data
      description: >-
        Retrieve interval meter data for a customer, organized by meter. Poll
        until intervals_are_ready is true, or subscribe to the intervals_ready
        webhook.
      parameters:
        - $ref: '#/components/parameters/CustomerId'
      responses:
        '200':
          description: The customer's interval data grouped by meter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntervalData'
  /bills:
    post:
      operationId: createBill
      tags:
        - Bills
      summary: Upload a bill
      description: Upload a new bill for processing.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Bill'
      responses:
        '201':
          description: The created bill.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bill'
  /bills/{id}:
    get:
      operationId: getBill
      tags:
        - Bills
      summary: Retrieve a bill
      description: Retrieve a specific bill by its identifier.
      parameters:
        - $ref: '#/components/parameters/BillId'
      responses:
        '200':
          description: The requested bill.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bill'
    patch:
      operationId: updateBill
      tags:
        - Bills
      summary: Update a bill
      description: Update a specific bill by its identifier.
      parameters:
        - $ref: '#/components/parameters/BillId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Bill'
      responses:
        '200':
          description: The updated bill.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bill'
  /bills/{id}/unlock:
    post:
      operationId: unlockBill
      tags:
        - Bills
      summary: Unlock a bill
      description: >-
        Unlock a bill's data, entirely or partially. Unlocking meters drives
        usage-based billing once the free meter allowance is exhausted.
      parameters:
        - $ref: '#/components/parameters/BillId'
      responses:
        '200':
          description: The unlocked bill.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bill'
  /utilities:
    get:
      operationId: listUtilities
      tags:
        - Utilities
      summary: List supported utilities
      description: >-
        Retrieve all supported utilities, including coverage, availability, and
        performance details.
      responses:
        '200':
          description: A list of supported utilities.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Utility'
  /utilities/{id}:
    get:
      operationId: getUtility
      tags:
        - Utilities
      summary: Retrieve a utility
      description: Retrieve details for a specific supported utility.
      parameters:
        - name: id
          in: path
          required: true
          description: The utility identifier.
          schema:
            type: string
      responses:
        '200':
          description: The requested utility.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Utility'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic authentication. Use your API key as the username and leave
        the password empty.
  parameters:
    CustomerId:
      name: id
      in: path
      required: true
      description: The customer identifier.
      schema:
        type: integer
    BillId:
      name: id
      in: path
      required: true
      description: The bill identifier.
      schema:
        type: integer
  schemas:
    CreateCustomerRequest:
      type: object
      required:
        - utility
      properties:
        utility:
          type: string
          description: >-
            The utility identifier the customer will connect (e.g.
            speculoos_power for testing).
        email:
          type: string
          format: email
          description: Optional email address for the customer.
    UpdateCustomerRequest:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Updated email address for the customer.
    Customer:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the customer.
        utility:
          type: string
          description: The utility the customer is connecting.
        email:
          type: string
          format: email
        onboarding_link:
          type: string
          format: uri
          description: Hosted link the customer uses to connect utility credentials.
        has_filled_credentials:
          type: boolean
          description: Whether the customer has submitted their utility credentials.
        bills_are_ready:
          type: boolean
          description: Whether initial bill discovery has completed.
        intervals_are_ready:
          type: boolean
          description: Whether initial interval discovery has completed.
        address:
          $ref: '#/components/schemas/Address'
    Bill:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the bill.
        customer_id:
          type: integer
        statement_date:
          type: string
          format: date
        billing_period_from:
          type: string
          format: date
        billing_period_to:
          type: string
          format: date
        account_number:
          type: string
        total_amount_due_cents:
          type: integer
          description: Total amount due on the bill, in cents.
        address:
          $ref: '#/components/schemas/Address'
        meters:
          type: array
          items:
            $ref: '#/components/schemas/Meter'
    Meter:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          description: Meter type, e.g. electric or gas.
        billing_period_from:
          type: string
          format: date
        billing_period_to:
          type: string
          format: date
        consumption:
          type: number
          description: Consumption for the billing period.
        tariff:
          type: string
        address:
          $ref: '#/components/schemas/Address'
    IntervalData:
      type: object
      properties:
        meters:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              type:
                type: string
              intervals:
                type: array
                items:
                  $ref: '#/components/schemas/Interval'
    Interval:
      type: object
      properties:
        start:
          type: string
          format: date-time
          description: Start timestamp of the interval.
        end:
          type: string
          format: date-time
          description: End timestamp of the interval.
        net_consumption:
          type: number
          description: Net consumption recorded during the interval.
    Utility:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        is_active:
          type: boolean
        bill_availability:
          type: string
        interval_availability:
          type: string
    Address:
      type: object
      properties:
        line1:
          type: string
        line2:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string