openapi: 3.0.3
info:
  title: Aurora Solar Agreements Consumption Profiles API
  description: 'The Aurora API lets you build apps and integrations on the Aurora Solar platform for solar sales and design. It is a tenant-scoped REST API: every resource lives under /tenants/{tenant_id}. Requests are authenticated with an API-key bearer token (Standard keys prefixed `sk_`, Restricted keys prefixed `rk_`; `sand_`/`prod_` denote the environment) passed as `Authorization: Bearer <token>`. The current API version is v2024.05, selected via the `Aurora-Version` request header.


    Scope note: A handful of paths in this document are confirmed directly against Aurora''s public reference (List Projects, Create Design Request, Create Webhook). The remaining paths are HONESTLY MODELED from Aurora''s published operation catalog (docs.aurorasolar.com/llms.txt) following the same `/tenants/{tenant_id}/<resource>` convention; exact path segments for modeled operations should be reconciled against the live reference, which is partially gated. Modeled operations carry `x-modeled: true`.'
  version: v2024.05
  contact:
    name: Aurora Solar Developer Platform
    url: https://docs.aurorasolar.com
  license:
    name: Proprietary
    url: https://aurorasolar.com/terms-of-service/
servers:
- url: https://api.aurorasolar.com
  description: Production
- url: https://api-sandbox.aurorasolar.com
  description: Sandbox
security:
- bearerAuth: []
tags:
- name: Consumption Profiles
  description: Energy consumption profiles and utility bills.
paths:
  /tenants/{tenant_id}/projects/{project_id}/consumption_profile:
    parameters:
    - $ref: '#/components/parameters/TenantId'
    - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: retrieveConsumptionProfile
      tags:
      - Consumption Profiles
      summary: Retrieve consumption profile
      description: Retrieves the energy consumption profile for a project.
      x-modeled: true
      responses:
        '200':
          description: The consumption profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsumptionProfile'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateConsumptionProfile
      tags:
      - Consumption Profiles
      summary: Update consumption profile
      description: Updates the energy consumption profile for a project.
      x-modeled: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConsumptionProfile'
      responses:
        '200':
          description: The updated consumption profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConsumptionProfile'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
  /tenants/{tenant_id}/projects/{project_id}/utility_bills:
    parameters:
    - $ref: '#/components/parameters/TenantId'
    - $ref: '#/components/parameters/ProjectId'
    get:
      operationId: listUtilityBills
      tags:
      - Consumption Profiles
      summary: List utility bills
      description: Lists the utility bills uploaded for a project.
      x-modeled: true
      responses:
        '200':
          description: A list of utility bills.
          content:
            application/json:
              schema:
                type: object
                properties:
                  utility_bills:
                    type: array
                    items:
                      type: object
                      additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              title:
                type: string
              detail:
                type: string
    ConsumptionProfile:
      type: object
      properties:
        project_id:
          type: string
        annual_consumption_kwh:
          type: number
          format: double
        monthly_consumption_kwh:
          type: array
          items:
            type: number
            format: double
        utility_rate_name:
          type: string
        source:
          type: string
          description: How the profile was derived (for example utility_bill or manual).
  responses:
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: The project ID.
      schema:
        type: string
    TenantId:
      name: tenant_id
      in: path
      required: true
      description: The tenant (organization) ID that owns the resource.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API-key bearer token. Standard keys are prefixed `sk_`, Restricted keys `rk_`; `sand_`/`prod_` denote sandbox vs production. Passed as `Authorization: Bearer <token>`.'