OpenADR Alliance Subscriptions API

openapi: 3.2.0
info:
  title: Openadr Alliance Subscriptions API
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: '1.0'
  description: 'Operations tagged subscriptions across 4 of this provider''s published API definitions: openadr-3-0-0-openapi.yaml, openadr-3-0-1-openapi.yaml, openadr-3-1-0-openapi.yaml, openadr-3-1-1-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- description: base path
  url: http://localhost:8081/openadr3
- description: base path
  url: http://localhost:8081/openadr3/3.0.1
- description: SwaggerHub API Auto Mocking
  url: https://virtserver.swaggerhub.com/OPENADR3_1/openADR3.1.0/1.0.0
tags:
- name: subscriptions
paths:
  /subscriptions:
    get:
      tags:
      - subscriptions
      summary: search subscriptions
      operationId: searchSubscriptions
      description: 'List all subscriptions.

        May filter results by programID and clientID as query params.

        May filter results by objects as query param. See objectTypes schema.

        Use skip and pagination query params to limit response size.

        '
      security:
      - oAuth2ClientCredentials:
        - read_all
      - bearerAuth: []
      parameters:
      - name: programID
        in: query
        schema:
          $ref: '#/components/schemas/objectID'
        description: filter results to subscriptions with programID.
        required: false
      - name: clientName
        in: query
        schema:
          type: string
        description: filter results to subscriptions with clientName.
        required: false
      - name: targetType
        in: query
        description: Indicates targeting type, e.g. GROUP
        required: false
        schema:
          type: string
      - name: targetValues
        in: query
        description: List of target values, e.g. group names
        required: false
        schema:
          type: array
          items:
            type: string
      - name: objects
        in: query
        description: list of objects to subscribe to.
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/objectTypes'
      - name: skip
        in: query
        description: number of records to skip for pagination.
        required: false
        style: form
        explode: true
        schema:
          minimum: 0
          type: integer
          format: int32
      - name: limit
        in: query
        description: maximum number of records to return.
        required: false
        style: form
        explode: true
        schema:
          maximum: 50
          minimum: 0
          type: integer
          format: int32
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/subscription'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    post:
      tags:
      - subscriptions
      summary: create subscription
      operationId: createSubscription
      description: Create a new subscription.
      security:
      - oAuth2ClientCredentials:
        - write_subscriptions
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/subscription'
      callbacks:
        notifyEvent:
          '{$request.body#/callbackUrl}':
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/notification'
              responses:
                '200':
                  description: Your server returns this code if it accepts the callback.
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/subscription'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '409':
          description: Conflict. Implementation dependent response if identical object already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    servers:
    - description: base path
      url: http://localhost:8081/openadr3
  /subscriptions/{subscriptionID}:
    parameters:
    - name: subscriptionID
      in: path
      schema:
        $ref: '#/components/schemas/objectID'
      description: object ID of the associated subscription.
      required: true
    get:
      tags:
      - subscriptions
      summary: search subscriptions by ID
      operationId: searchSubscriptionByID
      description: Return the subscription specified by subscriptionID specified in path.
      security:
      - oAuth2ClientCredentials:
        - read_all
      - bearerAuth: []
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/subscription'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    put:
      tags:
      - subscriptions
      summary: update  subscription
      operationId: updateSubscription
      description: Update the subscription specified by subscriptionID specified in path.
      security:
      - oAuth2ClientCredentials:
        - write_subscriptions
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/subscription'
        description: subscription item to update.
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/subscription'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '409':
          description: Conflict. Implementation dependent response if program with the same programName exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    delete:
      tags:
      - subscriptions
      summary: delete  subscription
      operationId: deleteSubscription
      description: Delete the subscription specified by subscriptionID specified in path.
      security:
      - oAuth2ClientCredentials:
        - write_subscriptions
      - bearerAuth: []
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/subscription'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problem'
    servers:
    - description: base path
      url: http://localhost:8081/openadr3
components:
  schemas:
    reportDescriptor:
      type: object
      description: 'An object that may be used to request a report from a VEN.

        See OpenADR REST User Guide for detailed description of how configure a report request.

        '
      required:
      - payloadType
      properties:
        payloadType:
          type: string
          description: Enumerated or private string signifying the nature of values.
          example: USAGE
        readingType:
          type: string
          description: Enumerated or private string signifying the type of reading.
          example: DIRECT_READ
          default: DIRECT_READ
        targets:
          type:
          - array
          - 'null'
          description: A list of valuesMap objects.
          default: null
          items:
            $ref: '#/components/schemas/valuesMap'
        aggregate:
          type: boolean
          description: 'True if report should aggregate results from all targeted resources.

            False if report includes results for each resource.

            '
          example: false
          default: false
        startInterval:
          type: integer
          format: int32
          description: 'The interval on which to generate a report.

            -1 indicates generate report at end of last interval.

            '
          example: -1
          default: -1
        numIntervals:
          type: integer
          format: int32
          description: 'The number of intervals to include in a report.

            -1 indicates that all intervals are to be included.

            '
          example: -1
          default: -1
        historical:
          type: boolean
          description: 'True indicates report on intervals preceding startInterval.

            False indicates report on intervals following startInterval (e.g. forecast).

            '
          example: true
          default: true
        frequency:
          type: integer
          format: int32
          description: 'Number of intervals that elapse between reports.

            -1 indicates same as numIntervals.

            '
          example: -1
          default: -1
        repeat:
          type: integer
          format: int32
          description: 'Number of times to repeat report.

            1 indicates generate one report.

            -1 indicates repeat indefinitely.

            '
          example: 1
          default: 1
    valuesMap:
      type: object
      description: 'Represents one or more values associated with a type.

        E.g. a type of PRICE contains a single float value.

        '
      required:
      - type
      - values
      properties:
        type:
          type: string
          description: 'Enumerated or private string signifying the nature of values.

            E.G. "PRICE" indicates value is to be interpreted as a currency.

            '
          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'
    resource:
      type: object
      description: 'A resource is an energy device or system subject to control by a VEN.

        '
      required:
      - resourceName
      properties:
        id:
          $ref: '#/components/schemas/objectID'
        createdDateTime:
          $ref: '#/components/schemas/dateTime'
        modificationDateTime:
          $ref: '#/components/schemas/dateTime'
        objectType:
          type: string
          description: Used as discriminator, e.g. notification.object
          enum:
          - RESOURCE
        resourceName:
          type:
          - string
          - 'null'
          description: User generated identifier, resource may be configured with identifier out-of-band.
          example: RESOURCE-999
          default: null
        venID:
          $ref: '#/components/schemas/objectID'
        attributes:
          type: array
          description: A list of valuesMap objects describing attributes.
          items:
            $ref: '#/components/schemas/valuesMap'
        targets:
          type: array
          description: A list of valuesMap objects describing target criteria.
          items:
            $ref: '#/components/schemas/valuesMap'
    report:
      type: object
      description: report object.
      required:
      - programID
      - eventID
      - clientName
      - resources
      properties:
        id:
          $ref: '#/components/schemas/objectID'
        createdDateTime:
          $ref: '#/components/schemas/dateTime'
        modificationDateTime:
          $ref: '#/components/schemas/dateTime'
        objectType:
          type: string
          description: Used as discriminator, e.g. notification.object
          enum:
          - REPORT
        programID:
          $ref: '#/components/schemas/objectID'
        eventID:
          $ref: '#/components/schemas/objectID'
        clientName:
          type:
          - string
          - 'null'
          description: User generated identifier; may be VEN ID provisioned during program enrollment.
          example: VEN-999
          default: null
        reportName:
          type:
          - string
          - 'null'
          description: User defined string for use in debugging or User Interface.
          example: Battery_usage_04112023
          default: null
        payloadDescriptors:
          type:
          - array
          - 'null'
          description: A list of reportPayloadDescriptors.
          default: null
          items:
            $ref: '#/components/schemas/reportPayloadDescriptor'
        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:
                type:
                - string
                - 'null'
                description: User generated identifier. A value of AGGREGATED_REPORT indicates an aggregation of more that one resource's data
                example: RESOURCE-999
                default: null
              intervalPeriod:
                $ref: '#/components/schemas/intervalPeriod'
              intervals:
                type: array
                description: A list of interval objects.
                items:
                  $ref: '#/components/schemas/interval'
    objectTypes:
      type: string
      description: Types of objects addressable through API.
      example: EVENT
      enum:
      - PROGRAM
      - EVENT
      - REPORT
      - SUBSCRIPTION
      - VEN
      - RESOURCE
    duration:
      type:
      - string
      - 'null'
      description: duration in ISO 8601 format
      example: PT1H
      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
          - 'null'
          format: float
          description: A value on an x axis.
          example: 1.0
          default: null
        y:
          type:
          - number
          - 'null'
          format: float
          description: A value on a y axis.
          example: 2.0
          default: null
    interval:
      type: object
      description: 'An object defining a temporal window and a list of valuesMaps.

        if intervalPeriod present may set temporal aspects of interval or override event.intervalPeriod.

        '
      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'
    dateTime:
      type:
      - string
      - 'null'
      description: datetime in ISO 8601 format
      example: 2023-06-15 09:30:00+00:00
      default: null
    notification:
      type: object
      description: 'VTN generated object included in request to subscription callbackUrl.

        '
      required:
      - objectType
      - operation
      - object
      properties:
        objectType:
          $ref: '#/components/schemas/objectTypes'
        operation:
          type: string
          description: the operation on on object that triggered the notification.
          example: POST
          enum:
          - GET
          - POST
          - PUT
          - DELETE
        targets:
          type:
          - array
          - 'null'
          description: A list of valuesMap objects.
          default: null
          items:
            $ref: '#/components/schemas/valuesMap'
        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
    intervalPeriod:
      type: object
      description: 'Defines temporal aspects of intervals.

        A duration of default null indicates infinity.

        A randomizeStart of default null indicates no randomization.

        '
      required:
      - start
      properties:
        start:
          $ref: '#/components/schemas/dateTime'
        duration:
          $ref: '#/components/schemas/duration'
        randomizeStart:
          $ref: '#/components/schemas/duration'
    event:
      type: object
      description: 'Event object to communicate a Demand Response request to VEN.

        If intervalPeriod is present, sets start time and duration of intervals.

        '
      required:
      - programID
      - intervals
      properties:
        id:
          $ref: '#/components/schemas/objectID'
        createdDateTime:
          $ref: '#/components/schemas/dateTime'
        modificationDateTime:
          $ref: '#/components/schemas/dateTime'
        objectType:
          type: string
          description: Used as discriminator, e.g. notification.object
          enum:
          - EVENT
        programID:
          $ref: '#/components/schemas/objectID'
        eventName:
          type:
          - string
          - 'null'
          description: User defined string for use in debugging or User Interface.
          example: price event 11-18-2022
          default: null
        priority:
          type:
          - integer
          - 'null'
          description: Relative priority of event. A lower number is a higher priority.
          example: 0
          default: null
        targets:
          type:
          - array
          - 'null'
          description: A list of valuesMap objects.
          default: null
          items:
            $ref: '#/components/schemas/valuesMap'
        reportDescriptors:
          type:
          - array
          - 'null'
          description: A list of reportDescriptor objects. Used to request reports from VEN.
          default: null
          items:
            $ref: '#/components/schemas/reportDescriptor'
        payloadDescriptors:
          type:
          - array
          - 'null'
          description: A list of payloadDescriptor objects.
          default: null
          items:
            $ref: '#/components/schemas/eventPayloadDescriptor'
        intervalPeriod:
          $ref: '#/components/schemas/intervalPeriod'
        intervals:
          type: array
          description: A list of interval objects.
          items:
            $ref: '#/components/schemas/interval'
    objectID:
      type: string
      pattern: ^[a-zA-Z0-9_-]*$
      minLength: 1
      maxLength: 128
      description: URL safe VTN assigned object ID.
      example: object-999
    subscription:
      type: object
      description: 'An object created by a client to receive notification of operations on objects.

        Clients may subscribe to be notified when a type of object is created,

        updated, or deleted.

        '
      required:
      - clientName
      - programID
      - objectOperations
      properties:
        id:
          $ref: '#/components/schemas/objectID'
        createdDateTime:
          $ref: '#/components/schemas/dateTime'
        modificationDateTime:
          $ref: '#/components/schemas/dateTime'
        objectType:
          type: string
          description: Used as discriminator, e.g. notification.object
          enum:
          - SUBSCRIPTION
        clientName:
          type:
          - string
          - 'null'
          description: User generated identifier, may be VEN identifier provisioned during program enrollment.
          example: VEN-999
          default: null
        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: POST
                  enum:
                  - GET
                  - POST
                  - PUT
                  - DELETE
              callbackUrl:
                type: string
                format: uri
                description: User provided webhook URL.
                example: https://myserver.com/send/callback/here
              bearerToken:
                type:
                - string
                - 'null'
                description: 'User provided token.

                  To avoid custom integrations, callback endpoints

                  should accept the provided bearer token to authenticate VTN requests.

                  '
                example: NCEJGI9E8ER9802UT9HUG
                default: null
        targets:
          type:
          - array
          - 'null'
          description: A list of valuesMap objects. Used by server to filter callbacks.
          default: null
          items:
            $ref: '#/components/schemas/valuesMap'
    reportPayloadDescriptor:
      type: object
      description: 'Contextual information used to interpret report payload values.

        E.g. a USAGE payload simply contains a usage value, an

        associated descriptor provides necessary context such as units and data quality.

        '
      required:
      - payloadType
      properties:
        objectType:
          type: string
          description: Used as discriminator, e.g. program.payloadDescriptors
          default: REPORT_PAYLOAD_DESCRIPTOR
        payloadType:
          type: string
          description: Enumerated or private string signifying the nature of values.
          example: USAGE
        readingType:
          type: string
          description: Enumerated or private string signifying the type of reading.
          example: DIRECT_READ
          default: DIRECT_READ
        units:
          type: string
          description: Units of measure.
          example: KWH
          default: KWH
        accuracy:
          type: number
          format: float
          description: A quantification of the accuracy of a set of payload values.
          example: 0.0
          default: 0.0
        confidence:
          type: integer
          format: int32
          minimum: 0
          maximum: 100
          description: A quantification of the confidence in a set of payload values.
          example: 100
          default: 100
    program:
      type: object
      description: Provides program specific metadata from VTN to VEN.
      required:
      - programName
      properties:
        id:
          $ref: '#/components/schemas/objectID'
        createdDateTime:
          $ref: '#/components/schemas/dateTime'
        modificationDateTime:
          $ref: '#/components/schemas/dateTime'
        objectType:
          type: string
          description: Used as discriminator, e.g. notification.object
          enum:
          - PROGRAM
        programName:
          type: string
          description: Short name to uniquely identify program.
          example: ResTOU
        programLongName:
          type:
          - string
          - 'null'
          description: Long name of program for human readability.
          example: Residential Time of Use-A
          default: null
        retailerName:
          type:
          - string
          - 'null'
          description: Short name of energy retailer providing the program.
          example: ACME
          default: null
        retailerLongName:
          type:
          - string
          - 'null'
          description: Long name of energy retailer for human readability.
          example: ACME Electric Inc.
          default: null
        programType:
          type:
          - string
          - 'null'
          description: A program defined categorization.
          example: PRICING_TARIFF
          default: null
        country:
          type:
          - string
          - 'null'
          description: Alpha-2 code per ISO 3166-1.
          example: US
          default: null
        principalSubdivision:
          type:
          - string
          - 'null'
          description: Coding per ISO 3166-2. E.g. state in US.
          example: CO
          default: null
        timeZoneOffset:
          $ref: '#/components/schemas/duration'
        intervalPeriod:
          $ref: '#/components/schemas/intervalPeriod'
        programDescriptions:
          type:
          - array
          - 'null'
          description: A list of programDescriptions
          default: null
          items:
            required:
            - URL
            properties:
              URL:
                type: string
                format: uri
                description: A human or machine readable program description
                example: www.myCorporation.com/myProgramDescription
        bindingEvents:
          type: boolean
          description: True if events are fixed once transmitted.
          example: false
          default: false
        localPrice:
          type: boolean
          description: True if events have been adapted from a grid event.
          example: false
          default: false
        payloadDescriptors:
          type:
          - array
          - 'null'
          description: A list of payloadDescriptors.
          default: null
          items:
            anyOf:
            - $ref: '#/components/schemas/eventPayloadDescriptor'
            - $ref: '#/components/schemas/reportPayloadDescriptor'
            discriminator:
              propertyName: objectType
        targets:
          type:
          - array
          - 'null'
          description: A list of valuesMap objects.
          default: null
          items:
            $ref: '#/components/schemas/valuesMap'
    ven:
      type: object
      description: Ven represents a client with the ven role.
      required:
      - venName
      properties:
        id:
          $ref: '#/components/schemas/objectID'
        createdDateTime:
          $ref: '#/components/schemas/dateTime'
        modificationDateTime:
          $ref: '#/components/schemas/dateTime'
        objectType:
          type: string
          description: Used as discriminator, e.g. notification.object.
          enum:
          - VEN
        venName:
          type:
          - string
          - 'null'
          description: User generated identifier, may be VEN identifier provisioned during program enrollment.
          example: VEN-999
          default: null
        attributes:
          type: array
          description: A list of valuesMap objects describing attributes.
          items:
            $ref: '#/components/schemas/valuesMap'
        targets:
          type: array
          description: A list of valuesMap objects describing target criteria.
          items:
            $ref: '#/components/schemas/valuesMap'
        resources:
          type:
          - array
          - 'null'
          description: A list of resource objects representing end-devices or systems.
          default: null
          items:
            $ref: '#/components/schemas/resource'
    problem:
      type: object
      description: 'reusable error response. From https://opensource.zalando.com/problem/schema.yaml.

        '
      properties:
        type:
          type: string
          format: uri
          description: 'An absolute URI that identifies the problem type.

            When dereferenced, it SHOULD provide human-readable documentation for the problem type

            (e.g., using HTML).

            '
          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

            for engineers (usually not suited for non technical stakeholders and

            not localized); example: Service Unavailable.

            '
        status:
          type: integer
          format: int32
          description: 'The HTTP status code generated by the origin server for this occurrence

            of the problem.

            '
          minimum: 100
          example: 503
          exclusiveMaximum: 600
        detail:
          type: string
          description: 'A human readable explanation specific to this occurrence of the

            problem.

            '
          example: Connection to database timed out
        instance:
          type: string
          format: uri
          description: 'An absolute URI that identifies the specific occurrence of the problem.

            It may or may not yield further information if dereferenced.

            '
    eventPayloadDescriptor:
      type: object
      description: 'Contextual information used to interpret event valuesMap values.

        E.g. a PRICE payload simply contains a price value, an

        associated descriptor provides necessary context such as units and currency.

     

# --- truncated at 32 KB (100 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openadr-alliance/refs/heads/main/openapi/openadr-alliance-subscriptions-api-openapi.yml