Events

searches all events

get

List all events known to the server. May filter results by programID query param. May filter results by targetType and targetValues as query params. Use skip and pagination query params to limit response size.

Required scopes

This endpoint requires the following scopes:

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

programIDstring · min: 1 · max: 128Optional

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

targetTypestringOptional

Indicates targeting type, e.g. GROUP

targetValuesstring[]Optional

List of target values, e.g. group names

skipinteger · int32Optional

number of records to skip for pagination.

limitinteger · int32 · max: 50Optional

maximum number of records to return.

x-startstring · date-timeOptional

start of timeperiod for which to return events (extension - not part of the OpenADR specification)

x-endstring · date-timeOptional

end of timeperiod for which to return events (extension - not part of the OpenADR specification)

Responses

200

OK.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

500

Internal Server Error.

application/json

get

/events

HTTPcURLJavaScriptPython

GET /api/openadr/v1/events HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": "object-999",
    "createdDateTime": "2023-06-15T09:30:00Z",
    "modificationDateTime": "2023-06-15T09:30:00Z",
    "objectType": "EVENT",
    "programID": "object-999",
    "eventName": "price event 11-18-2022",
    "priority": 0,
    "targets": [
      {
        "type": "PRICE",
        "values": [
          0.17
        ]
      }
    ],
    "reportDescriptors": [
      {
        "payloadType": "USAGE",
        "readingType": "DIRECT_READ",
        "units": "KWH",
        "targets": [
          {
            "type": "PRICE",
            "values": [
              0.17
            ]
          }
        ],
        "aggregate": false,
        "startInterval": -1,
        "numIntervals": -1,
        "historical": true,
        "frequency": -1,
        "repeat": 1
      }
    ],
    "payloadDescriptors": [
      {
        "objectType": "EVENT_PAYLOAD_DESCRIPTOR",
        "payloadType": "PRICE",
        "units": "KWH",
        "currency": "USD"
      }
    ],
    "intervalPeriod": {
      "start": "2023-06-15T09:30:00Z",
      "duration": "PT1H",
      "randomizeStart": "PT1H"
    },
    "intervals": [
      {
        "id": 0,
        "intervalPeriod": {
          "start": "2023-06-15T09:30:00Z",
          "duration": "PT1H",
          "randomizeStart": "PT1H"
        },
        "payloads": [
          {
            "type": "PRICE",
            "values": [
              0.17
            ]
          }
        ]
      }
    ]
  }
]

create an event

post

Create a new event in the server.

Required scopes

This endpoint requires the following scopes:

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

Event object to communicate a Demand Response request to VEN. If intervalPeriod is present, sets default start time and duration of intervals.

idstring · min: 1 · max: 128Optional

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

createdDateTimestring · date-timeOptional

datetime in ISO 8601 format

Example: 2023-06-15T09:30:00Z

modificationDateTimestring · date-timeOptional

datetime in ISO 8601 format

Example: 2023-06-15T09:30:00Z

objectTypestring · enumOptional

Used as discriminator

Possible values:

programIDstring · min: 1 · max: 128Required

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

eventNamestring | nullableOptional

User defined string for use in debugging or User Interface.

Default: nullExample: price event 11-18-2022

priorityinteger | nullableOptional

Relative priority of event. A lower number is a higher priority.

Default: nullExample: 0

Responses

201

Created.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

409

Conflict. Implementation dependent response if event with same name already exists.

application/json

500

Internal Server Error.

application/json

post

/events

HTTPcURLJavaScriptPython

POST /api/openadr/v1/events HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 850

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "EVENT",
  "programID": "object-999",
  "eventName": "price event 11-18-2022",
  "priority": 0,
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ],
  "reportDescriptors": [
    {
      "payloadType": "USAGE",
      "readingType": "DIRECT_READ",
      "units": "KWH",
      "targets": [
        {
          "type": "PRICE",
          "values": [
            0.17
          ]
        }
      ],
      "aggregate": false,
      "startInterval": -1,
      "numIntervals": -1,
      "historical": true,
      "frequency": -1,
      "repeat": 1
    }
  ],
  "payloadDescriptors": [
    {
      "objectType": "EVENT_PAYLOAD_DESCRIPTOR",
      "payloadType": "PRICE",
      "units": "KWH",
      "currency": "USD"
    }
  ],
  "intervalPeriod": {
    "start": "2023-06-15T09:30:00Z",
    "duration": "PT1H",
    "randomizeStart": "PT1H"
  },
  "intervals": [
    {
      "id": 0,
      "intervalPeriod": {
        "start": "2023-06-15T09:30:00Z",
        "duration": "PT1H",
        "randomizeStart": "PT1H"
      },
      "payloads": [
        {
          "type": "PRICE",
          "values": [
            0.17
          ]
        }
      ]
    }
  ]
}

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "EVENT",
  "programID": "object-999",
  "eventName": "price event 11-18-2022",
  "priority": 0,
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ],
  "reportDescriptors": [
    {
      "payloadType": "USAGE",
      "readingType": "DIRECT_READ",
      "units": "KWH",
      "targets": [
        {
          "type": "PRICE",
          "values": [
            0.17
          ]
        }
      ],
      "aggregate": false,
      "startInterval": -1,
      "numIntervals": -1,
      "historical": true,
      "frequency": -1,
      "repeat": 1
    }
  ],
  "payloadDescriptors": [
    {
      "objectType": "EVENT_PAYLOAD_DESCRIPTOR",
      "payloadType": "PRICE",
      "units": "KWH",
      "currency": "USD"
    }
  ],
  "intervalPeriod": {
    "start": "2023-06-15T09:30:00Z",
    "duration": "PT1H",
    "randomizeStart": "PT1H"
  },
  "intervals": [
    {
      "id": 0,
      "intervalPeriod": {
        "start": "2023-06-15T09:30:00Z",
        "duration": "PT1H",
        "randomizeStart": "PT1H"
      },
      "payloads": [
        {
          "type": "PRICE",
          "values": [
            0.17
          ]
        }
      ]
    }
  ]
}

search events by ID

get

Fetch event associated with the eventID in path.

Required scopes

This endpoint requires the following scopes:

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

eventIDstring · min: 1 · max: 128Required

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

Responses

200

OK.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

404

Not Found.

application/json

500

Internal Server Error.

application/json

get

/events/{eventID}

HTTPcURLJavaScriptPython

GET /api/openadr/v1/events/{eventID} HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "EVENT",
  "programID": "object-999",
  "eventName": "price event 11-18-2022",
  "priority": 0,
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ],
  "reportDescriptors": [
    {
      "payloadType": "USAGE",
      "readingType": "DIRECT_READ",
      "units": "KWH",
      "targets": [
        {
          "type": "PRICE",
          "values": [
            0.17
          ]
        }
      ],
      "aggregate": false,
      "startInterval": -1,
      "numIntervals": -1,
      "historical": true,
      "frequency": -1,
      "repeat": 1
    }
  ],
  "payloadDescriptors": [
    {
      "objectType": "EVENT_PAYLOAD_DESCRIPTOR",
      "payloadType": "PRICE",
      "units": "KWH",
      "currency": "USD"
    }
  ],
  "intervalPeriod": {
    "start": "2023-06-15T09:30:00Z",
    "duration": "PT1H",
    "randomizeStart": "PT1H"
  },
  "intervals": [
    {
      "id": 0,
      "intervalPeriod": {
        "start": "2023-06-15T09:30:00Z",
        "duration": "PT1H",
        "randomizeStart": "PT1H"
      },
      "payloads": [
        {
          "type": "PRICE",
          "values": [
            0.17
          ]
        }
      ]
    }
  ]
}

update an event

put

Update the event specified by the eventID in path.

Required scopes

This endpoint requires the following scopes:

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

eventIDstring · min: 1 · max: 128Required

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

Body

application/json

Event object to communicate a Demand Response request to VEN. If intervalPeriod is present, sets default start time and duration of intervals.

idstring · min: 1 · max: 128Optional

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

createdDateTimestring · date-timeOptional

datetime in ISO 8601 format

Example: 2023-06-15T09:30:00Z

modificationDateTimestring · date-timeOptional

datetime in ISO 8601 format

Example: 2023-06-15T09:30:00Z

objectTypestring · enumOptional

Used as discriminator

Possible values:

programIDstring · min: 1 · max: 128Required

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

eventNamestring | nullableOptional

User defined string for use in debugging or User Interface.

Default: nullExample: price event 11-18-2022

priorityinteger | nullableOptional

Relative priority of event. A lower number is a higher priority.

Default: nullExample: 0

Responses

200

OK.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

404

Not Found.

application/json

409

Conflict. Implementation dependent response if program with the same programName exists.

application/json

500

Internal Server Error.

application/json

put

/events/{eventID}

HTTPcURLJavaScriptPython

PUT /api/openadr/v1/events/{eventID} HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 850

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "EVENT",
  "programID": "object-999",
  "eventName": "price event 11-18-2022",
  "priority": 0,
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ],
  "reportDescriptors": [
    {
      "payloadType": "USAGE",
      "readingType": "DIRECT_READ",
      "units": "KWH",
      "targets": [
        {
          "type": "PRICE",
          "values": [
            0.17
          ]
        }
      ],
      "aggregate": false,
      "startInterval": -1,
      "numIntervals": -1,
      "historical": true,
      "frequency": -1,
      "repeat": 1
    }
  ],
  "payloadDescriptors": [
    {
      "objectType": "EVENT_PAYLOAD_DESCRIPTOR",
      "payloadType": "PRICE",
      "units": "KWH",
      "currency": "USD"
    }
  ],
  "intervalPeriod": {
    "start": "2023-06-15T09:30:00Z",
    "duration": "PT1H",
    "randomizeStart": "PT1H"
  },
  "intervals": [
    {
      "id": 0,
      "intervalPeriod": {
        "start": "2023-06-15T09:30:00Z",
        "duration": "PT1H",
        "randomizeStart": "PT1H"
      },
      "payloads": [
        {
          "type": "PRICE",
          "values": [
            0.17
          ]
        }
      ]
    }
  ]
}

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "EVENT",
  "programID": "object-999",
  "eventName": "price event 11-18-2022",
  "priority": 0,
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ],
  "reportDescriptors": [
    {
      "payloadType": "USAGE",
      "readingType": "DIRECT_READ",
      "units": "KWH",
      "targets": [
        {
          "type": "PRICE",
          "values": [
            0.17
          ]
        }
      ],
      "aggregate": false,
      "startInterval": -1,
      "numIntervals": -1,
      "historical": true,
      "frequency": -1,
      "repeat": 1
    }
  ],
  "payloadDescriptors": [
    {
      "objectType": "EVENT_PAYLOAD_DESCRIPTOR",
      "payloadType": "PRICE",
      "units": "KWH",
      "currency": "USD"
    }
  ],
  "intervalPeriod": {
    "start": "2023-06-15T09:30:00Z",
    "duration": "PT1H",
    "randomizeStart": "PT1H"
  },
  "intervals": [
    {
      "id": 0,
      "intervalPeriod": {
        "start": "2023-06-15T09:30:00Z",
        "duration": "PT1H",
        "randomizeStart": "PT1H"
      },
      "payloads": [
        {
          "type": "PRICE",
          "values": [
            0.17
          ]
        }
      ]
    }
  ]
}

delete an event

delete

Delete the event specified by the eventID in path.

Required scopes

This endpoint requires the following scopes:

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

eventIDstring · min: 1 · max: 128Required

URL safe VTN assigned object ID.

Example: object-999Pattern: ^[a-zA-Z0-9_-]*$

Responses

200

OK.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

404

Not Found.

application/json

500

Internal Server Error.

application/json

delete

/events/{eventID}

HTTPcURLJavaScriptPython

DELETE /api/openadr/v1/events/{eventID} HTTP/1.1
Host: vtn3.switchmarket.se
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "EVENT",
  "programID": "object-999",
  "eventName": "price event 11-18-2022",
  "priority": 0,
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ],
  "reportDescriptors": [
    {
      "payloadType": "USAGE",
      "readingType": "DIRECT_READ",
      "units": "KWH",
      "targets": [
        {
          "type": "PRICE",
          "values": [
            0.17
          ]
        }
      ],
      "aggregate": false,
      "startInterval": -1,
      "numIntervals": -1,
      "historical": true,
      "frequency": -1,
      "repeat": 1
    }
  ],
  "payloadDescriptors": [
    {
      "objectType": "EVENT_PAYLOAD_DESCRIPTOR",
      "payloadType": "PRICE",
      "units": "KWH",
      "currency": "USD"
    }
  ],
  "intervalPeriod": {
    "start": "2023-06-15T09:30:00Z",
    "duration": "PT1H",
    "randomizeStart": "PT1H"
  },
  "intervals": [
    {
      "id": 0,
      "intervalPeriod": {
        "start": "2023-06-15T09:30:00Z",
        "duration": "PT1H",
        "randomizeStart": "PT1H"
      },
      "payloads": [
        {
          "type": "PRICE",
          "values": [
            0.17
          ]
        }
      ]
    }
  ]
}