The Span API does not at this time require any authentication. This will probably change in the future.
Description: Gets panel summary, firmware version, door state, serial number, network status Request: GET /api/v1/status Response:
{
"software": {
"firmwareVersion": "spanos2/r202216/04",
"updateStatus": "idle",
"env": "prod"
},
"system": {
"manufacturer": "Span",
"serial": "nt-2139-c1ac4",
"model": "00200",
"doorState": "OPEN",
"uptime": 1475028
},
"network": {
"eth0Link": false,
"wlanLink": true,
"wwanLink": false
}
}Description: Gets panel state, grid state, power draw for whole panel, and for each breaker Request: GET /api/v1/panel Response:
{
"mainRelayState": "CLOSED",
"instantGridPowerW": 8361.962890625,
"feedthroughPowerW": -82.79021826386452,
"gridSampleStartMs": 836674,
"gridSampleEndMs": 836686,
"dsmGridState": "DSM_GRID_UP",
"dsmState": "DSM_ON_GRID",
"currentRunConfig": "PANEL_ON_GRID",
"branches": [
{
"id": 1,
"relayState": "CLOSED",
"instantPowerW": -3.015791177749634,
"importedActiveEnergyWh": 1.4696391820907593,
"exportedActiveEnergyWh": 12594.255859375
},
{
"id": 2,
"relayState": "CLOSED",
"instantPowerW": -8.53760051727295,
"importedActiveEnergyWh": 343.6731262207031,
"exportedActiveEnergyWh": 19945.1328125
},
{
"id": 3,
"relayState": "CLOSED",
"instantPowerW": -4.699003219604492,
"importedActiveEnergyWh": 27.433591842651367,
"exportedActiveEnergyWh": 6132.89697265625
},
...
]
}Description: Get information on individual breakers, their positions, names, state, priority Request: GET /api/v1/circuits Response:
{
"spaces": {
"xxxxxxxxxxxxxxx": {
"id": "xxxxxxxxxxxxxxx",
"name": "Garage 220",
"relayState": "CLOSED",
"instantPowerW": -3625.2879638671875,
"instantPowerUpdateTimeS": 1656531017,
"importEnergyAccumWh": 4146.5565185546875,
"exportEnergyAccumWh": 313066.625,
"energyAccumUpdateTimeS": 1656530716,
"tabs": [
12,
14
],
"priority": "NOT_ESSENTIAL",
"is_user_controllable": true,
"is_sheddable": false,
"is_never_backup": false
},
"xxxxxxxxxxxxxxx": {
"id": "xxxxxxxxxxxxxxx",
"name": "A/C condeser",
"relayState": "CLOSED",
"instantPowerW": -2428.6781005859375,
"instantPowerUpdateTimeS": 1656531017,
"importEnergyAccumWh": 11638.456787109375,
"exportEnergyAccumWh": 752839.09375,
"energyAccumUpdateTimeS": 1656530716,
"tabs": [
16,
18
],
"priority": "MUST_HAVE",
"is_user_controllable": true,
"is_sheddable": false,
"is_never_backup": false
},
"xxxxxxxxxxxxxxx": {
"id": "xxxxxxxxxxxxxxx",
"name": "Tesla charger",
"relayState": "CLOSED",
"instantPowerW": -503.9554138183594,
"instantPowerUpdateTimeS": 1656531017,
"importEnergyAccumWh": 30.012138724327087,
"exportEnergyAccumWh": 218781.4375,
"energyAccumUpdateTimeS": 1656530716,
"tabs": [
26,
28
],
"priority": "NICE_TO_HAVE",
"is_user_controllable": true,
"is_sheddable": false,
"is_never_backup": false
},
...
}
}Description: Change breaker state, turn on/off a breaker Valid Values: OPEN, CLOSED Request: POST /api/v1/circuits/xxxxxxxxxxxxxxx
{
"relay_state_in": {
"relayState":"OPEN"
}
}Response:
{
"id":"xxxxxxxxxxxxxxx",
"name":"Garage outlets*",
"relayState":"OPEN",
"instantPowerW":0.0,
"instantPowerUpdateTimeS":1656538555,
"importEnergyAccumWh":722.7332153320312,
"exportEnergyAccumWh":973.8363037109375,
"energyAccumUpdateTimeS":1656538493,
"tabs":[6],
"priority":"NOT_ESSENTIAL",
"is_user_controllable":true,
"is_sheddable":false,
"is_never_backup":false
}Description: Change breaker priority Valid Values: MUST_HAVE, NICE_TO_HAVE, NOT_ESSENTIAL Request: POST /api/v1/circuits/xxxxxxxxxxxxxxx
{
"priority_in": {
"priority":"NICE_TO_HAVE"
}
}Response:
{
"id":"xxxxxxxxxxxxxxx",
"name":"Garage outlets*",
"relayState":"OPEN",
"instantPowerW":0.0,
"instantPowerUpdateTimeS":1656539097,
"importEnergyAccumWh":722.7332153320312,
"exportEnergyAccumWh":973.8363037109375,
"energyAccumUpdateTimeS":1656538493,
"tabs":[6],
"priority":"NICE_TO_HAVE",
"is_user_controllable":true,
"is_sheddable":false,
"is_never_backup":false
}
hey look what i found ...
(this is all unverified, so far some of it works for me, some does not)
Register New Client
Register New Client POST
/api/v1/auth/register
This API enables a new client to be registered with the SPAN Panel, including information such as name and description. In return the SPAN Panel returns an access token which is to be included with all other API requests. Below is an example of the command using the initial access token and where name = SPAN_API_User_2, and description = SPAN_API_User_2 description.
$ curl -X 'POST'
'http://192.168.40.30/api/v1/auth/register'
-H 'accept: application/json'
-H 'Content-Type: application/json'
-d '{
"name": "SPAN_API_User_2",
"description": "SPAN_API_User_2 description",
}'
The response is a 200 on success, or a 422 Validation Error.
The annotated 200 response schema is as follows where:
name – user defined name for the client to be added
description – user defined description of the client to be added
{ "name": "string", "description": "string" }Example: annotated 422 response schema
{ "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] }Example of a 200 (success) response:
{ "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJzdHJpbmciLCJpYXQiOjE2NjI2MTEyODV9.tekwsKeaT9GW7bRrpOcyVxWRHn21qQOX897F4Zp-du0", "tokenType": "bearer" }Take note of the accessToken string as this will be required for all other API interactions.
View All Clients
This API returns the list of all authenticated clients registered with the SPAN Panel, including information such as name, description, and access control group. Below is an example of the command using the initial accessToken.
$ curl -X 'GET'
'http://192.168.40.30/api/v1/auth/clients/'
-H 'accept: application/json'
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJTaG9vcCIsImlhdCI6MTY2MjU5NDAxNn0.WH2_9gfz7YSsnRymPERWmfn_ic5x4BLvKfkO2ByzMxk'
The response is a 200 on success.
The annotated 200 response schema is as follows, where:
additionalProp# - returns the user defined name of the client added
description – returns a user defined short description for the client added
issued_at – returns the epoch date and time the client was added as an authorized client. This may be converted into a human readable date and time using an epoch converter.
allowed_endpoint_groups – returns the permission settings for each endpoint function; Delete, Get, Post, and Push.
{ "clients": { "additionalProp1": { "description": "string", "issued_at": 0, "allowed_endpoint_groups": { "delete": [ "string" ], "get": [ "string" ], "post": [ "string" ], "push": [ "string" ] } } } }An example 200 response is shown below, listing one client “SPAN_API_User_1” has been authorized for “SPAN API User 1” at issuance date of 1662561023 or Sept 7, 2022 at 2:30P GMT, and contains the “homeowner” permission settings for each API function.
{ "clients": { "SPAN_API_User_1": { "description": "SPAN API User1", "issued_at": 1662561023, "allowed_endpoint_groups": { "delete": [ "homeowner" ], "get": [ "homeonwer" ], "post": [ "homeowner" ], "push": [ "homeowner" ] } } } }View {name} Client
This API returns the status of the specified client registered with the SPAN Panel, including information such as description and authentication date. Below is an example of the command using the initial accessToken.
$ curl -X 'GET'
'http://192.168.40.30/api/v1/auth/clients/SPAN_API_User_1'
-H 'accept: application/json'
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJTaG9vcCIsImlhdCI6MTY2MjU5NDAxNn0.WH2_9gfz7YSsnRymPERWmfn_ic5x4BLvKfkO2ByzMxk'
The response is a 200 on success and 422 on error.
The annotated 200 response schema is as follows, where:
additionalProp# - returns the user defined name of the client added
description – returns a user defined short description for the client added
issued_at – returns the epoch date and time the client was added as an authorized client. This may be converted into a human readable date and time using an epoch converter.
allowed_endpoint_groups – returns the access control settings for API request types made by the client.
{ "description": "string", "issued_at": 0, "allowed_endpoint_groups": { "delete": [ "string" ], "get": [ "string" ], "post": [ "string" ], "push": [ "string" ] } }The annotated 422 response schema is as follows:
{ "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] } }An example 200 response is shown below, listing one client “SPAN_API_User_1” has been authorized for “SPAN API User1” at issuance date of 1662561023 or Sept 7, 2022 at 2:30P GMT, and contains the “homeowner” permission settings for each API function.
{ "clients": { "SPAN_API_User_1": { "description": "SPAN_Product_Management", "issued_at": 1662561023, "allowed_endpoint_groups": { "delete": [ "homeowner" ], "get": [ "homeonwer" ], "post": [ "homeowner" ], "push": [ "homeowner" ] } } } }Delete {name} Client
This API enables a specified client, short description and associated accessToken to be removed from the registry of the SPAN Panel. Below is an example of the command using the initial accessToken.
$ curl -X 'DELETE'
'http://192.168.40.30/api/v1/auth/clients/SPAN_API_User_1'
-H 'accept: application/json'
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJTaG9vcCIsImlhdCI6MTY2MjU5NDAxNn0.WH2_9gfz7YSsnRymPERWmfn_ic5x4BLvKfkO2ByzMxk'
The response is a 200 on success and a 422 on Error.
The annotated 200 response schema is as follows, where:
additionalProp# - returns the user defined name of the client added
description – returns a user defined short description for the client added
issued_at – returns the epoch date and time the client was added as an authorized client. This may be converted into a human readable date and time using an epoch converter.
allowed_endpoint_groups – returns the access control settings for API request types made by the client.
{ "description": "string", "issued_at": 0, "allowed_endpoint_groups": { "delete": [ "string" ], "get": [ "string" ], "post": [ "string" ], "push": [ "string" ] } }The annotated 422 response schema is as follows:
{ "detail": [ { "loc": [ "string" ], "msg": "string", "type": "string" } ] }An example 200 response is shown below, listing one client “SPAN_API_User_1” has been authorized for “SPAN API User1” at issuance date of 1662561023 or Sept 7, 2022 at 2:30P GMT, and contains the “homeowner” permission settings for each API function.
{ "clients": { "SPAN_API_User_1": { "description": "SPAN API User1", "issued_at": 1662561023, "allowed_endpoint_groups": { "delete": [ "homeowner" ], "get": [ "homeonwer" ], "post": [ "homeowner" ], "push": [ "homeowner" ] } } } }