API Evangelist enhancements for the Amber Electric Public Sites API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Amber Electric Public Sites API
  version: 1.0.0
extends: openapi/amber-electric-sites-api-openapi.yml
x-apievangelist:
  generated: '2026-10-21'
  method: generated
  source: >-
    Derived from openapi/amber-electric-sites-api-openapi.yml (split from Amber's
    published https://app.amber.com.au/swagger.json) plus rate-limits/,
    conventions/, errors/ and authentication/ in this repository. The contract is
    never mutated; every enhancement lives here.
actions:
- target: $.info
  update:
    x-access-gate: customer-account-required
    x-agent-surfaces:
      mcp: mcp/amber-electric-mcp.yml
      skills: skills/_index.yml
      llms: llms/amber-electric-llms.txt
- target: $
  update:
    tags:
    - name: Sites
      description: The sites on your Amber account and their half-hourly prices and usage.
- target: $.paths['/sites'].get
  update:
    summary: List the sites on your account
    x-apievangelist-note: >-
      Call this first. siteId is an Amber-assigned identifier, not the NMI, and
      every other site-scoped operation needs it.
- target: $.paths['/sites/{siteId}/prices'].get
  update:
    summary: Get prices for a site across a date range
- target: $.paths['/sites/{siteId}/prices/current'].get
  update:
    summary: Get the current price (with optional previous/next intervals) for a site
- target: $.paths['/sites/{siteId}/usage'].get
  update:
    summary: Get usage for a site across a date range
    x-apievangelist-note: Returns at most 90 days per call; startDate and endDate are both required.
- target: $.paths.*.get.responses
  update:
    '429':
      $ref: '#/components/responses/TooManyRequests'
- target: $.components.securitySchemes.apiKey
  update:
    description: >-
      Unscoped bearer token generated from the Developers tab inside the
      logged-in Amber customer app at https://app.amber.com.au/developers.
      Requires an active Amber electricity account; there is no self-serve
      developer signup, sandbox or trial key.
- target: $.components
  update:
    responses:
      TooManyRequests:
        description: >-
          Rate limit exceeded. Amber enforces 50 calls per 5 minutes per account
          (announced at https://github.com/amberelectric/public-api/discussions/146).
          Undeclared in the published contract.
        headers:
          RateLimit-Limit:
            $ref: '#/components/headers/RateLimit-Limit'
          RateLimit-Remaining:
            $ref: '#/components/headers/RateLimit-Remaining'
          RateLimit-Reset:
            $ref: '#/components/headers/RateLimit-Reset'
          RateLimit-Policy:
            $ref: '#/components/headers/RateLimit-Policy'