This is a development version of the documentation. Content may change without notice.
Voke Documentation
ReferenceREST API

Device Templates

Global signal maps and command vocabularies

List device templates (global catalog)

GET
/api/v1/device-templates

Query Parameters

level?string

Filter templates by assignment level (PLANT or SUB_DEVICE).

Value in"PLANT" | "SUB_DEVICE"

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://loading/api/v1/device-templates"
{
  "actions": [
    {}
  ],
  "createdAt": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "isSystem": true,
  "level": "PLANT",
  "name": "string",
  "signals": [
    {}
  ],
  "type": "CABINET",
  "updatedAt": "2019-08-24T14:15:22Z",
  "version": 0
}
{
  "code": "VALIDATION_ERROR",
  "details": {},
  "error": "Bad Request",
  "message": "Invalid query parameter (e.g. unknown level value)",
  "statusCode": 400
}
{
  "code": "UNAUTHORIZED",
  "details": {},
  "error": "Unauthorized",
  "message": "Unauthorized",
  "statusCode": 400
}
{
  "code": "FORBIDDEN",
  "details": {},
  "error": "Forbidden",
  "message": "Forbidden — writes require super-admin",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

Create a device template (super-admin only)

POST
/api/v1/device-templates

Request Body

application/json

actions?array<>

Command action vocabulary with typed params

level?string
Default"SUB_DEVICE"
Value in"PLANT" | "SUB_DEVICE"
name*string

Template display name

Length1 <= length <= 120
signals*array<>

Signal definitions — binary (with bit) or numeric (with field)

type*string
Value in"CABINET" | "METER" | "INVERTER" | "BATTERY"
version?number

Template version

Default1
Range1 <= value

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://loading/api/v1/device-templates" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "signals": [      {}    ],    "type": "CABINET"  }'
{
  "actions": [
    {}
  ],
  "createdAt": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "isSystem": true,
  "level": "PLANT",
  "name": "string",
  "signals": [
    {}
  ],
  "type": "CABINET",
  "updatedAt": "2019-08-24T14:15:22Z",
  "version": 0
}
{
  "code": "VALIDATION_ERROR",
  "details": {},
  "error": "Bad Request",
  "message": "Invalid signal or action definitions",
  "statusCode": 400
}
{
  "code": "UNAUTHORIZED",
  "details": {},
  "error": "Unauthorized",
  "message": "Unauthorized",
  "statusCode": 400
}
{
  "code": "FORBIDDEN",
  "details": {},
  "error": "Forbidden",
  "message": "Forbidden — writes require super-admin",
  "statusCode": 400
}
{
  "code": "CONFLICT",
  "details": {},
  "error": "Conflict",
  "message": "Template name + version already exists",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

Get a device template by ID

GET
/api/v1/device-templates/{id}

Path Parameters

id*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://loading/api/v1/device-templates/string"
{
  "actions": [
    {}
  ],
  "createdAt": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "isSystem": true,
  "level": "PLANT",
  "name": "string",
  "signals": [
    {}
  ],
  "type": "CABINET",
  "updatedAt": "2019-08-24T14:15:22Z",
  "version": 0
}
{
  "code": "INVALID_UUID",
  "details": {},
  "error": "Bad Request",
  "message": "Invalid UUID",
  "statusCode": 400
}
{
  "code": "UNAUTHORIZED",
  "details": {},
  "error": "Unauthorized",
  "message": "Unauthorized",
  "statusCode": 400
}
{
  "code": "FORBIDDEN",
  "details": {},
  "error": "Forbidden",
  "message": "Forbidden — writes require super-admin",
  "statusCode": 400
}
{
  "code": "DEVICE_TEMPLATE_NOT_FOUND",
  "details": {},
  "error": "Not Found",
  "message": "Template not found",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

Update a device template (super-admin only; editing signals bumps version)

PATCH
/api/v1/device-templates/{id}

Path Parameters

id*string

Request Body

application/json

actions?array<>
name?string
Length1 <= length <= 120
signals?array<>

Signal definitions — editing signals bumps version

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://loading/api/v1/device-templates/string" \  -H "Content-Type: application/json" \  -d '{}'
{
  "actions": [
    {}
  ],
  "createdAt": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "isSystem": true,
  "level": "PLANT",
  "name": "string",
  "signals": [
    {}
  ],
  "type": "CABINET",
  "updatedAt": "2019-08-24T14:15:22Z",
  "version": 0
}
{
  "code": "VALIDATION_ERROR",
  "details": {},
  "error": "Bad Request",
  "message": "Invalid UUID or payload",
  "statusCode": 400
}
{
  "code": "UNAUTHORIZED",
  "details": {},
  "error": "Unauthorized",
  "message": "Unauthorized",
  "statusCode": 400
}
{
  "code": "DEVICE_TEMPLATE_SYSTEM_READONLY",
  "details": {},
  "error": "Forbidden",
  "message": "System templates are read-only",
  "statusCode": 400
}
{
  "code": "DEVICE_TEMPLATE_NOT_FOUND",
  "details": {},
  "error": "Not Found",
  "message": "Template not found",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

Delete a device template (super-admin only; blocked when in use)

DELETE
/api/v1/device-templates/{id}

Path Parameters

id*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://loading/api/v1/device-templates/string"
{
  "message": "string"
}
{
  "code": "INVALID_UUID",
  "details": {},
  "error": "Bad Request",
  "message": "Invalid UUID",
  "statusCode": 400
}
{
  "code": "UNAUTHORIZED",
  "details": {},
  "error": "Unauthorized",
  "message": "Unauthorized",
  "statusCode": 400
}
{
  "code": "DEVICE_TEMPLATE_SYSTEM_READONLY",
  "details": {},
  "error": "Forbidden",
  "message": "System templates are read-only",
  "statusCode": 400
}
{
  "code": "DEVICE_TEMPLATE_NOT_FOUND",
  "details": {},
  "error": "Not Found",
  "message": "Template not found",
  "statusCode": 400
}
{
  "code": "DEVICE_TEMPLATE_IN_USE",
  "details": {},
  "error": "Conflict",
  "message": "Template is referenced by one or more sub-devices",
  "statusCode": 400
}
{
  "code": "INTERNAL_SERVER_ERROR",
  "details": {},
  "error": "Internal Server Error",
  "message": "Internal server error",
  "statusCode": 400
}

Commands

Plant commands

Health

Health checks