Adapter Protocol
The ZenEdge Adapter Protocol is the specification for building device integrations with SpaceOS. Any IoT device that implements this protocol can be managed by SpaceOS.
Philosophy
- One adapter = one device — Each adapter instance manages exactly one physical device
- HTTP-based — Simple REST endpoints, no custom transport protocols
- Self-describing — Adapters declare their capabilities via
/capabilities - Health-monitored — ZenEdge continuously polls
/pingfor health status - Embeddable UI — Adapters can serve HTML tiles for guest-facing interfaces
The 7 Endpoints
Every adapter must implement these endpoints:
| Endpoint | Level | Method | Purpose |
|---|---|---|---|
/ping | Adapter | GET | Health check — "is the adapter alive?" |
/capabilities | Adapter | GET | Declare supported devices, types, and actions |
/status | Device | GET | Current device state (locked/unlocked, online/offline) |
/action | Device | POST | Execute a command (unlock, generate_voucher, etc.) |
/ui | Device | GET | HTML embed for the guest-facing tile |
/webhook/register | Device | POST | Register for push events from the adapter |
/webhook/<event> | Device | POST | Receive push events from the device |
info
Device-level endpoints require a device_id query parameter: ?device_id=ada-xxx
Adapter-level endpoints (/ping, /capabilities) do not.
Authentication
All adapter endpoints are authenticated via API key:
x-api-key: adapter-secret-key
Protocol Versions
| Version | Status | Key Changes |
|---|---|---|
| v2.0 | Current | device_id routing via query parameter |
| v1.0 | Deprecated | Device ID in path |
Next Steps
- Contract Specification — Detailed endpoint schemas
- Tutorial: Build Your First Adapter — 30-minute walkthrough
- Capability Discovery — How adapters declare features