Connectors: the descriptor and the four routes

ALYT integrations use a consistent contract: each connector is described to the client with a single integration descriptor and is responsible for handling a set of standardized API routes. This models each integration, or “connector,” as a service with an explicit set of capabilities, setup methods, and device classes, independent from the devices it controls. This page explains the structure of the descriptor, the discovery model, and which API routes every connector must implement.

Summary

A connector on ALYT is a programmable integration endpoint described by a canonical integration descriptor and required to answer four core API routes (and sometimes additional routes). Descriptors and routes define how the client discovers, connects, and manages integration connections in a fully declarative, updatable way. Local connectors can function if the hub and LAN are reachable when cloud services are down; cloud-native ones require provider/network access. Connection, management, and lifecycle routes are uniform across all integration kinds.

Integration Descriptor

Every connector is described through its integration descriptor. This provides a client-facing definition of the connector’s identity, capability, setup process, and device class. The descriptor fields are strictly defined and delivered via GET /integrations/catalogue. This catalogue is rendered dynamically by all clients, so new integrations can be shipped out-of-band.

Key fields include:

Field	Description
kind, name, icon, promise	Stable identity, short summary, and category icon.
connectivity	One of local, cloud, or cloud-then-local; shown as a badge.
brings	List of device categories it may add (e.g., "adds switches and lights").
connect.method	One of the closed set (discover, form, signIn, oauth, pair, external, nativeApp). If method requires input (form, etc.) the needed fields are described for the client.
discovery	Present if connector can actively search for things on the network.
disconnect.consequence	Pre-disconnect sentence, with placeholders for affected devices/rooms.
author, version, source, visibility	Who made the connector, its distribution source, and audience scope.
verification	proven if a real device was reached, with date; otherwise declared.
availability	available if connector is installed; coming if only descriptor exists.
limits	Provider/binding-specific rules, visible to users.
pairing	For radio join flows: has stepwise fielded guides per vendor/family.
logo	Service mark to display, standardized SVG or PNG for cards.
docsUrl	Guides for each connector: /connectors/<kind>, always machine-readable.

Clients render cards and connection screens using these fields and do not reference a connector by name in client code. Catalogue entries marked coming are not connectable.

The Four Core Routes of a Connector

Each connector operates as its own microservice behind the platform and must answer these standardized routes:

Route	Purpose and When It Is Called	Response
POST /{kind}/connect	Called for connect methods: form, signIn, pair, oauth. Validates given input, or triggers OAuth flow, returning connected, challenge (with form fields for e.g., code), redirect, or rejected.	{ status: ... }, with connect outcome, or challenge. Config and name as required.
POST /{kind}/discover	Active network discovery: called if descriptor declares a discovery verb. Returns endpoints/devices found, or updated config. For pairing integrations, also answers window status, pending devices, join window seconds, etc.	List of endpoints, join window, pending, and/or new config.
POST /{kind}/state	Poll current state for listed endpoints. Provided with config (e.g., stored credentials). Batch itemized response. Cloud-only connectors answer nothing if provider is unreachable.	State records for each endpoint; errors reported per item.
POST /{kind}/control	Invoked for actionable commands (e.g., on/off, setpoint). Provided with endpoint externalId and current config. Returns confirmation and/or resulting state.	State confirmation/result for the write.

Notes:

• A fifth route, POST /{kind}/webhook, may optionally be implemented to handle provider push callbacks. Platform will 404 for absent endpoints.
• For connectors that keep active sessions with devices (e.g., Tuya), state can be pushed to the platform instantly rather than polled.
• All secrets (API keys, OAuth tokens) are managed via the connector and are never returned to the client in any route.

Device Discovery/Lifecycle and Endpoint Management

• Discovery (POST /{kind}/discover) must never remove endpoints not present in a given scan. Device identities are always upserted by externalId; rediscovery never renames endpoints or removes rooms/assignments.
• Room assignment is performed initially at discovery based on provider information (roomName), else left unassigned. Subsequent room changes are managed by PATCHing the endpoint.
• Name normalization: speakers arrive as <brand> <name>, locks as <name> Lock. Rediscovery never renames after initial assignment.
• Endpoint removal, renaming, or room placement is handled by idempotent PATCH/DELETE at the /endpoints/:id resource.

Pairing and Vendor Guides

For connectors supporting pairing (e.g., Zigbee/Thread), the descriptor includes a pairing field with stepwise visual guides (intro, vendors, action forms, etc.). These are rendered by clients from API data and updated instantly across all clients when changed. Device addition via pairing is bounded by join window timings; explicit start/stop and discovery window management are described by the pairing data.

Scaffold for Developers

• Every connector must supply a public guide in /connectors/<kind>. This is linked in the UI as “Read the guide”.
• Each connector’s descriptor and docs are deployed to the developer portal and as JSON.
• Third-party/submitted connectors follow exactly the same descriptor and API rules, and can be live or sandboxed as appropriate for DEV/LIVE API key scopes.
• Household permissioning constrains actions: connect/discover/disconnect are configure (OWNER or staff); control is everyone in household. DEV credentials stay in developer sandbox; LIVE credentials act only on installed connector instance.

Cloud/Local Behavior

• Local integrations (e.g., Sonos, WiZ, Zigbee, Matter, local Tuya) continue to function while ALYT’s cloud is unavailable as long as the hub and LAN are reachable.
• Cloud-only connectors (e.g., Cync, SwitchBot, Ring, aromi.ai) require internet reachability for all routes.
• Cloud-then-local connectors (e.g., Tuya) require provider initial setup, but persist for local access afterwards.

API Route Reference (for Connector Implementers)

HTTP Verb + Path	Called By Platform For	Notes
POST /{kind}/connect	Connect and authenticate	Validates credentials, triggers OAuth, etc.
POST /{kind}/discover	Device/network discovery/pairing	Returns endpoints found, may persist to config, updates.
POST /{kind}/state	State polling	Returns per-endpoint state; cloud path errors handled per item.
POST /{kind}/control	Command dispatch	Receives externalId, config, processes command, returns confirmation and new state.
POST /{kind}/webhook	Optional: provider push callbacks	Only needed if vendor supports push; connector must verify signature and only parse after verifying authenticity.

For more details on the descriptor structure or how to build a connector, refer to the connector’s guide at /connectors/<kind> or the machine-readable catalogue endpoint /integrations/catalogue.

Govee connectors use the existing Add a connector flow in the partner portal and the household Add device path, with discovery limited to Look for devices and device-reported state. Source-listed capability data does not grant permission by itself, and rediscovery should preserve room assignment.