1KEY Developers
API reference

Automations

Base URL https://api.1keyplatform.dev/v1. Every endpoint below is generated from the OpenAPI contract, which you can download as openapi.yaml.

Log in to send these requests to your organization from this page.

Automations

Automations, schedules and remote triggers the hub keeps and runs, offline too.

DELETE /calendars/{key}

Delete a calendar

Needs the automations:write scope.

Parameters

Name In Type Description
key required path string

Responses

204 Deleted.

Errors

404 not_found No such resource, or it is not your organization's.
GET /calendars/{key}

One calendar

Needs the automations:read scope.

Parameters

Name In Type Description
key required path string

Responses

200 The calendar.

Errors

404 not_found No such resource, or it is not your organization's.
PUT /calendars/{key}

Create or replace a calendar

Needs the automations:write scope.

Given to every hub of the organization, for automations and schedules that refer to it.

Parameters

Name In Type Description
key required path string

Body

dates array of string · required
name string, up to 100 characters · required

Responses

200 Saved.

Errors

400 invalid_request The request is malformed or a field is invalid.
DELETE /hubs/{hub_id}/schedules/{schedule_key}

Delete a schedule

Needs the automations:write scope.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
schedule_key required path string

Responses

204 Deleted.
PUT /hubs/{hub_id}/schedules/{schedule_key}

Create or replace a schedule

Needs the automations:write scope.

A schedule that unlocks a lock or opens a garage door needs allow_unlock and automations:unlock, keeps it locked or closed by default, and is saved with an unlocks warning in problems.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
schedule_key required path string

Body

default object · required The values out of every period; a lock locked, a garage door closed.
device_id integer · required
name string, up to 100 characters · required
periods array of object · required
type "channel_state" | "setpoint_program" · required channel_state sets one channel key; setpoint_program sets heating_setpoint, cooling_setpoint, mode and fan_mode.
allow_unlock boolean · optional Must be true for a schedule that unlocks or opens a device; the API key needs automations:unlock.
enabled boolean, default true · optional
endpoint integer, 0–255 · optional Absent: the device's one endpoint with each key.
key string · optional From the path.

Responses

200 Saved, with any warnings.

Errors

400 invalid_request The request is malformed or a field is invalid.
403 insufficient_scope The key lacks the scope this operation needs.
422 automation_rejected: the hub refused it; error.problems lists why.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
GET /automation-templates/{key}

A template (latest, or `?version=`)

Needs the automations:read scope.

Parameters

Name In Type Description
key required path string
version optional query integer, at least 1 A version of the template; absent, the latest.

Responses

200 The template.

Errors

404 not_found No such resource, or it is not your organization's.
PUT /automation-templates/{key}

Save a template's next version

Needs the automations:write scope.

Parameters

Name In Type Description
key required path string

Body

automation Automation · required
name string · required
parameters object · optional

Responses

200 Saved as the next version.

Errors

400 invalid_request The request is malformed or a field is invalid.
POST /automation-templates/{key}/deployments

Deploy a template to hubs

Needs the automations:write scope.

Parameters

Name In Type Description
key required path string

Body

targets array of object · required
version integer · optional Absent

Responses

201 The deployment, with each target's status. · returns a Deployment

Errors

400 invalid_request The request is malformed or a field is invalid.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
GET /automation-templates

Each template's latest version

Needs the automations:read scope.

Responses

200 The templates.
GET /calendars

The organization's calendars

Needs the automations:read scope.

Responses

200 The calendars.
POST /hubs/{hub_id}/triggers/{name}

Fire a hub's remote triggers

Needs the automations:run scope.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
name required path string

Body

data object · optional The run sees it as trigger.data.

Responses

202 The automations it started.

Errors

503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
GET /hubs/{hub_id}/automations/{key}/traces

An automation's last runs

Needs the automations:read scope.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
key required path string
run_id optional query string Only this run.

Responses

200 Its last 20 runs, newest first.
DELETE /hubs/{hub_id}/automations/{key}

Delete an automation

Needs the automations:write scope.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
key required path string

Responses

204 Deleted.

Errors

404 not_found No such resource, or it is not your organization's.
GET /hubs/{hub_id}/automations/{key}

One automation

Needs the automations:read scope.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
key required path string

Responses

200 The automation. · returns a Automation

Errors

404 not_found No such resource, or it is not your organization's.
PUT /hubs/{hub_id}/automations/{key}

Create or replace an automation

Needs the automations:write scope.

Checked strictly by the API, then by the hub against its devices and its other automations. Anything that unlocks or opens needs allow_unlock and the automations:unlock scope. A revision in the body saves only if it's the one the hub holds.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
key required path string

Body

actions array of AutomationAction · required
name string, up to 100 characters · required
triggers array of AutomationTrigger · required
allow_unlock boolean, default false · optional Must be true for an automation that unlocks or opens a device, or resumes a credential.
conditions array of AutomationCondition · optional
cooldown_s integer, 0–86400, default 0 · optional
digest string · optional SHA-256 of the document in canonical JSON, without revision and digest.
enabled boolean, default true · optional
key string · optional From the path.
max_runs integer, 1–10 · optional Runs queued or under way at once; default 1, or 10 for queued and parallel.
mode "single" | "restart" | "queued" | "parallel" · optional
revision integer, at least 0 · optional Held by the hub. Sent, the save goes through only if it's the one the hub holds; 0 for one that must be new.
suspended boolean · optional The hub switched it off after repeated loops.
template string, up to 64 characters · optional The template it was deployed from: <key>@<version>.
variables object · optional

Responses

200 Saved, with any warnings.

Errors

400 invalid_request The request is malformed or a field is invalid.
403 insufficient_scope The key lacks the scope this operation needs.
409 conflict: revision isn't the one the hub holds; the message names it.
422 automation_rejected: the hub refused it; error.problems lists why.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
GET /deployments/{id}

A deployment and each target's status

Needs the automations:read scope.

Parameters

Name In Type Description
id required path string

Responses

200 The deployment. · returns a Deployment

Errors

404 not_found No such resource, or it is not your organization's.
GET /hubs/{hub_id}/automations

The hub's automations

Needs the automations:read scope.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Responses

200 Each in brief.

Errors

503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
POST /hubs/{hub_id}/automations/validate

Check an automation without saving it

Needs the automations:write scope.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Body

actions array of AutomationAction · required
name string, up to 100 characters · required
triggers array of AutomationTrigger · required
allow_unlock boolean, default false · optional Must be true for an automation that unlocks or opens a device, or resumes a credential.
conditions array of AutomationCondition · optional
cooldown_s integer, 0–86400, default 0 · optional
digest string · optional SHA-256 of the document in canonical JSON, without revision and digest.
enabled boolean, default true · optional
key string · optional From the path.
max_runs integer, 1–10 · optional Runs queued or under way at once; default 1, or 10 for queued and parallel.
mode "single" | "restart" | "queued" | "parallel" · optional
revision integer, at least 0 · optional Held by the hub. Sent, the save goes through only if it's the one the hub holds; 0 for one that must be new.
suspended boolean · optional The hub switched it off after repeated loops.
template string, up to 64 characters · optional The template it was deployed from: <key>@<version>.
variables object · optional

Responses

200 The hub's problems, if any.

Errors

400 invalid_request The request is malformed or a field is invalid.
GET /hubs/{hub_id}/schedules

The hub's schedules

Needs the automations:read scope.

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).

Responses

200 The schedules.
POST /hubs/{hub_id}/automations/{key}/{action}

Enable, disable, test or run an automation

Needs the automations:write automations:run scopes.

Action Body
enable, disable none Switches it on (lifting a suspension) or off; answers it in brief (AutomationBrief). Needs automations:write
test {trigger?} Runs against live state, sending nothing to devices: delays pass and a wait_for times out. trigger is what the run sees as its trigger (default {"type": "test"}); an unlock or open is refused: untrusted_trigger unless it is remote or access granted. Answers {trace: {run_id, result, steps}}. Needs automations:run
runs {variables?} Runs it now, its conditions included; 202 with its run_id. Needs automations:run. Its trigger is manual, which is not trusted: its unlocks and opens are refused: untrusted_trigger and a credential resume refused: manual_run, in it and in any automation it runs

Parameters

Name In Type Description
hub_id required path string The hub ID printed on the hub (lowercase).
key required path string
action required path "enable" | "disable" | "test" | "runs"

Responses

200 Done.
202 Started.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
503 hub_offline hub_offline: the hub is not connected. hub_unavailable: it is connected but cannot do it now, for example its radio is down or it does not know the time yet.
POST /triggers/{name}

Fire a remote trigger across hubs and sites

Needs the automations:run scope.

Parameters

Name In Type Description
name required path string

Body

data object · optional
hub_ids array of string · optional
site_ids array of string · optional

Responses

202 Each hub's result; an offline hub is reported, not queued.

Errors

400 invalid_request The request is malformed or a field is invalid.