{"openapi":"3.1.0","info":{"title":"Roots API","version":"2026-10-18","description":"The farm and ranch platform: animals, herds and flocks, paddocks, trackers, Roost houses, alerts, tasks and webhooks.","contact":{"url":"https://docs.roots.sh"}},"servers":[{"url":"https://api.roots.sh"}],"security":[{"key":[]}],"components":{"securitySchemes":{"key":{"type":"http","scheme":"bearer","description":"rk_live_… or rk_test_… from https://my.roots.sh/keys"},"device":{"type":"http","scheme":"bearer","description":"rd_… device key"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Farm":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"mode":{"enum":["live","test"]},"timezone":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"},"acres":{"type":"number"},"sample":{"type":"boolean"},"settings":{"type":"object"},"created_at":{"type":"string","format":"date-time"}}},"Alert":{"type":"object","properties":{"id":{"type":"string"},"farm_id":{"type":"string"},"severity":{"enum":["urgent","watch","info"]},"title":{"type":"string"},"reason":{"type":"string"},"rule":{"type":"string"},"subject_type":{"type":"string"},"subject_id":{"type":"string"},"status":{"enum":["open","acknowledged","resolved"]},"created_at":{"type":"string","format":"date-time"},"resolved_at":{"type":"string","format":"date-time"}}},"Command":{"type":"object","properties":{"id":{"type":"string"},"device_id":{"type":"string"},"command":{"type":"string"},"params":{"type":"object"},"status":{"enum":["queued","delivered","done","failed"]},"result":{"type":"object"},"created_at":{"type":"string","format":"date-time"},"done_at":{"type":"string","format":"date-time"}}},"Reading":{"type":"object","properties":{"metric":{"type":"string"},"value":{"type":"number"},"unit":{"type":"string"},"at":{"type":"string","format":"date-time"}}},"Brief":{"type":"object","properties":{"headline":{"type":"string"},"text":{"type":"string"},"alerts":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}},"tasks":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"roosts":{"type":"array","items":{"type":"object"}}}},"Key":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"mode":{"enum":["live","test"]},"prefix":{"type":"string"},"key":{"type":"string","description":"Shown once, on create."},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":"string","format":"date-time"}}},"Animal":{"type":"object","properties":{"id":{"type":"string"},"farm_id":{"type":"string"},"species":{"type":"string"},"name":{"type":"string"},"tag":{"type":"string"},"eid":{"type":"string"},"sex":{"type":"string"},"breed":{"type":"string"},"birth_date":{"type":"string","format":"date-time"},"group_id":{"type":"string"},"paddock_id":{"type":"string"},"status":{"type":"string"},"notes":{"type":"string"},"fields":{"type":"object"},"created_at":{"type":"string","format":"date-time"}}},"Group":{"type":"object","properties":{"id":{"type":"string"},"farm_id":{"type":"string"},"name":{"type":"string"},"species":{"type":"string"},"kind":{"type":"string"},"head_count":{"type":"number"},"hatch_date":{"type":"string","format":"date-time"},"paddock_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"Paddock":{"type":"object","properties":{"id":{"type":"string"},"farm_id":{"type":"string"},"name":{"type":"string"},"acres":{"type":"number"},"geometry":{"type":"object"},"rest_days_target":{"type":"number"},"last_grazed_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"Device":{"type":"object","properties":{"id":{"type":"string"},"farm_id":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"serial":{"type":"string"},"animal_id":{"type":"string"},"group_id":{"type":"string"},"firmware":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"},"battery":{"type":"number"},"state":{"type":"object"},"last_seen_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"Task":{"type":"object","properties":{"id":{"type":"string"},"farm_id":{"type":"string"},"title":{"type":"string"},"notes":{"type":"string"},"due_at":{"type":"string","format":"date-time"},"assignee":{"type":"string"},"status":{"type":"string"},"subject_id":{"type":"string"},"alert_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"Event":{"type":"object","properties":{"id":{"type":"string"},"farm_id":{"type":"string"},"type":{"type":"string"},"subject_type":{"type":"string"},"subject_id":{"type":"string"},"data":{"type":"object"},"at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"farm_id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"}}}}},"paths":{"/v1/farms":{"get":{"tags":["Farms"],"summary":"List farms","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Farm"}}}}}}}}},"post":{"tags":["Farms"],"summary":"Create a farm","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"timezone":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"},"acres":{"type":"number"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Farm"}}}}}}},"/v1/farms/{farm}":{"parameters":[{"name":"farm","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Farms"],"summary":"Get a farm","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Farm"}}}}}},"patch":{"tags":["Farms"],"summary":"Update a farm (settings.rules overrides alert thresholds)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Farm"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Farm"}}}}}},"delete":{"tags":["Farms"],"summary":"Delete a farm","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/farms/{farm}/brief":{"parameters":[{"name":"farm","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Farms"],"summary":"Morning brief: what needs you, ranked","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brief"}}}}}}},"/v1/farms/{farm}/alerts":{"parameters":[{"name":"farm","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Alerts"],"summary":"List alerts","parameters":[{"name":"status","in":"query","schema":{"enum":["active","open","acknowledged","resolved","all"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}}}}}}}}}},"/v1/alerts/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Alerts"],"summary":"Get an alert","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Alert"}}}}}}},"/v1/alerts/{id}/acknowledge":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Alerts"],"summary":"Acknowledge an alert","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Alert"}}}}}}},"/v1/alerts/{id}/resolve":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Alerts"],"summary":"Resolve an alert","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Alert"}}}}}}},"/v1/farms/{farm}/roosts":{"parameters":[{"name":"farm","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Roost"],"summary":"Every Roost with its latest readings and recent commands","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/roosts/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Roost"],"summary":"One Roost","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/farms/{farm}/animals":{"parameters":[{"name":"farm","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Animals"],"summary":"List animals","parameters":[{"name":"species","in":"query","schema":{"type":"string"}},{"name":"group_id","in":"query","schema":{"type":"string"}},{"name":"paddock_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"eid","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string"}},{"name":"before","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Animal"}}}}}}}}},"post":{"tags":["Animals"],"summary":"Create an animal","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["species"],"properties":{"species":{"type":"string"},"name":{"type":"string"},"tag":{"type":"string"},"eid":{"type":"string"},"sex":{"type":"string"},"breed":{"type":"string"},"birth_date":{"type":"string","format":"date-time"},"group_id":{"type":"string"},"paddock_id":{"type":"string"},"status":{"type":"string"},"notes":{"type":"string"},"fields":{"type":"object"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Animal"}}}}}}},"/v1/animals/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Animals"],"summary":"Get an animal","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Animal"}}}}}},"patch":{"tags":["Animals"],"summary":"Update an animal","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"species":{"type":"string"},"name":{"type":"string"},"tag":{"type":"string"},"eid":{"type":"string"},"sex":{"type":"string"},"breed":{"type":"string"},"birth_date":{"type":"string","format":"date-time"},"group_id":{"type":"string"},"paddock_id":{"type":"string"},"status":{"type":"string"},"notes":{"type":"string"},"fields":{"type":"object"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Animal"}}}}}},"delete":{"tags":["Animals"],"summary":"Delete an animal","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/farms/{farm}/groups":{"parameters":[{"name":"farm","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Groups"],"summary":"List groups","parameters":[{"name":"species","in":"query","schema":{"type":"string"}},{"name":"kind","in":"query","schema":{"type":"string"}},{"name":"paddock_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string"}},{"name":"before","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Group"}}}}}}}}},"post":{"tags":["Groups"],"summary":"Create a group","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","species"],"properties":{"name":{"type":"string"},"species":{"type":"string"},"kind":{"type":"string"},"head_count":{"type":"number"},"hatch_date":{"type":"string","format":"date-time"},"paddock_id":{"type":"string"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}}}}}},"/v1/groups/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Groups"],"summary":"Get a group","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}}}}},"patch":{"tags":["Groups"],"summary":"Update a group","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"name":{"type":"string"},"species":{"type":"string"},"kind":{"type":"string"},"head_count":{"type":"number"},"hatch_date":{"type":"string","format":"date-time"},"paddock_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}}}}},"delete":{"tags":["Groups"],"summary":"Delete a group","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/farms/{farm}/paddocks":{"parameters":[{"name":"farm","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Paddocks"],"summary":"List paddocks","parameters":[{"name":"limit","in":"query","schema":{"type":"string"}},{"name":"before","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Paddock"}}}}}}}}},"post":{"tags":["Paddocks"],"summary":"Create a paddock","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"acres":{"type":"number"},"geometry":{"type":"object"},"rest_days_target":{"type":"number"},"last_grazed_at":{"type":"string","format":"date-time"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Paddock"}}}}}}},"/v1/paddocks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Paddocks"],"summary":"Get a paddock","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Paddock"}}}}}},"patch":{"tags":["Paddocks"],"summary":"Update a paddock","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"name":{"type":"string"},"acres":{"type":"number"},"geometry":{"type":"object"},"rest_days_target":{"type":"number"},"last_grazed_at":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Paddock"}}}}}},"delete":{"tags":["Paddocks"],"summary":"Delete a paddock","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/farms/{farm}/devices":{"parameters":[{"name":"farm","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Devices"],"summary":"List devices","parameters":[{"name":"type","in":"query","schema":{"type":"string"}},{"name":"animal_id","in":"query","schema":{"type":"string"}},{"name":"group_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string"}},{"name":"before","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Device"}}}}}}}}},"post":{"tags":["Devices"],"summary":"Create a device (returns device_key once)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","name"],"properties":{"type":{"type":"string"},"name":{"type":"string"},"serial":{"type":"string"},"animal_id":{"type":"string"},"group_id":{"type":"string"},"firmware":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Device"}}}}}}},"/v1/devices/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Devices"],"summary":"Get a device","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Device"}}}}}},"patch":{"tags":["Devices"],"summary":"Update a device","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"type":{"type":"string"},"name":{"type":"string"},"serial":{"type":"string"},"animal_id":{"type":"string"},"group_id":{"type":"string"},"firmware":{"type":"string"},"lat":{"type":"number"},"lon":{"type":"number"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Device"}}}}}},"delete":{"tags":["Devices"],"summary":"Delete a device","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/farms/{farm}/tasks":{"parameters":[{"name":"farm","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Tasks"],"summary":"List tasks","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"assignee","in":"query","schema":{"type":"string"}},{"name":"subject_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string"}},{"name":"before","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}}}}}}}}},"post":{"tags":["Tasks"],"summary":"Create a task","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"notes":{"type":"string"},"due_at":{"type":"string","format":"date-time"},"assignee":{"type":"string"},"status":{"type":"string"},"subject_id":{"type":"string"},"alert_id":{"type":"string"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}}}}},"/v1/tasks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Tasks"],"summary":"Get a task","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}}}},"patch":{"tags":["Tasks"],"summary":"Update a task","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"title":{"type":"string"},"notes":{"type":"string"},"due_at":{"type":"string","format":"date-time"},"assignee":{"type":"string"},"status":{"type":"string"},"subject_id":{"type":"string"},"alert_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}}}},"delete":{"tags":["Tasks"],"summary":"Delete a task","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/farms/{farm}/events":{"parameters":[{"name":"farm","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Events"],"summary":"List events","parameters":[{"name":"type","in":"query","schema":{"type":"string"}},{"name":"subject_id","in":"query","schema":{"type":"string"}},{"name":"subject_type","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"string"}},{"name":"before","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}}}}}},"post":{"tags":["Events"],"summary":"Create a event","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"subject_type":{"type":"string"},"subject_id":{"type":"string"},"data":{"type":"object"},"at":{"type":"string","format":"date-time"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}}}}},"/v1/events/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Events"],"summary":"Get a event","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}}}},"patch":{"tags":["Events"],"summary":"Update a event","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"type":{"type":"string"},"subject_type":{"type":"string"},"subject_id":{"type":"string"},"data":{"type":"object"},"at":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}}}},"delete":{"tags":["Events"],"summary":"Delete a event","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/farms/{farm}/webhooks":{"parameters":[{"name":"farm","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Webhooks"],"summary":"List webhooks","parameters":[{"name":"limit","in":"query","schema":{"type":"string"}},{"name":"before","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}}}},"post":{"tags":["Webhooks"],"summary":"Create a webhook (returns the signing secret once)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}}}}},"/v1/webhooks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Webhooks"],"summary":"Get a webhook","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}}}},"patch":{"tags":["Webhooks"],"summary":"Update a webhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":[],"properties":{"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}}}},"delete":{"tags":["Webhooks"],"summary":"Delete a webhook","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/tasks/{id}/done":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Tasks"],"summary":"Mark a task done","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}}}}},"/v1/devices/{id}/readings":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Devices"],"summary":"Readings (time series)","parameters":[{"name":"metric","in":"query","schema":{"type":"string"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Reading"}}}}}}}}}},"/v1/devices/{id}/commands":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Devices"],"summary":"Command history","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Command"}}}}}}}}},"post":{"tags":["Devices"],"summary":"Send a command (see /v1/catalog)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["command"],"properties":{"command":{"type":"string"},"params":{"type":"object"}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Command"}}}}}}},"/v1/devices/{id}/key":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Devices"],"summary":"Rotate the device key","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"device_key":{"type":"string"}}}}}}}}},"/v1/ingest":{"post":{"tags":["Ingest"],"summary":"Device report (device key). Returns queued commands.","security":[{"device":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"readings":{"type":"array","items":{"type":"object","required":["metric","value"],"properties":{"metric":{"type":"string"},"value":{"type":"number"},"unit":{"type":"string"},"at":{"type":"string","format":"date-time"}}}},"state":{"type":"object"},"events":{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"data":{"type":"object"},"at":{"type":"string","format":"date-time"}}}},"battery":{"type":"number"},"lat":{"type":"number"},"lon":{"type":"number"},"firmware":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"accepted":{"type":"number"},"commands":{"type":"array","items":{"$ref":"#/components/schemas/Command"}}}}}}}}}},"/v1/device/commands":{"get":{"tags":["Ingest"],"summary":"Poll for queued commands (device key)","security":[{"device":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Command"}}}}}}}}}},"/v1/device/commands/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Ingest"],"summary":"Report a command result (device key)","security":[{"device":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"enum":["done","failed"]},"result":{"type":"object"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Command"}}}}}}},"/v1/me":{"get":{"tags":["Account"],"summary":"Who am I","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/keys":{"get":{"tags":["Account"],"summary":"List API keys","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Key"}}}}}}}}},"post":{"tags":["Account"],"summary":"Create an API key","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"mode":{"enum":["live","test"]}}}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Key"}}}}}}},"/v1/keys/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"tags":["Account"],"summary":"Revoke an API key","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/usage":{"get":{"tags":["Account"],"summary":"Calls by day and surface","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/catalog":{"get":{"tags":["Catalog"],"summary":"Metrics, commands, rules and webhook events","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}