SPAN

aid: span-io
name: SPAN
description: >-
  SPAN is a San Francisco-based home energy technology company building smart
  electrical panels that replace traditional residential breaker boxes with a
  software-defined, controllable, and metered panel. SPAN Panel provides
  whole-home real-time power and energy metering, per-circuit monitoring and
  remote relay control, grid/islanding state management for whole-home backup
  with solar and energy storage, EV charging coordination via SPAN Drive, and
  a mobile app for energy management. As of the SPAN Panel firmware r202603
  release (Q1 2026), SPAN exposes a public-beta on-premise SPAN API for
  software integrations between SPAN Panel and other devices on the home Local
  Area Network. The SPAN API is a real, documented HTTP + MQTT/Homie surface
  that runs directly on the panel — there is no cloud-hosted developer
  endpoint. The REST surface provides authentication, system status, Wi-Fi
  setup, panel state, per-circuit control, panel grid relay, energy storage
  state-of-energy, and emergency reconnect operations. The publish/subscribe
  surface uses the Electrification Bus (eBus) framework and Homie Convention
  over MQTT for streaming real-time panel state, per-circuit telemetry, and
  control of relays. SPAN API is licensed for personal, non-commercial use
  under MIT-0 for docs and example code; commercial / fleet use requires the
  separately licensed SPAN Fleet Manager.
type: Provider
position: Provider
access: 3rd-Party
image: https://kinlane-productions.s3.amazonaws.com/apis-json/apis-json-logo.jpg
tags:
  - Energy
  - Home Energy
  - Electrification
  - Smart Panel
  - Electrical Panel
  - Home Automation
  - Solar
  - Energy Storage
  - EV Charging
  - Grid
  - Islanding
  - Backup Power
  - Demand Response
  - IoT
  - MQTT
  - Homie
  - Electrification Bus
  - On-Premise
url: https://raw.githubusercontent.com/api-evangelist/span-io/refs/heads/main/apis.yml
created: '2026-05-25'
modified: '2026-05-25'
specificationVersion: '0.20'
apis:
  - aid: span-io:span-rest-api
    name: SPAN REST API
    description: >-
      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.
    humanURL: https://github.com/spanio/SPAN-API-Client-Docs
    baseURL: http://span-{serial-number}.local/api/v1
    tags:
      - Energy
      - Home Energy
      - Smart Panel
      - REST
      - On-Premise
      - Circuits
      - Energy Storage
      - Grid
      - Islanding
    properties:
      - url: https://github.com/spanio/SPAN-API-Client-Docs
        type: Documentation
      - url: https://github.com/spanio/SPAN-API-Client-Docs/blob/main/README.md
        type: Documentation
      - url: openapi/span-rest-api-openapi.json
        type: OpenAPI
      - url: https://github.com/spanio/SPAN-API-Client-Docs/blob/main/specs/r202615/openapi.json
        type: OpenAPI
      - url: json-schema/span-mdns-services-schema.json
        type: JSONSchema
      - url: json-ld/span-context.jsonld
        type: JSONLD
      - url: capabilities/circuits.yaml
        type: NaftikoCapability
      - url: capabilities/panel.yaml
        type: NaftikoCapability
      - url: capabilities/storage.yaml
        type: NaftikoCapability
      - url: capabilities/auth.yaml
        type: NaftikoCapability
      - url: capabilities/wifi.yaml
        type: NaftikoCapability
  - aid: span-io:span-ebus-mqtt-api
    name: SPAN eBus MQTT API
    description: >-
      Publish/subscribe streaming API hosted on SPAN Panel using the
      Electrification Bus (eBus) integration framework and the Homie
      Convention. SPAN Panel hosts an MQTT broker accessible over MQTTS
      (8883), WS, and WSS. Clients subscribe to `ebus/5/<serial>/...` topics
      to receive real-time panel state, per-circuit telemetry, energy storage
      state, and SPAN Drive integration data, and publish to `/set` topics to
      operate relays and control panel state. The broker enforces topic-level
      ACLs — full read access on `ebus/#`, write access limited to Homie
      `/set` control topics and to non-panel device subtrees under `ebus/5/`.
      Credentials are obtained via the REST authentication endpoint.
    humanURL: https://github.com/spanio/SPAN-API-Client-Docs#span-api-interaction-models
    tags:
      - MQTT
      - Homie
      - Electrification Bus
      - eBus
      - Pub/Sub
      - Streaming
      - On-Premise
      - Energy
    properties:
      - url: https://github.com/spanio/SPAN-API-Client-Docs#publishsubscribe
        type: Documentation
      - url: https://homieiot.github.io/specification/
        type: Documentation
      - url: https://ebus.energy/
        type: Documentation
      - url: asyncapi/span-ebus-asyncapi.yml
        type: AsyncAPI
      - url: json-schema/span-homie-schema.json
        type: JSONSchema
      - url: capabilities/ebus-telemetry.yaml
        type: NaftikoCapability
common:
  - type: Website
    url: https://www.span.io
  - type: Portal
    url: https://www.span.io
  - type: Documentation
    url: https://github.com/spanio/SPAN-API-Client-Docs
  - type: Documentation
    url: https://opensource.span.io/span-panel/
  - type: Product
    url: https://www.span.io/smart-panel-product
  - type: Product
    url: https://www.span.io/products/main-32
  - type: Product
    url: https://www.span.io/drive
  - type: Product
    url: https://www.span.io/app
  - type: Product
    url: https://www.span.io/utilities
  - type: Blog
    url: https://www.span.io/blog
  - type: AnnouncementPost
    url: https://www.span.io/blog/introducing-span-api-and-span-home-on-premise-public-beta
    name: Introducing SPAN API and SPAN Home On-premise (Public Beta)
  - type: Support
    url: https://support.span.io/hc/en-us
  - type: TermsOfService
    url: https://www.span.io/terms-of-service
  - type: PrivacyPolicy
    url: https://www.span.io/privacy-policy
  - type: GitHubOrganization
    url: https://github.com/spanio
  - type: Repository
    url: https://github.com/spanio/SPAN-API-Client-Docs
    name: SPAN API Client Documentation
  - type: Forum
    url: https://github.com/spanio/SPAN-API-Client-Docs/discussions
    name: SPAN API GitHub Discussions
  - type: Issues
    url: https://github.com/spanio/SPAN-API-Client-Docs/issues
  - type: ChangeLog
    url: https://github.com/spanio/SPAN-API-Client-Docs/blob/main/CHANGELOG.md
  - type: License
    url: https://github.com/spanio/SPAN-API-Client-Docs/blob/main/LICENSE
    name: MIT-0 (Docs and example code)
  - type: SDK
    url: https://github.com/SpanPanel/span-panel-api
    name: span-panel-api (Python, community)
  - type: SDK
    url: https://github.com/SpanPanel/Span
    name: Home Assistant Integration (community)
  - type: SDK
    url: https://github.com/SpanPanel/simulator
    name: SPAN Panel eBus Simulator (community)
  - type: Tool
    url: https://github.com/spanio/SPAN-API-Client-Docs/tree/main/scripts
    name: SPAN reference scripts (span-discover, span-auth, span-curl, span-mqtt-pub, span-mqtt-sub, span-mdns-query)
  - type: Twitter
    url: https://twitter.com/span_io
  - type: LinkedIn
    url: https://www.linkedin.com/company/span-io
  - type: YouTube
    url: https://www.youtube.com/@span_io
  - type: Careers
    url: https://www.span.io/careers
  - type: Contact
    url: https://www.span.io/contact
  - type: Plans
    url: plans/span-io-plans-pricing.yml
  - type: RateLimits
    url: rate-limits/span-io-rate-limits.yml
  - type: FinOps
    url: finops/span-io-finops.yml
  - type: Features
    data:
      - SPAN Panel — software-defined smart electrical panel replacing traditional residential breaker boxes
      - Whole-home and per-circuit real-time power and energy metering
      - Per-circuit remote relay control with named circuits and priority groups
      - Grid / islanding state management for whole-home backup with solar and energy storage
      - SPAN Drive — integrated Level 2 EV charging coordinated with the panel
      - SPAN Home mobile and on-premise apps for energy management and monitoring
      - On-premise SPAN API hosted on the panel — REST + MQTT, LAN-only, no cloud
      - HTTP Bearer JWT authentication minted by the panel and bound to a named API client
      - REST resources for circuits, panel state, panel grid relay, panel meter and power, islanding state, energy storage SoE and nice-to-have thresholds, Wi-Fi scan/connect, system status, emergency reconnect
      - MQTT pub/sub via the Electrification Bus (eBus) framework using the Homie Convention
      - mDNS-advertised local discovery (`_span._tcp`, `_span-api._tcp`, `_mqtt._tcp`) for zero-config integration
      - JSON Schema for Homie device descriptions and mDNS service records
      - Reference shell + Python scripts (span-discover, span-auth, span-curl, span-mqtt-sub, span-mdns-query)
      - Public beta — initial firmware r202603 for SPAN Panel MAIN 32, rolling out to MAIN 16 / MLO 24 / MAIN 40 / MLO 48 in H2 2026
      - Commercial / fleet integrations served separately via SPAN Fleet Manager licensing
      - SPAN Utilities — distributed energy resource (DER) management platform for utility partners
    sources:
      - https://www.span.io/blog/introducing-span-api-and-span-home-on-premise-public-beta
      - https://github.com/spanio/SPAN-API-Client-Docs
      - https://www.span.io/smart-panel-product
      - https://opensource.span.io/span-panel/
    updated: '2026-05-25'
maintainers:
  - FN: Kin Lane
    email: [email protected]