Feeding plans API

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

GET /v1/farm/{farm_id}/feed-plan

GET /v1/farm/{farm_id}/feed-plan

Get Feed Plan

Current feeding plans 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"}
since	query	No	{"type":"string","format":"date-time"}

Request example

bash example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/feed-plan' \
  -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
synced_at	string	Required
rations	array	Required
rations[]	object	Required
rations[].id	string	Required
rations[].name	string	Required
rations[].unit	string	Required
rations[].ingredients	array	Required
rations[].ingredients[]	object	Required
rations[].ingredients[].id	string	Required
rations[].ingredients[].name	string	Required
rations[].ingredients[].per_head_lbs	string	Required
rations[].ingredients[].position	integer	Required
assignments	array	Required
assignments[]	object	Required
assignments[].id	string	Required
assignments[].ration_id	string	Required
assignments[].group_id	string	Required
assignments[].feedings_per_day	number	Required
assignments[].label (variant 1)	null	Required
assignments[].label (variant 2)	string	Required
assignments[].group	object	Required
assignments[].group.id	string	Required
assignments[].group.name	string	Required
assignments[].group.head_count	number	Required
recent_deliveries	array	Required
recent_deliveries[]	object	Required
recent_deliveries[].feeding_id	string	Required
recent_deliveries[].ration_id	string	Required
recent_deliveries[].group_id	string	Required
recent_deliveries[].fed_at	string	Required	format: "date-time"
recent_deliveries[].delivered_lbs	string	Required
recent_deliveries[].status	string	Required	enum: ["ACTIVE","COMPLETED"]

json example

{
  "synced_at": "2026-09-01T12:00:00.000Z",
  "rations": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Hay ration",
      "unit": "lb",
      "ingredients": [
        {
          "id": "11111111-1111-4111-8111-111111111111",
          "name": "Hay",
          "per_head_lbs": "5.25",
          "position": 0
        }
      ]
    }
  ],
  "assignments": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "ration_id": "11111111-1111-4111-8111-111111111111",
      "group_id": "11111111-1111-4111-8111-111111111111",
      "feedings_per_day": 2,
      "label": null,
      "group": {
        "id": "11111111-1111-4111-8111-111111111111",
        "name": "Ewes",
        "head_count": 10
      }
    }
  ],
  "recent_deliveries": [
    {
      "feeding_id": "11111111-1111-4111-8111-111111111111",
      "ration_id": "11111111-1111-4111-8111-111111111111",
      "group_id": "11111111-1111-4111-8111-111111111111",
      "fed_at": "2026-09-01T12:00:00.000Z",
      "delivered_lbs": "12.5",
      "status": "ACTIVE"
    }
  ]
}

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"
    }
  ]
}