Roots docs

API reference

Base URL https://api.roots.sh. Send Authorization: Bearer rk_… on every request. Bodies are JSON. The machine-readable spec is at api.roots.sh/openapi.json.

Lists return { "data": [...] } and take limit (up to 500) and before (an ISO time) to page back.

FarmsAlertsRoostAnimalsGroupsPaddocksDevicesTasksEventsWebhooksIngestAccountCatalog

Farms

GET /v1/farms

List farms

POST /v1/farms

Create a farm

Field Type
name * string
timezone string
lat number
lon number
acres number
GET /v1/farms/{farm}

Get a farm

PATCH /v1/farms/{farm}

Update a farm (settings.rules overrides alert thresholds)

Field Type
id string
name string
mode live · test
timezone string
lat number
lon number
acres number
sample boolean
settings object
created_at ISO time
DELETE /v1/farms/{farm}

Delete a farm

GET /v1/farms/{farm}/brief

Morning brief: what needs you, ranked

Alerts

GET /v1/farms/{farm}/alerts

List alerts

Query: status

GET /v1/alerts/{id}

Get an alert

POST /v1/alerts/{id}/acknowledge

Acknowledge an alert

POST /v1/alerts/{id}/resolve

Resolve an alert

Roost

GET /v1/farms/{farm}/roosts

Every Roost with its latest readings and recent commands

GET /v1/roosts/{id}

One Roost

Animals

GET /v1/farms/{farm}/animals

List animals

Query: species, group_id, paddock_id, status, tag, eid, q, limit, before

POST /v1/farms/{farm}/animals

Create an animal

Field Type
species * string
name string
tag string
eid string
sex string
breed string
birth_date ISO time
group_id string
paddock_id string
status string
notes string
fields object
GET /v1/animals/{id}

Get an animal

PATCH /v1/animals/{id}

Update an animal

Field Type
species string
name string
tag string
eid string
sex string
breed string
birth_date ISO time
group_id string
paddock_id string
status string
notes string
fields object
DELETE /v1/animals/{id}

Delete an animal

Groups

GET /v1/farms/{farm}/groups

List groups

Query: species, kind, paddock_id, limit, before

POST /v1/farms/{farm}/groups

Create a group

Field Type
name * string
species * string
kind string
head_count number
hatch_date ISO time
paddock_id string
GET /v1/groups/{id}

Get a group

PATCH /v1/groups/{id}

Update a group

Field Type
name string
species string
kind string
head_count number
hatch_date ISO time
paddock_id string
DELETE /v1/groups/{id}

Delete a group

Paddocks

GET /v1/farms/{farm}/paddocks

List paddocks

Query: limit, before

POST /v1/farms/{farm}/paddocks

Create a paddock

Field Type
name * string
acres number
geometry object
rest_days_target number
last_grazed_at ISO time
GET /v1/paddocks/{id}

Get a paddock

PATCH /v1/paddocks/{id}

Update a paddock

Field Type
name string
acres number
geometry object
rest_days_target number
last_grazed_at ISO time
DELETE /v1/paddocks/{id}

Delete a paddock

Devices

GET /v1/farms/{farm}/devices

List devices

Query: type, animal_id, group_id, limit, before

POST /v1/farms/{farm}/devices

Create a device (returns device_key once)

Field Type
type * string
name * string
serial string
animal_id string
group_id string
firmware string
lat number
lon number
GET /v1/devices/{id}

Get a device

PATCH /v1/devices/{id}

Update a device

Field Type
type string
name string
serial string
animal_id string
group_id string
firmware string
lat number
lon number
DELETE /v1/devices/{id}

Delete a device

GET /v1/devices/{id}/readings

Readings (time series)

Query: metric, since, limit

GET /v1/devices/{id}/commands

Command history

POST /v1/devices/{id}/commands

Send a command (see /v1/catalog)

Field Type
command * string
params object
POST /v1/devices/{id}/key

Rotate the device key

Tasks

GET /v1/farms/{farm}/tasks

List tasks

Query: status, assignee, subject_id, limit, before

POST /v1/farms/{farm}/tasks

Create a task

Field Type
title * string
notes string
due_at ISO time
assignee string
status string
subject_id string
alert_id string
GET /v1/tasks/{id}

Get a task

PATCH /v1/tasks/{id}

Update a task

Field Type
title string
notes string
due_at ISO time
assignee string
status string
subject_id string
alert_id string
DELETE /v1/tasks/{id}

Delete a task

POST /v1/tasks/{id}/done

Mark a task done

Events

GET /v1/farms/{farm}/events

List events

Query: type, subject_id, subject_type, limit, before

POST /v1/farms/{farm}/events

Create a event

Field Type
type * string
subject_type string
subject_id string
data object
at ISO time
GET /v1/events/{id}

Get a event

PATCH /v1/events/{id}

Update a event

Field Type
type string
subject_type string
subject_id string
data object
at ISO time
DELETE /v1/events/{id}

Delete a event

Webhooks

GET /v1/farms/{farm}/webhooks

List webhooks

Query: limit, before

POST /v1/farms/{farm}/webhooks

Create a webhook (returns the signing secret once)

Field Type
url * string
events string[]
GET /v1/webhooks/{id}

Get a webhook

PATCH /v1/webhooks/{id}

Update a webhook

Field Type
url string
events string[]
DELETE /v1/webhooks/{id}

Delete a webhook

Ingest

POST /v1/ingest

Device report (device key). Returns queued commands. Takes a device key (rd_…).

Field Type
readings object[]
state object
events object[]
battery number
lat number
lon number
firmware string
GET /v1/device/commands

Poll for queued commands (device key) Takes a device key (rd_…).

POST /v1/device/commands/{id}

Report a command result (device key) Takes a device key (rd_…).

Field Type
status * done · failed
result object

Account

GET /v1/me

Who am I

GET /v1/keys

List API keys

POST /v1/keys

Create an API key

Field Type
name string
mode live · test
DELETE /v1/keys/{id}

Revoke an API key

GET /v1/usage

Calls by day and surface

Catalog

GET /v1/catalog

Metrics, commands, rules and webhook events No key needed.

Objects

Error

error

Farm

id · name · mode · timezone · lat · lon · acres · sample · settings · created_at

Alert

id · farm_id · severity · title · reason · rule · subject_type · subject_id · status · created_at · resolved_at

Command

id · device_id · command · params · status · result · created_at · done_at

Reading

metric · value · unit · at

Brief

headline · text · alerts · tasks · roosts

Key

id · name · mode · prefix · key · created_at · last_used_at

Animal

id · farm_id · species · name · tag · eid · sex · breed · birth_date · group_id · paddock_id · status · notes · fields · created_at

Group

id · farm_id · name · species · kind · head_count · hatch_date · paddock_id · created_at

Paddock

id · farm_id · name · acres · geometry · rest_days_target · last_grazed_at · created_at

Device

id · farm_id · type · name · serial · animal_id · group_id · firmware · lat · lon · battery · state · last_seen_at · created_at

Task

id · farm_id · title · notes · due_at · assignee · status · subject_id · alert_id · created_at

Event

id · farm_id · type · subject_type · subject_id · data · at · created_at

Webhook

id · farm_id · url · events · created_at