Subscribe to event notifications - customer_has_filled_credentials, customer_must_reauthenticate, new_bill, updated_bill, new_unparsed_bill, bills_ready, and intervals_ready - so production integrations react to data availability instead of polling.
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