{"openapi":"3.1.0","info":{"title":"Amber Electric (BYOK) API","version":"0.1.0","description":"Amber Electric (BYOK) lets an AI assistant read your own Amber Electric data through the Amber Electric API with a key you supply (API token (starts with psk_)). Read-only: 5 tools (list_sites, get_current_prices, list_prices, list_usage, get_current_renewables). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever sent to...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-amber-electric.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-amber-electric/docs"},"termsOfService":"https://connectorbay.com/byok-amber-electric/terms"},"servers":[{"url":"https://byok-amber-electric.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-amber-electric/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_sites":{"post":{"operationId":"list_sites","summary":"List the Amber sites on the account: site id, network, status, activation date and the price channels (general, controll","description":"List the Amber sites on the account: site id, network, status, activation date and the price channels (general, controlled load, feed-in) with their tariffs. The meter identifier (NMI) is not returned. Use for \"Which Amber sites do I have and what are their site ids\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_sitesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_current_prices":{"post":{"operationId":"get_current_prices","summary":"Get the price for the current half-hour per channel, optionally with upcoming forecast and past intervals; prices are in","description":"Get the price for the current half-hour per channel, optionally with upcoming forecast and past intervals; prices are in cents per kWh. Use for \"What is my Amber electricity price right now and for the next few hours\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"Amber site id; list_sites returns it.","maxLength":200,"title":"Site Id","type":"string"},"next":{"anyOf":[{"maximum":2048,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Also return this many forecast intervals after now.","title":"Next"},"previous":{"anyOf":[{"maximum":2048,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Also return this many past (actual) intervals before now.","title":"Previous"},"resolution":{"anyOf":[{"const":30,"type":"integer"},{"type":"null"}],"default":30,"description":"Interval length in minutes; only 30 is allowed.","title":"Resolution"}},"required":["site_id"],"title":"get_current_pricesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_prices":{"post":{"operationId":"list_prices","summary":"List prices for each interval between two dates (default today), in cents per kWh, with spot price, renewables share, pr","description":"List prices for each interval between two dates (default today), in cents per kWh, with spot price, renewables share, price descriptor and spike status. Use for \"What were the Amber electricity prices yesterday\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"Amber site id; list_sites returns it.","maxLength":200,"title":"Site Id","type":"string"},"start_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"First day, format YYYY-MM-DD (default today).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Last day, format YYYY-MM-DD (default today).","title":"End Date"},"resolution":{"anyOf":[{"enum":[5,30],"type":"integer"},{"type":"null"}],"default":30,"description":"Interval length in minutes: 5 or 30.","title":"Resolution"}},"required":["site_id"],"title":"list_pricesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_usage":{"post":{"operationId":"list_usage","summary":"List metered usage per interval and channel between two dates: kWh, cost, price and quality (estimated or billable). Use","description":"List metered usage per interval and channel between two dates: kWh, cost, price and quality (estimated or billable). Use for \"How much electricity did I use and what did it cost last week on Amber\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"site_id":{"description":"Amber site id; list_sites returns it.","maxLength":200,"title":"Site Id","type":"string"},"start_date":{"description":"First day, format YYYY-MM-DD.","maxLength":200,"title":"Start Date","type":"string"},"end_date":{"description":"Last day, format YYYY-MM-DD.","maxLength":200,"title":"End Date","type":"string"},"resolution":{"anyOf":[{"const":30,"type":"integer"},{"type":"null"}],"default":30,"description":"Interval length in minutes; only 30 is allowed.","title":"Resolution"}},"required":["site_id","start_date","end_date"],"title":"list_usageArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_current_renewables":{"post":{"operationId":"get_current_renewables","summary":"Get the share of renewable energy in the grid for an Australian state (nsw, sa, qld, vic), with optional past and foreca","description":"Get the share of renewable energy in the grid for an Australian state (nsw, sa, qld, vic), with optional past and forecast intervals. Use for \"How much of the grid is renewable right now in South Australia\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"description":"State code: nsw, sa, qld or vic.","enum":["nsw","sa","qld","vic"],"title":"State","type":"string"},"next":{"anyOf":[{"maximum":2048,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Also return this many forecast intervals after now.","title":"Next"},"previous":{"anyOf":[{"maximum":2048,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Also return this many past (actual) intervals before now.","title":"Previous"},"resolution":{"anyOf":[{"enum":[5,30],"type":"integer"},{"type":"null"}],"default":30,"description":"Interval length in minutes: 5 or 30.","title":"Resolution"}},"required":["state"],"title":"get_current_renewablesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}