Records API

HTTP reference for records. Read authentication and access before using these operations. All examples use made-up data and placeholder credentials.

GET /v1/farm/{farm_id}/records
POST /v1/farm/{farm_id}/records
DELETE /v1/farm/{farm_id}/records/{record_id}
GET /v1/farm/{farm_id}/records/{record_id}
PUT /v1/farm/{farm_id}/records/{record_id}

GET /v1/farm/{farm_id}/records

Get Records

Current records HTTP operation. External credential scopes: read:records. Minimum farm role: READER. Pagination accepts integer skip and take; set both explicitly. An omitted value passes through to the data query. Collection property names differ by resource; use the response schema. Production rate limit: 100 requests per 15-minute window, per legacy key, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
skip	query	No	{"type":"integer"}
take	query	No	{"type":"integer"}

Request example

bash example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/records' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

Status	Meaning	Content type
200	Success	application/json
400	Request validation failed.	application/json
401	Missing/invalid authentication or insufficient farm role.	application/json
403	Missing required scope or credential type is disallowed.	application/json
404	Resource or active farm membership not found.	application/json
429	Rate limit exceeded. Retry after the indicated delay.	application/json
500	Unexpected server failure.	application/json

200 response schema (application/json)

Field	Type	Presence	Constraints
total	number	Required
records	array	Required
records[]	object	Required
records[].type	string	Required	enum: ["OTHER","FEED","GENETIC","HEALTH","MOVEMENT"]
records[].id	string	Required
records[].created_at	string	Required	format: "date-time"
records[].updated_at	string	Required	format: "date-time"
records[].name	string	Required
records[].is_active	boolean	Required
records[].description (variant 1)	null	Required
records[].description (variant 2)	string	Required
records[].applied_at	string	Required	format: "date-time"
records[].record_items	array	Required
records[].record_items[]	object	Required
records[].record_items[].id (variant 1)	string	Required
records[].record_items[].id (variant 2)	null	Required
records[].record_items[].description (variant 1)	string	Required
records[].record_items[].description (variant 2)	null	Required
records[].record_items[].is_active (variant 1)	boolean	Required
records[].record_items[].is_active (variant 2)	null	Required
records[].record_items[].metadata (variant 1)	JSON	Required
records[].record_items[].metadata (variant 2)	null	Required
records[].record_items[].name (variant 1)	string	Required
records[].record_items[].name (variant 2)	null	Required
records[].record_items[].created_at (variant 1)	string	Required	format: "date-time"
records[].record_items[].created_at (variant 2)	null	Required
records[].record_items[].updated_at (variant 1)	string	Required	format: "date-time"
records[].record_items[].updated_at (variant 2)	null	Required
records[].files	array	Required
records[].files[]	object	Required
records[].files[].id (variant 1)	string	Required
records[].files[].id (variant 2)	null	Required
records[].files[].is_active (variant 1)	boolean	Required
records[].files[].is_active (variant 2)	null	Required
records[].files[].mime_type (variant 1)	string	Required
records[].files[].mime_type (variant 2)	null	Required
records[].files[].name (variant 1)	string	Required
records[].files[].name (variant 2)	null	Required
records[].files[].size (variant 1)	integer	Required
records[].files[].size (variant 2)	null	Required
records[].files[].url (variant 1)	string	Required
records[].files[].url (variant 2)	null	Required
records[].files[].created_at (variant 1)	string	Required	format: "date-time"
records[].files[].created_at (variant 2)	null	Required
records[].files[].updated_at (variant 1)	string	Required	format: "date-time"
records[].files[].updated_at (variant 2)	null	Required

json example

{
  "total": 0,
  "records": []
}

POST /v1/farm/{farm_id}/records

Create Record

Current records HTTP operation. External credential scopes: write:records. Minimum farm role: EDITOR. Direct requests execute without an app confirmation screen. Production rate limit: 100 requests per 15-minute window, per legacy key, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429. At least one animal_ids or group_ids entry is required. Associations must name active entities in this farm; the service filters out ids outside that set. Supply ids obtained from the same farm.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}

Request body (application/json)

Field	Type	Presence	Constraints
(variant 1)	JSON	Required
(variant 1).animal_ids	JSON	Required	minItems: 1
(variant 2)	JSON	Required
(variant 2).group_ids	JSON	Required	minItems: 1

json example

{
  "animal_ids": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "group_ids": [],
  "name": "Example observation",
  "type": "OTHER",
  "applied_at": "2026-09-01T12:00:00.000Z"
}

Request example

bash example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/records' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"animal_ids":["11111111-1111-4111-8111-111111111111"],"group_ids":[],"name":"Example observation","type":"OTHER","applied_at":"2026-09-01T12:00:00.000Z"}'

Responses

Status	Meaning	Content type
201	Success	application/json
400	Request validation failed.	application/json
401	Missing/invalid authentication or insufficient farm role.	application/json
403	Missing required scope or credential type is disallowed.	application/json
404	Resource or active farm membership not found.	application/json
429	Rate limit exceeded. Retry after the indicated delay.	application/json
500	Unexpected server failure.	application/json

201 response schema (application/json)

Field	Type	Presence	Constraints
type	string	Required	enum: ["OTHER","FEED","GENETIC","HEALTH","MOVEMENT"]
id	string	Required
created_at	string	Required	format: "date-time"
updated_at	string	Required	format: "date-time"
name	string	Required
is_active	boolean	Required
description (variant 1)	null	Required
description (variant 2)	string	Required
applied_at	string	Required	format: "date-time"

json example

{
  "type": "OTHER",
  "id": "11111111-1111-4111-8111-111111111111",
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:00:00.000Z",
  "name": "Example",
  "is_active": true,
  "description": null,
  "applied_at": "2026-09-01T12:00:00.000Z"
}

DELETE /v1/farm/{farm_id}/records/{record_id}

Delete Record

Current records HTTP operation. External credential scopes: write:records. Minimum farm role: OWNER. Direct requests execute without an app confirmation screen. Production rate limit: 100 requests per 15-minute window, per legacy key, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429. Deletion behavior is described below; a successful status does not imply erasure from all retained history. Marks the stored entity inactive (soft deletion).

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
record_id	path	Yes	{"type":"string","format":"uuid"}

Request example

bash example

curl --fail-with-body -X DELETE \
  'https://api.ranch.bot/v1/farm/<farm_id>/records/<record_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

Status	Meaning	Content type
204	Completed; no response body.	No body
400	Request validation failed.	application/json
401	Missing/invalid authentication or insufficient farm role.	application/json
403	Missing required scope or credential type is disallowed.	application/json
404	Resource or active farm membership not found.	application/json
429	Rate limit exceeded. Retry after the indicated delay.	application/json
500	Unexpected server failure.	application/json

GET /v1/farm/{farm_id}/records/{record_id}

Get Record

Current records HTTP operation. External credential scopes: read:records. Minimum farm role: READER. Production rate limit: 100 requests per 15-minute window, per legacy key, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
record_id	path	Yes	{"type":"string","format":"uuid"}

Request example

bash example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/records/<record_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

Status	Meaning	Content type
200	Success	application/json
400	Request validation failed.	application/json
401	Missing/invalid authentication or insufficient farm role.	application/json
403	Missing required scope or credential type is disallowed.	application/json
404	Resource or active farm membership not found.	application/json
429	Rate limit exceeded. Retry after the indicated delay.	application/json
500	Unexpected server failure.	application/json

200 response schema (application/json)

Field	Type	Presence	Constraints
type	string	Required	enum: ["OTHER","FEED","GENETIC","HEALTH","MOVEMENT"]
id	string	Required
created_at	string	Required	format: "date-time"
updated_at	string	Required	format: "date-time"
name	string	Required
is_active	boolean	Required
description (variant 1)	null	Required
description (variant 2)	string	Required
applied_at	string	Required	format: "date-time"
record_items	array	Required
record_items[]	object	Required
record_items[].id (variant 1)	string	Required
record_items[].id (variant 2)	null	Required
record_items[].description (variant 1)	string	Required
record_items[].description (variant 2)	null	Required
record_items[].is_active (variant 1)	boolean	Required
record_items[].is_active (variant 2)	null	Required
record_items[].metadata (variant 1)	JSON	Required
record_items[].metadata (variant 2)	null	Required
record_items[].name (variant 1)	string	Required
record_items[].name (variant 2)	null	Required
record_items[].created_at (variant 1)	string	Required	format: "date-time"
record_items[].created_at (variant 2)	null	Required
record_items[].updated_at (variant 1)	string	Required	format: "date-time"
record_items[].updated_at (variant 2)	null	Required
files	array	Required
files[]	object	Required
files[].id (variant 1)	string	Required
files[].id (variant 2)	null	Required
files[].is_active (variant 1)	boolean	Required
files[].is_active (variant 2)	null	Required
files[].mime_type (variant 1)	string	Required
files[].mime_type (variant 2)	null	Required
files[].name (variant 1)	string	Required
files[].name (variant 2)	null	Required
files[].size (variant 1)	integer	Required
files[].size (variant 2)	null	Required
files[].url (variant 1)	string	Required
files[].url (variant 2)	null	Required
files[].created_at (variant 1)	string	Required	format: "date-time"
files[].created_at (variant 2)	null	Required
files[].updated_at (variant 1)	string	Required	format: "date-time"
files[].updated_at (variant 2)	null	Required

json example

{
  "type": "OTHER",
  "id": "11111111-1111-4111-8111-111111111111",
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:00:00.000Z",
  "name": "Example",
  "is_active": true,
  "description": null,
  "applied_at": "2026-09-01T12:00:00.000Z",
  "record_items": [],
  "files": []
}

PUT /v1/farm/{farm_id}/records/{record_id}

Update Record

Current records HTTP operation. External credential scopes: write:records. Minimum farm role: EDITOR. Direct requests execute without an app confirmation screen. Production rate limit: 100 requests per 15-minute window, per legacy key, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429. Provided association ids are connected to the record; they do not replace the entire association set.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
record_id	path	Yes	{"type":"string","format":"uuid"}

Request body (application/json)

Field	Type	Presence	Constraints
animal_ids	array	Optional	default: []
animal_ids[]	string	Required	format: "uuid"
group_ids	array	Optional	default: []
group_ids[]	string	Required	format: "uuid"
description	string	Optional
name	string	Optional
type	string	Optional	enum: ["FEED","GENETIC","HEALTH","MOVEMENT","OTHER"]
applied_at	string	Optional	format: "date-time"

json example

{}

Request example

bash example

curl --fail-with-body -X PUT \
  'https://api.ranch.bot/v1/farm/<farm_id>/records/<record_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'

Responses

Status	Meaning	Content type
200	Success	application/json
400	Request validation failed.	application/json
401	Missing/invalid authentication or insufficient farm role.	application/json
403	Missing required scope or credential type is disallowed.	application/json
404	Resource or active farm membership not found.	application/json
429	Rate limit exceeded. Retry after the indicated delay.	application/json
500	Unexpected server failure.	application/json

200 response schema (application/json)

Field	Type	Presence	Constraints
type	string	Required	enum: ["OTHER","FEED","GENETIC","HEALTH","MOVEMENT"]
id	string	Required
created_at	string	Required	format: "date-time"
updated_at	string	Required	format: "date-time"
name	string	Required
is_active	boolean	Required
description (variant 1)	null	Required
description (variant 2)	string	Required
applied_at	string	Required	format: "date-time"

json example

{
  "type": "OTHER",
  "id": "11111111-1111-4111-8111-111111111111",
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:00:00.000Z",
  "name": "Example",
  "is_active": true,
  "description": null,
  "applied_at": "2026-09-01T12:00:00.000Z"
}

Error body

Validation and authentication errors generally use this envelope. Rate-limit errors omit data; OAuth polling also has protocol-specific errors shown in its reference.

json example

{
  "success": false,
  "errors": [
    {
      "code": 400,
      "name": "ValidationError",
      "message": "Example validation failure"
    }
  ]
}