Changelog
Changelog
1.0.0
The 1key API v1: sites, hubs (added to sites by Serial, with connection, firmware and network), members and invitations, live device reads, commands with idempotency keys, your organization's event log of every hub's events, kept 30 days and read by cursor or Server-Sent Events (or one hub's), the device registry: product details, manuals and pairing steps for every device, and the organization, its API keys and their usage. Lists filter, expand reads related objects in one call, and every object has created_at and updated_at.
SmartStart: /hubs/{hub_id}/setup-codes puts devices' QR codes on a hub's list, each with the name and room it takes when it joins. Codes for a hub that is offline, or has never connected, are held and sent when it connects. Events setup_code.added, setup_code.removed, setup_code.joined, setup_code.dropped and setup_code.unknown_request; device.added carries setup_code_id.
Device setup: devices carry setup and needs_setup; GET /hubs/{hub_id}/devices/{device_id}/setup lists the hub's checks, and POST …/setup/{action} pings, identifies, repairs, tests, and marks setup complete once every required check passes. Events device.setup_completed, device.setup_reopened, device.setup_test_step and device.setup_tested.
POST /hubs/{hub_id}/devices/{device_id}/replace puts a new device in a failed one's place, with its name and room; POST /hubs/{hub_id}/devices/reset starts a hub's device network over.
Settings: GET /hubs/{hub_id}/devices/{device_id}/settings and PATCH …/settings/{setting_id}. Access: lock users with PINs and cards and weekly schedules the hub enforces, at /hubs/{hub_id}/devices/{device_id}/users. Events user.created, user.updated, user.deleted, credential.created, credential.applied, credential.revoked, credential.used, credential.rejected, credential.diverged and credential.replaced.
Sites take a time_zone and a location: their hubs run schedules and local-time conditions in that time zone, and know sunrise and sunset from the location.
Devices carry room, security (how securely it joined), pin, fingerprint, firmware and product.
Channels: every channel key has one type and unit whatever the device's protocol, following Matter's names and polarity (brightness 0–100 %, shades % closed, contact true when closed, °C, named modes and alarm states). Commands are validated against them; GET /v1/channel-types and the channel reference publish them. A channel describes itself with schema, category, label, observable and stateful. Channel types cover locks and their credentials (with schema.slots), switches, dimmers, shades, garage doors, valves, thermostats (with operating_state and fan_state), colour (color, color_temperature, color_components), environment and air-quality sensors, energy, gas and water meters, buttons and alarms. POST /hubs/{hub_id}/pairing takes security: "legacy" for a lock that can't join with S2, or "without_code" for a device with no setup code; a device added with only its PIN or none confirms its code after joining, with network.setup_code_requested and POST /hubs/{hub_id}/pairing/confirm.
Commands: a command sets a channel, or with action move (and a direction) or stop moves and stops a level, shade or fan; transition sets how long it takes. Several commands to one device go as one batch under commands, each checked before any is sent. A command without endpoint goes to the device's one channel with that key. for puts the channel back after a time, a lock locked and a garage door closed; a lock or garage door that doesn't confirm it, or an automation's relock or a schedule's lock or close, is a device.not_secured event. Each put-back's steps are events put_back.armed, put_back.commanded, put_back.attempted and put_back.ended, and channel.observed carries the cause of the change.
Automations: /hubs/{hub_id}/automations keeps automations the hub runs, offline too: triggers, conditions and steps, checked by the API and by the hub for loops and conflicts, with revisions, tests, runs and traces. /hubs/{hub_id}/schedules holds a device in a state period by period, or runs a thermostat's week. Remote triggers fire at one hub (/hubs/{hub_id}/triggers/{name}) or across hubs and sites (/triggers/{name}). /automation-templates saves an automation once with parameters and deploys it to many hubs, queued for a hub that is offline. /calendars gives every hub of the organization dates for time triggers and calendar conditions. Anything that unlocks or opens needs automations:unlock and is saved with an unlocks warning. Scopes automations:read, automations:write, automations:run and automations:unlock. Events automation.created, automation.updated, automation.deleted, automation.suspended, automation.loop_blocked, automation.run_finished, automation.emitted, automation.unlocked, schedule.updated, schedule.deleted, schedule.applied, calendar.updated, calendar.deleted and site.time_zone_set.
Intercoms: /intercoms adds 1Key Intercoms to sites by Serial, reads their connection, firmware, network, building enrollment, door and uptime (GET /intercoms/{intercom_id}/uptime), and their building's directory and masked codes as 1Valet has them (/directory, /codes), moves, renames and removes them, and resets their cloud link. POST /intercoms/{intercom_id}/door/unlock opens the door, with an expiry and idempotency keys. Their events are in the organization's log and at GET /intercoms/{intercom_id}/events: door.unlocked, door.state, access.denied, call.started, call.answered, call.ended, intercom.booted and intercom.power, and the hubs' connection and alarm events. Signals intercom.created, intercom.updated and intercom.deleted. Intercoms have their own scopes: intercoms:read, intercoms:write and intercoms:command. An intercom is added with management 1valet (the building's 1Valet account manages it) or 1key: then /intercoms/{intercom_id}/entries, /credentials and /settings keep its directory, codes, cards, faces (learned from photos, with the person's consent; only the embeddings are kept) and door settings, and /enrollment-code gives the code it enrolls with at the door.