SPAN

SPAN REST API

Local on-premise HTTP/JSON REST API hosted directly on SPAN Panel. The API exposes authentication (registering API clients and obtaining JWT access tokens), system status, Wi-Fi scan and connect, panel state, main meter, panel power, islanding state, per-circuit control, panel grid relay control, emergency reconnect, and energy storage state-of-energy and nice-to-have thresholds. All access is local-only on the home LAN; authentication uses HTTP Bearer JWT credentials minted by the panel itself. Available initially on SPAN Panel MAIN 32 with firmware r202603 and later, with rollout to MAIN 16 / MLO 24 / MAIN 40 / MLO 48 planned for the second half of 2026.

SPAN REST API is one of 2 APIs that SPAN publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

This API exposes 5 machine-runnable capabilities that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko and 1 JSON Schema definition.

Tagged areas include Energy, Home Energy, Smart Panel, REST, and On-Premise. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, a JSON-LD context, 5 Naftiko capability specs, and 1 JSON Schema.

GitHub OpenAPI

Documentation

📖
Documentation
https://github.com/spanio/SPAN-API-Client-Docs
📖
Documentation
https://github.com/spanio/SPAN-API-Client-Docs/blob/main/README.md

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/span-io/refs/heads/main/openapi/span-rest-api-openapi.json
⚙
OpenAPI
https://github.com/spanio/SPAN-API-Client-Docs/blob/main/specs/r202615/openapi.json

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/span-io/refs/heads/main/json-schema/span-mdns-services-schema.json

Other Resources

🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/span-io/refs/heads/main/json-ld/span-context.jsonld
🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/span-io/refs/heads/main/capabilities/circuits.yaml
🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/span-io/refs/heads/main/capabilities/panel.yaml
🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/span-io/refs/heads/main/capabilities/storage.yaml
🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/span-io/refs/heads/main/capabilities/auth.yaml
🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/span-io/refs/heads/main/capabilities/wifi.yaml

OpenAPI Specification

span-rest-api-openapi.json Raw ↑ 
{
    "openapi": "3.0.2",
    "info": {
        "title": "Span",
        "description": "Span Panel REST API",
        "version": "v1"
    },
    "paths": {
        "/api/v1/auth/register": {
            "post": {
                "summary": "Generate Jwt",
                "operationId": "generate_jwt_api_v1_auth_register_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/AuthIn"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/AuthOut"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            }
        },
        "/api/v1/auth/clients": {
            "get": {
                "summary": "Get All Clients",
                "operationId": "get_all_clients_api_v1_auth_clients_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Clients"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            }
        },
        "/api/v1/auth/clients/{name}": {
            "get": {
                "summary": "Get Client",
                "operationId": "get_client_api_v1_auth_clients__name__get",
                "parameters": [
                    {
                        "required": true,
                        "schema": {
                            "title": "Name",
                            "type": "string"
                        },
                        "name": "name",
                        "in": "path"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Client"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            },
            "delete": {
                "summary": "Delete Client",
                "operationId": "delete_client_api_v1_auth_clients__name__delete",
                "parameters": [
                    {
                        "required": true,
                        "schema": {
                            "title": "Name",
                            "type": "string"
                        },
                        "name": "name",
                        "in": "path"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Client"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            }
        },
        "/api/v1/status": {
            "get": {
                "summary": "System Status",
                "operationId": "system_status_api_v1_status_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/StatusOut"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            }
        },
        "/api/v1/wifi/scan": {
            "get": {
                "summary": "Get Wifi Scan",
                "operationId": "get_wifi_scan_api_v1_wifi_scan_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WifiScanOut"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            }
        },
        "/api/v1/wifi/connect": {
            "post": {
                "summary": "Run Wifi Connect",
                "operationId": "run_wifi_connect_api_v1_wifi_connect_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/WifiConnectIn"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/WifiConnectOut"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            }
        },
        "/api/v1/panel": {
            "get": {
                "summary": "Get Panel State",
                "operationId": "get_panel_state_api_v1_panel_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PanelState"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            }
        },
        "/api/v1/islanding-state": {
            "get": {
                "summary": "Get Islanding State",
                "operationId": "get_islanding_state_api_v1_islanding_state_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/IslandingState"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            }
        },
        "/api/v1/panel/grid": {
            "get": {
                "summary": "Get Main Relay State",
                "operationId": "get_main_relay_state_api_v1_panel_grid_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/RelayStateOut"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            },
            "post": {
                "summary": "Set Main Relay State",
                "operationId": "set_main_relay_state_api_v1_panel_grid_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/RelayStateIn"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {}
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            }
        },
        "/api/v1/panel/power": {
            "get": {
                "summary": "Get Panel Power",
                "operationId": "get_panel_power_api_v1_panel_power_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PanelPower"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            }
        },
        "/api/v1/panel/meter": {
            "get": {
                "summary": "Get Panel Meter",
                "operationId": "get_panel_meter_api_v1_panel_meter_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/PanelMeter"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            }
        },
        "/api/v1/circuits": {
            "get": {
                "summary": "Get Circuits",
                "operationId": "get_circuits_api_v1_circuits_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/CircuitsOut"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            }
        },
        "/api/v1/circuits/{circuitId}": {
            "get": {
                "summary": "Get Circuit State",
                "operationId": "get_circuit_state_api_v1_circuits__circuitId__get",
                "parameters": [
                    {
                        "required": true,
                        "schema": {
                            "title": "Circuitid",
                            "type": "string"
                        },
                        "name": "circuitId",
                        "in": "path"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Circuit"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            },
            "post": {
                "summary": "Set Circuit State",
                "operationId": "set_circuit_state_api_v1_circuits__circuitId__post",
                "parameters": [
                    {
                        "required": true,
                        "schema": {
                            "title": "Circuitid",
                            "type": "string"
                        },
                        "name": "circuitId",
                        "in": "path"
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/Body_set_circuit_state_api_v1_circuits__circuitId__post"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Circuit"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            }
        },
        "/api/v1/spaces/{spaces_id}": {
            "get": {
                "summary": "Deprecated Spaces Endpoint Stub",
                "operationId": "deprecated_spaces_endpoint_stub_api_v1_spaces__spaces_id__get",
                "parameters": [
                    {
                        "required": true,
                        "schema": {
                            "title": "Spaces Id",
                            "type": "string"
                        },
                        "name": "spaces_id",
                        "in": "path"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {}
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            },
            "post": {
                "summary": "Deprecated Spaces Endpoint Stub",
                "operationId": "deprecated_spaces_endpoint_stub_api_v1_spaces__spaces_id__post",
                "parameters": [
                    {
                        "required": true,
                        "schema": {
                            "title": "Spaces Id",
                            "type": "string"
                        },
                        "name": "spaces_id",
                        "in": "path"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {}
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            }
        },
        "/api/v1/spaces": {
            "get": {
                "summary": "Deprecated Spaces Endpoint Stub",
                "operationId": "deprecated_spaces_endpoint_stub_api_v1_spaces_get",
                "parameters": [
                    {
                        "required": false,
                        "schema": {
                            "title": "Spaces Id",
                            "type": "string",
                            "default": ""
                        },
                        "name": "spaces_id",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {}
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            }
        },
        "/api/v1/panel/emergency-reconnect": {
            "post": {
                "summary": "Run Panel Emergency Reconnect",
                "operationId": "run_panel_emergency_reconnect_api_v1_panel_emergency_reconnect_post",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {}
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            }
        },
        "/api/v1/storage/soe": {
            "get": {
                "summary": "Get Storage Soe",
                "operationId": "get_storage_soe_api_v1_storage_soe_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BatteryStorage"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            },
            "post": {
                "summary": "Set Storage Soe",
                "operationId": "set_storage_soe_api_v1_storage_soe_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/BatteryStorage"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/BatteryStorage"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            }
        },
        "/api/v1/storage/nice-to-have-thresh": {
            "get": {
                "summary": "Get Storage Nice To Have Threshold",
                "operationId": "get_storage_nice_to_have_threshold_api_v1_storage_nice_to_have_thresh_get",
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/NiceToHaveThreshold"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            },
            "post": {
                "summary": "Set Storage Nice To Have Threshold",
                "operationId": "set_storage_nice_to_have_threshold_api_v1_storage_nice_to_have_thresh_post",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/NiceToHaveThreshold"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Successful Response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/NiceToHaveThreshold"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Validation Error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/HTTPValidationError"
                                }
                            }
                        }
                    }
                },
                "security": [
                    {
                        "HTTPBearer": []
                    }
                ]
            }
        }
    },
    "components": {
        "schemas": {
            "AllowedEndpointGroups": {
                "title": "AllowedEndpointGroups",
                "required": [
                    "delete",
                    "get",
                    "post",
                    "push"
                ],
                "type": "object",
                "properties": {
                    "delete": {
                        "title": "Delete",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "get": {
                        "title": "Get",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "post": {
                        "title": "Post",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "push": {
                        "title": "Push",
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                }
            },
            "AuthIn": {
                "title": "AuthIn",
                "required": [
                    "name"
                ],
                "type": "object",
                "properties": {
                    "name": {
                        "title": "Name",
                        "type": "string"
                    },
                    "description": {
                        "title": "Description",
                        "type": "string"
                    },
                    "otp": {
                        "title": "Otp",
                        "type": "string"
                    },
                    "dashboardPassword": {
                        "title": "Dashboardpassword",
                        "type": "string"
                    }
                }
            },
            "AuthOut": {
                "title": "AuthOut",
                "required": [
                    "accessToken",
                    "tokenType",
                    "iatMs"
                ],
                "type": "object",
                "properties": {
                    "accessToken": {
                        "title": "Accesstoken",
                        "type": "string"
                    },
                    "tokenType": {
                        "title": "Tokentype",
                        "type": "string"
                    },
                    "iatMs": {
                        "title": "Iatms",
                        "type": "integer"
                    }
                }
            },
            "BatteryStorage": {
                "title": "BatteryStorage",
                "required": [
                    "soe"
                ],
                "type": "object",
                "properties": {
                    "soe": {
                        "$ref": "#/components/schemas/StateOfEnergy"
                    }
                }
            },
            "Body_set_circuit_state_api_v1_circuits__circuitId__post": {
                "title": "Body_set_circuit_state_api_v1_circuits__circuitId__post",
                "type": "object",
                "properties": {
                    "relayStateIn": {
                        "$ref": "#/components/schemas/RelayStateIn"
                    },
                    "priorityIn": {
                        "$ref": "#/components/schemas/PriorityIn"
                    },
                    "circuitNameIn": {
                        "$ref": "#/components/schemas/CircuitNameIn"
                    },
                    "userControllableIn": {
                        "$ref": "#/components/schemas/BooleanIn"
                    },
                    "sheddableIn": {
                        "$ref": "#/components/schemas/BooleanIn"
                    },
        

# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/span-io/refs/heads/main/openapi/span-rest-api-openapi.json