Subscriptions

search subscriptions

get

List all subscriptions. May filter results by programID and clientName as query params. May filter results by targetType and targetValues as query params. May filter results by objects as query param. See objectTypes schema. 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_-]*$

clientNamestringOptional

filter results to subscriptions with clientName.

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.

Responses

200

OK.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

500

Internal Server Error.

application/json

get

/subscriptions

HTTPcURLJavaScriptPython

GET /api/openadr/v1/subscriptions HTTP/1.1
Host: qa-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": "SUBSCRIPTION",
    "clientName": "VEN-999",
    "programID": "object-999",
    "objectOperations": [
      {
        "objects": [
          "EVENT"
        ],
        "operations": [
          "POST"
        ],
        "callbackUrl": "https://myserver.com/send/callback/here",
        "bearerToken": "NCEJGI9E8ER9802UT9HUG"
      }
    ],
    "targets": [
      {
        "type": "PRICE",
        "values": [
          0.17
        ]
      }
    ]
  }
]

create subscription

post

Create a new subscription.

Required scopes

This endpoint requires the following scopes:

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

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.

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:

clientNamestring · min: 1 · max: 128Required

User generated identifier, may be VEN identifier provisioned out-of-band.

Example: VEN-999

programIDstring · min: 1 · max: 128Required

URL safe VTN assigned object ID.

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

Responses

201

Created.

application/json

400

Bad Request.

application/json

403

Forbidden.

application/json

409

Conflict. Implementation dependent response if identical object already exists.

application/json

500

Internal Server Error.

application/json

post

/subscriptions

HTTPcURLJavaScriptPython

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

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "SUBSCRIPTION",
  "clientName": "VEN-999",
  "programID": "object-999",
  "objectOperations": [
    {
      "objects": [
        "EVENT"
      ],
      "operations": [
        "POST"
      ],
      "callbackUrl": "https://myserver.com/send/callback/here",
      "bearerToken": "NCEJGI9E8ER9802UT9HUG"
    }
  ],
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ]
}

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "SUBSCRIPTION",
  "clientName": "VEN-999",
  "programID": "object-999",
  "objectOperations": [
    {
      "objects": [
        "EVENT"
      ],
      "operations": [
        "POST"
      ],
      "callbackUrl": "https://myserver.com/send/callback/here",
      "bearerToken": "NCEJGI9E8ER9802UT9HUG"
    }
  ],
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ]
}

search subscriptions by ID

get

Return the subscription specified by subscriptionID specified in path.

Required scopes

This endpoint requires the following scopes:

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

subscriptionIDstring · 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

/subscriptions/{subscriptionID}

HTTPcURLJavaScriptPython

GET /api/openadr/v1/subscriptions/{subscriptionID} HTTP/1.1
Host: qa-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": "SUBSCRIPTION",
  "clientName": "VEN-999",
  "programID": "object-999",
  "objectOperations": [
    {
      "objects": [
        "EVENT"
      ],
      "operations": [
        "POST"
      ],
      "callbackUrl": "https://myserver.com/send/callback/here",
      "bearerToken": "NCEJGI9E8ER9802UT9HUG"
    }
  ],
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ]
}

update subscription

put

Update the subscription specified by subscriptionID specified in path.

Required scopes

This endpoint requires the following scopes:

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

subscriptionIDstring · min: 1 · max: 128Required

URL safe VTN assigned object ID.

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

Body

application/json

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.

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:

clientNamestring · min: 1 · max: 128Required

User generated identifier, may be VEN identifier provisioned out-of-band.

Example: VEN-999

programIDstring · 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

409

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

application/json

500

Internal Server Error.

application/json

put

/subscriptions/{subscriptionID}

HTTPcURLJavaScriptPython

PUT /api/openadr/v1/subscriptions/{subscriptionID} HTTP/1.1
Host: qa-vtn3.switchmarket.se
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 386

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "SUBSCRIPTION",
  "clientName": "VEN-999",
  "programID": "object-999",
  "objectOperations": [
    {
      "objects": [
        "EVENT"
      ],
      "operations": [
        "POST"
      ],
      "callbackUrl": "https://myserver.com/send/callback/here",
      "bearerToken": "NCEJGI9E8ER9802UT9HUG"
    }
  ],
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ]
}

{
  "id": "object-999",
  "createdDateTime": "2023-06-15T09:30:00Z",
  "modificationDateTime": "2023-06-15T09:30:00Z",
  "objectType": "SUBSCRIPTION",
  "clientName": "VEN-999",
  "programID": "object-999",
  "objectOperations": [
    {
      "objects": [
        "EVENT"
      ],
      "operations": [
        "POST"
      ],
      "callbackUrl": "https://myserver.com/send/callback/here",
      "bearerToken": "NCEJGI9E8ER9802UT9HUG"
    }
  ],
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ]
}

delete subscription

delete

Delete the subscription specified by subscriptionID specified in path.

Required scopes

This endpoint requires the following scopes:

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

subscriptionIDstring · 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

/subscriptions/{subscriptionID}

HTTPcURLJavaScriptPython

DELETE /api/openadr/v1/subscriptions/{subscriptionID} HTTP/1.1
Host: qa-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": "SUBSCRIPTION",
  "clientName": "VEN-999",
  "programID": "object-999",
  "objectOperations": [
    {
      "objects": [
        "EVENT"
      ],
      "operations": [
        "POST"
      ],
      "callbackUrl": "https://myserver.com/send/callback/here",
      "bearerToken": "NCEJGI9E8ER9802UT9HUG"
    }
  ],
  "targets": [
    {
      "type": "PRICE",
      "values": [
        0.17
      ]
    }
  ]
}