{"openapi":"3.1.0","info":{"title":"Grid Coordination Price Server API","version":"1.0.0","description":"Public [OpenADR 3.1.0](https:\/\/www.openadr.org\/) API serving California electricity prices and GHG emissions.\n\n## Quick start\n\n1. **Find your program** \u2014 `GET \/programs` lists all 1,645 programs. Filter by name to find your rate + location.\n2. **Get prices or emissions** \u2014 `GET \/events?programID={id}` returns daily events with 24 hourly intervals.\n3. **Subscribe to updates** \u2014 `GET \/notifiers` returns the MQTT broker URL for real-time push notifications.\n\n## What's available\n\n- **31 pricing tariffs** \u2014 PG&E and SCE residential, commercial, agricultural, and EV rate schedules, each served across every circuit\/substation. Payload type: `PRICE` (USD\/kWh).\n- **11 GHG emissions regions** \u2014 Marginal operating emissions rate (MOER) for California grid regions. Payload type: `GHG` (g CO2\/kWh).\n\nNo authentication required. All endpoints are read-only.\n\n**User guide:** [\/docs](https:\/\/price.grid-coordination.energy\/docs) \u00b7 **Source:** [GitHub](https:\/\/github.com\/grid-coordination\/clj-price-server)","contact":{"email":"info@openadr.org"},"license":{"name":"Apache 2.0","url":"http:\/\/www.apache.org\/licenses\/LICENSE-2.0.html"}},"paths":{"\/notifiers\/mqtt\/topics\/events":{"get":{"tags":["MQTT_notifier"],"summary":"List all MQTT binding topic names for operations on all events\n","description":"List all MQTT binding topic names for operations on all events\n","operationId":"listAllMqttNotifierTopicsEvents","security":[{"oAuth2ClientCredentials":["read_bl"]},{"bearerAuth":[]}],"responses":{"200":{"$ref":"#\/components\/responses\/notifiersTopicsResponse"},"400":{"$ref":"#\/components\/responses\/badRequest"},"401":{"$ref":"#\/components\/responses\/unauthorized"},"403":{"$ref":"#\/components\/responses\/forbidden"},"404":{"$ref":"#\/components\/responses\/notFound"},"500":{"$ref":"#\/components\/responses\/internalServerError"}}}},"\/events\/{eventID}":{"get":{"tags":["events"],"summary":"search events by ID","operationId":"searchEventsByID","description":"Fetch event associated with the eventID in path.\n","security":[{"oAuth2ClientCredentials":["read_targets"]},{"bearerAuth":[]}],"responses":{"200":{"description":"OK.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/event"}}}},"400":{"$ref":"#\/components\/responses\/badRequest"},"401":{"$ref":"#\/components\/responses\/unauthorized"},"403":{"$ref":"#\/components\/responses\/forbidden"},"404":{"$ref":"#\/components\/responses\/notFound"},"500":{"$ref":"#\/components\/responses\/internalServerError"}}}},"\/notifiers\/mqtt\/topics\/programs\/{programID}":{"get":{"tags":["MQTT_notifier"],"summary":"List all MQTT binding topic names for operations on a program\n","description":"List all MQTT binding topic names for operations on a program\n","operationId":"listAllMqttNotifierTopicsProgram","security":[{"oAuth2ClientCredentials":["read_all"]},{"bearerAuth":[]}],"responses":{"200":{"$ref":"#\/components\/responses\/notifiersTopicsResponse"},"400":{"$ref":"#\/components\/responses\/badRequest"},"401":{"$ref":"#\/components\/responses\/unauthorized"},"404":{"$ref":"#\/components\/responses\/notFound"},"500":{"$ref":"#\/components\/responses\/internalServerError"}}}},"\/programs":{"get":{"tags":["programs"],"summary":"searches all programs","operationId":"searchAllPrograms","description":"List all programs known to the server.\nMay filter results by targets params.\nUse skip and pagination query params to limit response size.\n","security":[{"oAuth2ClientCredentials":["read_targets"]},{"bearerAuth":[]}],"parameters":[{"name":"targets","in":"query","description":"Indicates targets","required":false,"schema":{"type":"array","items":{"$ref":"#\/components\/schemas\/target"}}},{"name":"programName","in":"query","description":"Filter results to programs whose programName matches exactly.\nLocal extension pending oadr3-org\/specification#418 \u2014 enables\ndirect lookup without scanning the full program collection.\n","required":false,"schema":{"type":"string"}},{"name":"skip","in":"query","description":"number of records to skip for pagination.","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"limit","in":"query","description":"maximum number of records to return.","required":false,"schema":{"type":"integer","format":"int32","maximum":50,"minimum":0}}],"responses":{"200":{"description":"OK.","content":{"application\/json":{"schema":{"type":"array","items":{"$ref":"#\/components\/schemas\/program"}}}}},"400":{"$ref":"#\/components\/responses\/badRequest"},"401":{"$ref":"#\/components\/responses\/unauthorized"},"403":{"$ref":"#\/components\/responses\/forbidden"},"500":{"$ref":"#\/components\/responses\/internalServerError"}}}},"\/auth\/server":{"get":{"tags":["Auth"],"summary":"fetch server info","operationId":"getAuthServerInfo","description":"Return the URL of the token endpoint.","responses":{"200":{"description":"OK.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/authServerInfo"}}}},"500":{"$ref":"#\/components\/responses\/internalServerError"}}}},"\/programs\/{programID}":{"get":{"tags":["programs"],"summary":"searches programs by program ID","operationId":"searchProgramByProgramId","description":"Fetch the program specified by the programID in path.\n","security":[{"oAuth2ClientCredentials":["read_targets"]},{"bearerAuth":[]}],"responses":{"200":{"description":"OK.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/program"}}}},"400":{"$ref":"#\/components\/responses\/badRequest"},"401":{"$ref":"#\/components\/responses\/unauthorized"},"403":{"$ref":"#\/components\/responses\/forbidden"},"404":{"$ref":"#\/components\/responses\/notFound"},"500":{"$ref":"#\/components\/responses\/internalServerError"}}}},"\/notifiers":{"get":{"tags":["notifiers"],"summary":"List all notifier bindings","operationId":"listAllNotifiers","description":"List all notifier bindings supported by the server\n","security":[{"oAuth2ClientCredentials":["read_all"]},{"bearerAuth":[]}],"responses":{"200":{"description":"OK.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/notifiersResponse"}}}}}}},"\/notifiers\/mqtt\/topics\/programs\/{programID}\/events":{"get":{"tags":["MQTT_notifier"],"summary":"List all MQTT binding topic names for operations on events for a program\n","description":"List all MQTT binding topic names for operations on events for a program\n","operationId":"listAllMqttNotifierTopicsProgramEvents","security":[{"oAuth2ClientCredentials":["read_all"]},{"bearerAuth":[]}],"responses":{"200":{"$ref":"#\/components\/responses\/notifiersTopicsResponse"},"400":{"$ref":"#\/components\/responses\/badRequest"},"401":{"$ref":"#\/components\/responses\/unauthorized"},"404":{"$ref":"#\/components\/responses\/notFound"},"500":{"$ref":"#\/components\/responses\/internalServerError"}}}},"\/events":{"get":{"tags":["events"],"summary":"searches all events","operationId":"searchAllEvents","description":"List all events known to the server.\nMay filter results by programID query param.\nMay filter results by targets params.\nUse skip and pagination query params to limit response size.\n","security":[{"oAuth2ClientCredentials":["read_targets"]},{"bearerAuth":[]}],"parameters":[{"name":"programID","in":"query","schema":{"$ref":"#\/components\/schemas\/objectID"},"required":false,"description":"filter results to events with programID.","example":"program-999"},{"name":"targets","in":"query","description":"Indicates targets","required":false,"schema":{"type":"array","items":{"$ref":"#\/components\/schemas\/target"}}},{"name":"skip","in":"query","description":"number of records to skip for pagination.","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"limit","in":"query","description":"maximum number of records to return.","required":false,"schema":{"type":"integer","format":"int32","maximum":50,"minimum":0}},{"name":"active","in":"query","description":"ignore events that have transpired.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"OK.","content":{"application\/json":{"schema":{"type":"array","items":{"$ref":"#\/components\/schemas\/event"}}}}},"400":{"$ref":"#\/components\/responses\/badRequest"},"401":{"$ref":"#\/components\/responses\/unauthorized"},"403":{"$ref":"#\/components\/responses\/forbidden"},"500":{"$ref":"#\/components\/responses\/internalServerError"}}}},"\/auth\/token":{"post":{"tags":["Auth"],"summary":"fetch a token","operationId":"fetchToken","description":"Return an access token based on clientID and clientSecret.","requestBody":{"required":true,"content":{"application\/x-www-form-urlencoded":{"schema":{"$ref":"#\/components\/schemas\/clientCredentialRequest"}}}},"responses":{"200":{"description":"OK.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/clientCredentialResponse"}}}},"400":{"$ref":"#\/components\/responses\/badRequest"},"401":{"$ref":"#\/components\/responses\/unauthorized"},"500":{"$ref":"#\/components\/responses\/internalServerError"},"501":{"$ref":"#\/components\/responses\/notImplemented"}}}},"\/notifiers\/mqtt\/topics\/programs":{"get":{"tags":["MQTT_notifier"],"summary":"List all MQTT notifier topic names for operations on programs\n","description":"List all MQTT notifier topic names for operations on programs\n","operationId":"listAllMqttNotifierTopicsPrograms","security":[{"oAuth2ClientCredentials":["read_all"]},{"bearerAuth":[]}],"responses":{"200":{"$ref":"#\/components\/responses\/notifiersTopicsResponse"},"400":{"$ref":"#\/components\/responses\/badRequest"},"401":{"$ref":"#\/components\/responses\/unauthorized"},"404":{"$ref":"#\/components\/responses\/notFound"},"500":{"$ref":"#\/components\/responses\/internalServerError"}}}}},"components":{"responses":{"badRequest":{"description":"The request is malformed or invalid","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/problem"}}}},"unauthorized":{"description":"Unauthorized","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/problem"}}}},"forbidden":{"description":"Forbidden","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/problem"}}}},"notFound":{"description":"The specified resource was not found","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/problem"}}}},"conflict":{"description":"Conflict. Could for example be a violation of a foreign key constraint or of a unique constraint on a name or id.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/problem"}}}},"internalServerError":{"description":"Internal server error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/problem"}}}},"notImplemented":{"description":"Not implemented","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/problem"}}}},"notifiersTopicsResponse":{"description":"OK","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/notifierTopicsResponse"}}}}},"schemas":{"resourceRequest":{"oneOf":[{"$ref":"#\/components\/schemas\/BlResourceRequest"},{"$ref":"#\/components\/schemas\/VenResourceRequest"}]},"readingType":{"type":"string","description":"Represents the type of reading.\n\nSee enumerations in Definitions for defined string values, or use privately defined strings\n","example":"DIRECT_READ","minLength":1,"maxLength":128,"nullable":true,"default":null},"resource":{"type":"object","description":"Server provided representation of resource","allOf":[{"$ref":"#\/components\/schemas\/objectMetadata"},{"$ref":"#\/components\/schemas\/BlResourceRequest"}]},"objectTypes":{"type":"string","description":"Types of objects addressable through API.","example":"EVENT","enum":["PROGRAM","EVENT","REPORT","SUBSCRIPTION","VEN","RESOURCE"]},"resourceName":{"type":"string","minLength":1,"maxLength":128,"description":"User generated identifier. A value of AGGREGATED_REPORT indicates an aggregation of more that one resource's data","example":"RESOURCE-999"},"clientCredentialRequest":{"type":"object","description":"Body of POST request to \/auth\/token. Note snake case per https:\/\/www.rfc-editor.org\/rfc\/rfc6749\n","required":["grant_type","client_id","client_secret"],"properties":{"grant_type":{"type":"string","description":"OAuth2 grant type, must be 'client_credentials'","example":"client_credentials","enum":["client_credentials"]},"client_id":{"type":"string","minLength":1,"maxLength":4096,"description":"client ID to exchange for bearer token.","example":"ven_client_99"},"client_secret":{"type":"string","minLength":1,"maxLength":4096,"description":"client secret to exchange for bearer token.","example":"ven_secret_99"},"scope":{"type":"string","minLength":0,"maxLength":4096,"description":"application defined scope.","example":"read_all"}}},"reportPayloadDescriptor":{"type":"object","description":"Contextual information used to interpret report payload values.\nE.g. a USAGE payload simply contains a usage value, an\nassociated descriptor provides necessary context such as units and data quality.\n","required":["objectType","payloadType"],"properties":{"objectType":{"type":"string","description":"Used as discriminator.","enum":["REPORT_PAYLOAD_DESCRIPTOR"]},"payloadType":{"type":"string","description":"Represents the nature of values.\n\nSee enumerations in Definitions for defined string values, or use privately defined strings\n","minLength":1,"maxLength":128,"example":"USAGE"},"readingType":{"$ref":"#\/components\/schemas\/readingType"},"units":{"$ref":"#\/components\/schemas\/units"},"accuracy":{"type":"number","format":"float","description":"A quantification of the accuracy of a set of payload values.","example":0.0,"nullable":true,"default":null},"confidence":{"type":"integer","format":"int32","minimum":0,"maximum":100,"description":"A quantification of the confidence in a set of payload values.","example":100,"nullable":true,"default":null}}},"clientID":{"type":"string","description":"ClientID as provisioned by Auhtentication Service and associated with client's bearer token\n","minLength":1,"maxLength":128,"example":"249rj49jiej"},"eventRequest":{"type":"object","description":"Event object to communicate a Demand Response request to VEN.\nIf intervalPeriod is present, sets default start time and duration of intervals.\n","required":["programID"],"properties":{"priority":{"type":"integer","minimum":0,"description":"Relative priority of event. A lower number is a higher priority.","example":0,"nullable":true,"default":null},"reportDescriptors":{"type":"array","description":"A list of reportDescriptor objects. Used to request reports from VEN.","items":{"$ref":"#\/components\/schemas\/reportDescriptor"},"nullable":true,"default":null},"programID":{"$ref":"#\/components\/schemas\/objectID"},"intervals":{"type":"array","description":"A list of interval objects.","items":{"$ref":"#\/components\/schemas\/interval"}},"eventName":{"type":"string","description":"User defined string for use in debugging or User Interface.","example":"price event 11-18-2022","nullable":true,"default":null},"payloadDescriptors":{"type":"array","description":"A list of payloadDescriptor objects.","items":{"$ref":"#\/components\/schemas\/eventPayloadDescriptor"},"nullable":true,"default":null},"targets":{"type":"array","description":"A list of targets.","items":{"$ref":"#\/components\/schemas\/target"},"nullable":true,"default":null},"duration":{"$ref":"#\/components\/schemas\/duration"},"intervalPeriod":{"$ref":"#\/components\/schemas\/intervalPeriod"}}},"BlVenRequest":{"type":"object","description":"Business Logic provided representation of ven.","required":["objectType","clientID","venName"],"properties":{"objectType":{"type":"string","description":"Used as discriminator.","enum":["BL_VEN_REQUEST"]},"clientID":{"$ref":"#\/components\/schemas\/clientID"},"targets":{"type":"array","description":"A list of targets.","items":{"$ref":"#\/components\/schemas\/target"},"nullable":true,"default":"null          -"},"venName":{"$ref":"#\/components\/schemas\/venName"},"attributes":{"type":"array","description":"A list of valuesMap objects describing attributes.","items":{"$ref":"#\/components\/schemas\/valuesMap"},"nullable":true,"default":null}}},"notifierOperationsTopics":{"type":"object","description":"MQTT notifier topic names for notifications of subscribable-object operations","required":["UPDATE","DELETE"],"properties":{"CREATE":{"type":"string","description":"'Topic path for CREATE operations,\n not provided for notifications for a specific object ID,\n e.g. until programID foo is created, clients unable to\n request notifications of its creation'\n","example":"{objectType}s\/create"},"UPDATE":{"type":"string","description":"Topic path for UPDATE operations","example":"{objectType}s\/update"},"DELETE":{"type":"string","description":"Topic path for DELETE operations","example":"{objectType}s\/delete"},"ALL":{"type":"string","description":"Topic path for ALL operations, if supported by VTN","example":"{objectType}s\/+"}}},"clientCredentialResponse":{"type":"object","description":"Body response from \/auth\/token. Note snake case per https:\/\/www.rfc-editor.org\/rfc\/rfc6749\n","required":["access_token","token_type"],"properties":{"access_token":{"type":"string","minLength":1,"maxLength":4096,"description":"access token provided by Authorization service","example":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3"},"token_type":{"type":"string","description":"token type, must be Bearer.","example":"Bearer","enum":["Bearer"]},"expires_in":{"type":"integer","description":"expiration period in seconds.","example":3600},"refresh_token":{"type":"string","minLength":1,"maxLength":4096,"description":"refresh token provided by Authorization service","example":"IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk"},"scope":{"type":"string","minLength":0,"maxLength":4096,"description":"application defined scope.","example":"read_all"}}},"authError":{"type":"object","description":"error response on HTTP 400 from auth\/token per https:\/\/www.rfc-editor.org\/rfc\/rfc6749","required":["error"],"properties":{"error":{"type":"string","description":"As described in rfc6749 | invalid_request \u2013 The request is missing a parameter so the server can\u2019t proceed with the request. This may also be returned if the request includes an unsupported parameter or repeats a parameter. invalid_client \u2013 Client authentication failed, such as if the request contains an invalid client ID or secret. Send an HTTP 401 response in this case. invalid_grant \u2013 The authorization code (or user\u2019s password for the password grant type) is invalid or expired. This is also the error you would return if the redirect URL given in the authorization grant does not match the URL provided in this access token request. invalid_scope \u2013 For access token requests that include a scope (password or client_credentials grants), this error indicates an invalid scope value in the request. unauthorized_client \u2013 This client is not authorized to use the requested grant type. For example, if you restrict which applications can use the Implicit grant, you would return this error for the other apps. unsupported_grant_type \u2013 If a grant type is requested that the authorization server doesn\u2019t recognize, use this code. Note that unknown grant types also use this specific error code rather than using the invalid_request above.","example":"invalid_request","enum":["invalid_request","invalid_client","invalid_grant","invalid_scope","unauthorized_client","unsupported_grant_type"]},"error_description":{"type":"string","description":"Should be a sentence or two at most describing the circumstance of the error","example":"Request was missing the 'client_id' parameter."},"error_uri":{"type":"string","format":"uri","minLength":2,"maxLength":8000,"description":"Optional reference to more detailed error description","example":"See the full API docs at https:\/\/authorization-server.com\/docs\/access_toke"}}},"eventPayloadDescriptor":{"type":"object","description":"Contextual information used to interpret event valuesMap values.\nE.g. a PRICE payload simply contains a price value, an\nassociated descriptor provides necessary context such as units and currency.\n","required":["objectType","payloadType"],"properties":{"objectType":{"type":"string","description":"Used as discriminator.","enum":["EVENT_PAYLOAD_DESCRIPTOR"]},"payloadType":{"type":"string","description":"Represents the nature of values.\n\nSee enumerations in Definitions for defined string values, or use privately defined strings\n","minLength":1,"maxLength":128,"example":"PRICE"},"units":{"$ref":"#\/components\/schemas\/units"},"currency":{"type":"string","description":"Currency of price payload.","example":"USD","nullable":true,"default":null}}},"dateTime":{"type":"string","format":"date-time","description":"datetime in RFC 3339 format","example":"2023-06-15T09:30:00Z"},"event":{"type":"object","description":"Server provided representation of event","allOf":[{"$ref":"#\/components\/schemas\/objectMetadata"},{"$ref":"#\/components\/schemas\/eventRequest"}]},"mqttNotifierBindingObject":{"type":"object","description":"Details of MQTT binding for messaging protocol support","required":["URIS","serialization","authentication"],"properties":{"URIS":{"type":"array","items":{"type":"string","format":"uri","description":"URIs for connection to MQTT broker","example":"mqtts:\/\/broker.vtn.company.com"}},"serialization":{"type":"string","description":"Currently always JSON, perhaps other formats supported in future","enum":["JSON"]},"authentication":{"oneOf":[{"$ref":"#\/components\/schemas\/mqttNotifierAuthenticationAnonymous"},{"$ref":"#\/components\/schemas\/mqttNotifierAuthenticationOauth2BearerToken"},{"$ref":"#\/components\/schemas\/mqttNotifierAuthenticationCertificate"}],"description":"Authentication method supported for connection to MQTT broker"}}},"notifierTopicsResponse":{"type":"object","required":["topics"],"properties":{"topics":{"$ref":"#\/components\/schemas\/notifierOperationsTopics"}}},"reportDescriptor":{"type":"object","description":"An object that may be used to request a report from a VEN.\n","required":["payloadType"],"properties":{"readingType":{"$ref":"#\/components\/schemas\/readingType"},"repeat":{"type":"integer","format":"int32","description":"Number of times to repeat report.\n1 indicates generate one report.\n-1 indicates repeat indefinitely.\n","example":1,"default":1},"aggregate":{"type":"boolean","description":"True if report should aggregate results from all targeted resources.\nFalse if report includes results for each resource.\n","example":false,"default":false},"payloadType":{"type":"string","description":"Represents the nature of values.\n\nSee enumerations in Definitions for defined string values, or use privately defined strings\n","minLength":1,"maxLength":128,"example":"USAGE"},"startInterval":{"type":"integer","format":"int32","description":"The interval on which to generate a report.\n-1 indicates generate report at end of last interval.\n","example":-1,"default":-1},"targets":{"type":"array","description":"A list of targets.","items":{"$ref":"#\/components\/schemas\/target"},"nullable":true,"default":null},"units":{"$ref":"#\/components\/schemas\/units"},"numIntervals":{"type":"integer","format":"int32","description":"The number of intervals to include in a report.\n-1 indicates that all intervals are to be included.\n","example":-1,"default":-1},"reportIntervals":{"type":"string","description":"Indicates VEN report interval options. See User Guide.","example":"INTERVALS","enum":["INTERVALS","SUB_INTERVALS","OPEN_INTERVALS"],"default":"INTERVALS"},"historical":{"type":"boolean","description":"True indicates report on intervals preceding startInterval.\nFalse indicates report on intervals following startInterval (e.g. forecast).\n","example":true,"default":true},"frequency":{"type":"integer","format":"int32","description":"Number of intervals that elapse between reports.\n-1 indicates same as numIntervals.\n","example":-1,"default":-1}}},"notifiersResponse":{"type":"object","description":"Provides details of each notifier binding supported","required":["WEBHOOK"],"properties":{"WEBHOOK":{"type":"boolean","description":"Currently MUST be true","example":true},"MQTT":{"$ref":"#\/components\/schemas\/mqttNotifierBindingObject"}}},"interval":{"type":"object","description":"An object defining a temporal window and a list of valuesMaps.\nif intervalPeriod present may set temporal aspects of interval or override event.intervalPeriod.\n","required":["id","payloads"],"properties":{"id":{"type":"integer","format":"int32","description":"A client generated number assigned an interval object. Not a sequence number.","example":0},"intervalPeriod":{"$ref":"#\/components\/schemas\/intervalPeriod"},"payloads":{"type":"array","description":"A list of valuesMap objects.","items":{"$ref":"#\/components\/schemas\/valuesMap"}}}},"venRequest":{"oneOf":[{"$ref":"#\/components\/schemas\/VenVenRequest"},{"$ref":"#\/components\/schemas\/BlVenRequest"}]},"valuesMap":{"type":"object","description":"Represents one or more values associated with a type.\n\nSee enumerations in Definitions for defined string values, or use privately defined strings\n","required":["type","values"],"properties":{"type":{"type":"string","minLength":1,"maxLength":128,"description":"Represents the nature of values.\n\nSee enumerations in Definitions for defined string values, or use privately defined strings\n","example":"PRICE"},"values":{"type":"array","description":"A list of data points. Most often a singular value such as a price.","example":[0.17],"items":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"string"},{"type":"boolean"},{"$ref":"#\/components\/schemas\/point"}]}}}},"subscription":{"type":"object","description":"Server provided representation of subscription","allOf":[{"$ref":"#\/components\/schemas\/objectMetadata"},{"$ref":"#\/components\/schemas\/subscriptionRequest"},{"type":"object","required":["clientID"],"properties":{"clientID":{"$ref":"#\/components\/schemas\/clientID"}}}]},"mqttNotifierAuthenticationCertificate":{"type":"object","description":"MQTT broker mTLS client certificate authentication details","required":["method","caCert","clientCert","clientKey"],"properties":{"method":{"type":"string","enum":["CERTIFICATE"],"description":"Specifies certificate authentication"},"caCert":{"type":"string","description":"String containing the Certificate Authority certificate"},"clientCert":{"type":"string","description":"String containing the Client certificate"},"clientKey":{"type":"string","description":"String containing the client certificate private key"}}},"ven":{"type":"object","description":"Server provided representation of ven","allOf":[{"$ref":"#\/components\/schemas\/objectMetadata"},{"$ref":"#\/components\/schemas\/BlVenRequest"}]},"authServerInfo":{"type":"object","required":["tokenURL"],"properties":{"tokenURL":{"type":"string","format":"uri","minLength":2,"maxLength":8000,"description":"URL of the token endpoint."}}},"subscriptionRequest":{"type":"object","description":"An object created by a client to receive notification of operations on objects.\nClients may subscribe to be notified when a type of object is created,\nupdated, or deleted.\n","required":["clientName","objectOperations"],"properties":{"clientName":{"$ref":"#\/components\/schemas\/clientName"},"programID":{"$ref":"#\/components\/schemas\/objectID"},"objectOperations":{"type":"array","description":"list of objects and operations to subscribe to.","items":{"type":"object","description":"object type, operations, and callbackUrl.","required":["objects","operations","callbackUrl"],"properties":{"objects":{"type":"array","description":"list of objects to subscribe to.","items":{"$ref":"#\/components\/schemas\/objectTypes"}},"operations":{"type":"array","description":"list of operations to subscribe to.","items":{"type":"string","description":"object operation to subscribe to.","example":"CREATE","enum":["READ","CREATE","UPDATE","DELETE"]}},"callbackUrl":{"type":"string","format":"uri","minLength":2,"maxLength":8000,"description":"User provided webhook URL.","example":"https:\/\/myserver.com\/send\/callback\/here"},"bearerToken":{"type":"string","description":"User provided token.\nTo avoid custom integrations, callback endpoints\nshould accept the provided bearer token to authenticate VTN requests.\n","example":"NCEJGI9E8ER9802UT9HUG","nullable":true,"default":null}}}},"targets":{"type":"array","description":"A list of target objects. Used by server to filter notifications.","items":{"$ref":"#\/components\/schemas\/target"},"nullable":true,"default":null}}},"units":{"type":"string","description":"Units of measure.","example":"KWH","nullable":true,"default":null,"minLength":1,"maxLength":128},"objectMetadata":{"type":"object","description":"metadata common to all addressable objects. Values provided by VTN on object creation.","required":["id","createdDateTime","modificationDateTime","objectType"],"properties":{"id":{"$ref":"#\/components\/schemas\/objectID"},"createdDateTime":{"$ref":"#\/components\/schemas\/dateTime"},"modificationDateTime":{"$ref":"#\/components\/schemas\/dateTime"},"objectType":{"$ref":"#\/components\/schemas\/objectTypes"}}},"objectID":{"type":"string","pattern":"^[a-zA-Z0-9_-]*$","minLength":1,"maxLength":128,"description":"URL safe VTN assigned object ID.","example":"object-999"},"duration":{"type":"string","pattern":"^(-?)P(?=\\d|T\\d)(?:(\\d+)Y)?(?:(\\d+)M)?(?:(\\d+)([DW]))?(?:T(?:(\\d+)H)?(?:(\\d+)M)?(?:(\\d+(?:\\.\\d+)?)S)?)?$","description":"duration in ISO 8601 format","example":"PT1H","default":"PT0S"},"clientName":{"type":"string","description":"User generated identifier, may be VEN identifier provisioned out-of-band.","minLength":1,"maxLength":128,"example":"VEN-999"},"target":{"type":"string","minLength":1,"maxLength":128,"description":"User generated target string.","example":"group-1"},"reportRequest":{"type":"object","description":"report object.","required":["eventID","clientName","resources"],"properties":{"eventID":{"$ref":"#\/components\/schemas\/objectID"},"clientName":{"$ref":"#\/components\/schemas\/clientName"},"reportName":{"type":"string","description":"User defined string for use in debugging or User Interface.","example":"Battery_usage_04112023","nullable":true,"default":null},"payloadDescriptors":{"type":"array","description":"A list of reportPayloadDescriptors.","items":{"$ref":"#\/components\/schemas\/reportPayloadDescriptor"},"nullable":true,"default":null},"resources":{"type":"array","description":"A list of objects containing report data for a set of resources.","items":{"type":"object","description":"Report data associated with a resource.","required":["resourceName","intervals"],"properties":{"resourceName":{"$ref":"#\/components\/schemas\/resourceName"},"intervalPeriod":{"$ref":"#\/components\/schemas\/intervalPeriod"},"intervals":{"type":"array","description":"A list of interval objects.","items":{"$ref":"#\/components\/schemas\/interval"}}}}}}},"report":{"type":"object","description":"Server provided representation of report","allOf":[{"$ref":"#\/components\/schemas\/objectMetadata"},{"$ref":"#\/components\/schemas\/reportRequest"},{"type":"object","required":["clientID"],"properties":{"clientID":{"$ref":"#\/components\/schemas\/clientID"}}}]},"mqttNotifierAuthenticationAnonymous":{"type":"object","description":"MQTT broker anonymous authentication details","required":["method"],"properties":{"method":{"type":"string","enum":["ANONYMOUS"],"description":"Specifies anonymous authentication"}}},"notification":{"type":"object","description":"VTN generated object included in request to subscription callbackUrl.\n","required":["objectType","operation","object"],"properties":{"objectType":{"$ref":"#\/components\/schemas\/objectTypes"},"operation":{"type":"string","description":"the operation on on object that triggered the notification.","example":"UPDATE","enum":["CREATE","READ","UPDATE","DELETE"]},"object":{"type":"object","description":"the object that is the subject of the notification.","example":{},"oneOf":[{"$ref":"#\/components\/schemas\/program"},{"$ref":"#\/components\/schemas\/report"},{"$ref":"#\/components\/schemas\/event"},{"$ref":"#\/components\/schemas\/subscription"},{"$ref":"#\/components\/schemas\/ven"},{"$ref":"#\/components\/schemas\/resource"}],"discriminator":{"propertyName":"objectType"}},"targets":{"type":"array","description":"A list of targets.","items":{"$ref":"#\/components\/schemas\/target"},"nullable":true,"default":null}}},"problem":{"type":"object","description":"reusable error response. From https:\/\/opensource.zalando.com\/problem\/schema.yaml.\n","properties":{"type":{"type":"string","format":"uri","minLength":2,"maxLength":8000,"description":"An absolute URI that identifies the problem type.\nWhen dereferenced, it SHOULD provide human-readable documentation for the problem type\n(e.g., using HTML).\n","default":"about:blank","example":"https:\/\/zalando.github.io\/problem\/constraint-violation"},"title":{"type":"string","description":"A short, summary of the problem type. Written in english and readable\nfor engineers (usually not suited for non technical stakeholders and\nnot localized); example: Service Unavailable.\n"},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.\n","minimum":100,"exclusiveMaximum":600,"example":503},"detail":{"type":"string","description":"A human readable explanation specific to this occurrence of the\nproblem.\n","example":"Connection to database timed out"},"instance":{"type":"string","minLength":3,"maxLength":8000,"format":"uri","description":"An absolute URI that identifies the specific occurrence of the problem.\nIt may or may not yield further information if dereferenced.\n"}}},"BlResourceRequest":{"type":"object","description":"Business Logic provided representation of ven resource.\n","required":["objectType","clientID","resourceName","venID"],"properties":{"objectType":{"type":"string","description":"Used as discriminator.","enum":["BL_RESOURCE_REQUEST"]},"clientID":{"$ref":"#\/components\/schemas\/clientID"},"targets":{"type":"array","description":"A list of targets.","items":{"$ref":"#\/components\/schemas\/target"},"nullable":true,"default":null},"resourceName":{"$ref":"#\/components\/schemas\/resourceName"},"venID":{"$ref":"#\/components\/schemas\/objectID"},"attributes":{"type":"array","description":"A list of valuesMap objects describing attributes.","items":{"$ref":"#\/components\/schemas\/valuesMap"},"nullable":true,"default":null}}},"mqttNotifierAuthenticationOauth2BearerToken":{"type":"object","description":"MQTT broker OAuth2 Bearer Token authentication details","required":["method","username"],"properties":{"method":{"type":"string","enum":["OAUTH2_BEARER_TOKEN"],"description":"Specifies OAuth2 bearer token authentication"},"username":{"type":"string","description":"Either the distinguished string \"{clientID}\", or any other literal string"}}},"VenResourceRequest":{"type":"object","description":"Business Logic provided representation of ven resource.\n","required":["objectType","resourceName","venID"],"properties":{"objectType":{"type":"string","description":"Used as discriminator.","enum":["VEN_RESOURCE_REQUEST"]},"resourceName":{"$ref":"#\/components\/schemas\/resourceName"},"venID":{"$ref":"#\/components\/schemas\/objectID"},"attributes":{"type":"array","description":"A list of valuesMap objects describing attributes.","items":{"$ref":"#\/components\/schemas\/valuesMap"},"nullable":true,"default":null}}},"venName":{"type":"string","description":"User generated identifier, may be VEN identifier provisioned out-of-band.\nvenName is expected to be unique within the scope of a VTN\n","minLength":1,"maxLength":128,"example":"VEN-999"},"programRequest":{"type":"object","description":"Client provided description of program","required":["programName"],"properties":{"programName":{"type":"string","description":"Short name to uniquely identify program.","minLength":1,"maxLength":128,"example":"ResTOU"},"intervalPeriod":{"$ref":"#\/components\/schemas\/intervalPeriod"},"programDescriptions":{"type":"array","description":"A list of programDescriptions","items":{"required":["URL"],"properties":{"URL":{"type":"string","format":"uri","minLength":2,"maxLength":8000,"description":"A human or machine readable program description","example":"https:\/\/www.myCorporation.com\/myProgramDescription"}}},"nullable":true,"default":null},"payloadDescriptors":{"type":"array","description":"A list of payloadDescriptors.","items":{"anyOf":[{"$ref":"#\/components\/schemas\/eventPayloadDescriptor"},{"$ref":"#\/components\/schemas\/reportPayloadDescriptor"}],"discriminator":{"propertyName":"objectType","mapping":{"EVENT_PAYLOAD_DESCRIPTOR":"#\/components\/schemas\/eventPayloadDescriptor","REPORT_PAYLOAD_DESCRIPTOR":"#\/components\/schemas\/reportPayloadDescriptor"}}},"nullable":true,"default":null},"attributes":{"type":"array","description":"A list of valuesMap objects describing attributes.","items":{"$ref":"#\/components\/schemas\/valuesMap"},"nullable":true,"default":null},"targets":{"type":"array","description":"A list of targets.","items":{"$ref":"#\/components\/schemas\/target"},"nullable":true,"default":null}}},"point":{"type":"object","description":"A pair of floats typically used as a point on a 2 dimensional grid.","required":["x","y"],"properties":{"x":{"type":"number","format":"float","description":"A value on an x axis.","example":1.0},"y":{"type":"number","format":"float","description":"A value on a y axis.","example":2.0}}},"intervalPeriod":{"type":"object","description":"Defines temporal aspects of intervals.\nA start of \"0001-01-01\" or \"0001-01-01T00:00:00\" may indicate 'now'. See User Guide.\nA duration of \"P9999Y\" may indicate infinity. See User Guide.\nA randomizeStart indicates absolute range of client applied offset to start. See User Guide.\n","properties":{"start":{"$ref":"#\/components\/schemas\/dateTime"},"duration":{"$ref":"#\/components\/schemas\/duration"},"randomizeStart":{"$ref":"#\/components\/schemas\/duration"}}},"program":{"type":"object","description":"Server provided representation of program","allOf":[{"$ref":"#\/components\/schemas\/objectMetadata"},{"$ref":"#\/components\/schemas\/programRequest"}]},"VenVenRequest":{"type":"object","description":"VEN provided representation of ven.","required":["objectType","venName"],"properties":{"objectType":{"type":"string","description":"Used as discriminator.","enum":["VEN_VEN_REQUEST"]},"venName":{"$ref":"#\/components\/schemas\/venName"},"attributes":{"type":"array","description":"A list of valuesMap objects describing attributes.","items":{"$ref":"#\/components\/schemas\/valuesMap"},"nullable":true,"default":null}}}},"securitySchemes":{"oAuth2ClientCredentials":{"type":"oauth2","description":"Client credential flow.","flows":{"clientCredentials":{"tokenUrl":"auth\/token","scopes":{"read_all":"BL can read all resources","read_targets":"VENs may only read objects with targets by providing matching targets","read_ven_objects":"VENs may only read objects whose clientID matches their own","write_programs":"Only BL can write to programs","write_events":"Only BL can write to events","write_reports":"only VENs can write to reports","write_subscriptions":"VENs and BL can write to subscriptions","write_vens":"VENS and BL can write to vens and resources"}}}},"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"servers":[{"url":"\/openadr3\/3.1.0"}],"tags":[{"name":"programs","description":"List available programs. Each program represents a rate schedule \u00d7 location combination (e.g. `EELEC-013532223` for PG&E residential on a specific circuit, or `MOER-PGE` for GHG emissions in the PG&E region). Start here to find the program relevant to you.\n\n**Finding a program by name:** The API returns programs in pages of up to 50. To find a specific program, paginate through the results and match on `programName`. For example, to find PG&E residential pricing for the Menlo substation, look for `programName: \"EELEC-024131103\"`. Note the `id` field (a UUID) \u2014 you'll need it to query events.\n\nExample: `GET \/programs?skip=0&limit=50`, then filter the response for your `programName`. Repeat with `skip=50`, `skip=100`, etc. until found."},{"name":"events","description":"Fetch pricing and emissions data. Each event covers one day with 24 hourly intervals. Query by `programID` (the UUID from the programs endpoint) to get events for a specific program. Intervals contain either `PRICE` (USD\/kWh) or `GHG` (g CO2\/kWh) payloads.\n\nExample: `GET \/events?programID=bb4a75a7-d7b5-49c4-af94-55a6911300d3` returns daily events for that program."},{"name":"notifiers","description":"Discover the MQTT broker for real-time push notifications. Returns broker URLs and authentication details."},{"name":"MQTT_notifier","description":"MQTT topic discovery. Find the exact topic strings to subscribe to for a specific program's event notifications."},{"name":"Auth","description":"Authentication endpoints. No authentication is currently required \u2014 all endpoints are read-only and publicly accessible."}]}