Feedings API

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

GET /v1/farm/{farm_id}/feedings
GET /v1/farm/{farm_id}/feedings/{feeding_id}
POST /v1/farm/{farm_id}/feedings/{feeding_id}/sync
POST /v1/farm/{farm_id}/feedings/{feeding_id}/undo

GET /v1/farm/{farm_id}/feedings

Get Feedings

Current feedings 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"}
status	query	No	{"type":"string","enum":["ACTIVE","COMPLETED"]}
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>/feedings' \
  -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[].id	string	Required
records[].ration_id	string	Required
records[].ration_name	string	Required
records[].status	string	Required	enum: ["ACTIVE","COMPLETED"]
records[].fed_at	string	Required	format: "date-time"
records[].scale_factor	string	Required
records[].delivery_count	number	Required
records[].total_delivered_lbs	number	Required

json example

{
  "total": 1,
  "records": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "ration_id": "11111111-1111-4111-8111-111111111111",
      "ration_name": "Hay ration",
      "status": "ACTIVE",
      "fed_at": "2026-09-01T12:00:00.000Z",
      "scale_factor": "1.25",
      "delivery_count": 1,
      "total_delivered_lbs": 12.5
    }
  ]
}

GET /v1/farm/{farm_id}/feedings/{feeding_id}

Get Feeding

Current feedings 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"}
feeding_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>/feedings/<feeding_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
status	string	Required	enum: ["ACTIVE","COMPLETED"]
id	string	Required
created_at	string	Required	format: "date-time"
updated_at	string	Required	format: "date-time"
is_active	boolean	Required
farm_id	string	Required
ingredients	JSON	Required
ration_id	string	Required
client_updated_at	string	Required	format: "date-time"
fed_at	string	Required	format: "date-time"
scale_factor	string	Required
ration	object	Required
ration.id	string	Required
ration.name	string	Required
ration.unit	string	Required
deliveries	array	Required
deliveries[]	object	Required
deliveries[].id	string	Required
deliveries[].feeding_id	string	Required
deliveries[].group_id	string	Required
deliveries[].actual_lbs	string	Required
deliveries[].client_updated_at	string	Required	format: "date-time"
deliveries[].head_count	integer	Required
deliveries[].is_active	boolean	Required
deliveries[].record_id	string or null	Required
deliveries[].created_at	string	Required	format: "date-time"
deliveries[].updated_at	string	Required	format: "date-time"
deliveries[].group	object	Required
deliveries[].group.id	string	Required
deliveries[].group.name	string	Required

json example

{
  "status": "ACTIVE",
  "id": "11111111-1111-4111-8111-111111111111",
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:00:00.000Z",
  "is_active": true,
  "farm_id": "11111111-1111-4111-8111-111111111111",
  "ingredients": [
    {
      "name": "Hay",
      "per_head_lbs": 5.25,
      "position": 0,
      "target_lbs": 12.5,
      "actual_lbs": 12.5
    }
  ],
  "ration_id": "11111111-1111-4111-8111-111111111111",
  "client_updated_at": "2026-09-01T12:00:00.000Z",
  "fed_at": "2026-09-01T12:00:00.000Z",
  "scale_factor": "1.25",
  "ration": {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "Hay ration",
    "unit": "lb"
  },
  "deliveries": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "feeding_id": "11111111-1111-4111-8111-111111111111",
      "group_id": "11111111-1111-4111-8111-111111111111",
      "actual_lbs": "12.5",
      "client_updated_at": "2026-09-01T12:00:00.000Z",
      "head_count": 10,
      "is_active": true,
      "record_id": null,
      "created_at": "2026-09-01T12:00:00.000Z",
      "updated_at": "2026-09-01T12:00:00.000Z",
      "group": {
        "id": "11111111-1111-4111-8111-111111111111",
        "name": "Ewes"
      }
    }
  ]
}

POST /v1/farm/{farm_id}/feedings/{feeding_id}/sync

Sync Feeding

Current feedings 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.

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

Request body (application/json)

Field	Type	Presence	Constraints
feeding	object	Required
feeding.ration_id	string	Required	format: "uuid"
feeding.status	string	Required	enum: ["ACTIVE","COMPLETED"]
feeding.fed_at	string	Required	format: "date-time"
feeding.scale_factor	number	Required
feeding.ingredients	array	Required	minItems: 1
feeding.ingredients[]	object	Required
feeding.ingredients[].ingredient_id	string	Optional	format: "uuid"
feeding.ingredients[].name	string	Required	minLength: 1
feeding.ingredients[].per_head_lbs	number	Required	minimum: 0
feeding.ingredients[].position	integer	Required	minimum: 0
feeding.ingredients[].target_lbs	number	Required	minimum: 0
feeding.ingredients[].actual_lbs	number	Optional	minimum: 0
feeding.ingredients[].skipped	boolean	Optional
feeding.client_updated_at	string	Required	format: "date-time"
deliveries	array	Required
deliveries[]	object	Required
deliveries[].id	string	Required	format: "uuid"
deliveries[].group_id	string	Required	format: "uuid"
deliveries[].head_count	integer	Required	minimum: 0
deliveries[].actual_lbs	number	Required	minimum: 0
deliveries[].client_updated_at	string	Required	format: "date-time"
deliveries[].deleted	boolean	Optional

json example

{
  "feeding": {
    "ration_id": "11111111-1111-4111-8111-111111111111",
    "status": "ACTIVE",
    "fed_at": "2026-09-01T12:00:00.000Z",
    "scale_factor": 1,
    "ingredients": [
      {
        "name": "Example",
        "per_head_lbs": 1,
        "position": 1,
        "target_lbs": 1
      }
    ],
    "client_updated_at": "2026-09-01T12:00:00.000Z"
  },
  "deliveries": []
}

Request example

bash example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/feedings/<feeding_id>/sync' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"feeding":{"ration_id":"11111111-1111-4111-8111-111111111111","status":"ACTIVE","fed_at":"2026-09-01T12:00:00.000Z","scale_factor":1,"ingredients":[{"name":"Example","per_head_lbs":1,"position":1,"target_lbs":1}],"client_updated_at":"2026-09-01T12:00:00.000Z"},"deliveries":[]}'

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
feeding	object	Required
feeding.status	string	Required	enum: ["ACTIVE","COMPLETED"]
feeding.id	string	Required
feeding.created_at	string	Required	format: "date-time"
feeding.updated_at	string	Required	format: "date-time"
feeding.is_active	boolean	Required
feeding.farm_id	string	Required
feeding.ingredients	JSON	Required
feeding.ration_id	string	Required
feeding.client_updated_at	string	Required	format: "date-time"
feeding.fed_at	string	Required	format: "date-time"
feeding.scale_factor	string	Required
results	array	Required
results[]	object	Required
results[].delivery_id	string	Required
results[].status	string	Required	enum: ["error","created","updated","unchanged","deleted"]
results[].record_id	string	Optional
results[].error	string	Optional

json example

{
  "feeding": {
    "status": "ACTIVE",
    "id": "11111111-1111-4111-8111-111111111111",
    "created_at": "2026-09-01T12:00:00.000Z",
    "updated_at": "2026-09-01T12:00:00.000Z",
    "is_active": true,
    "farm_id": "11111111-1111-4111-8111-111111111111",
    "ingredients": null,
    "ration_id": "11111111-1111-4111-8111-111111111111",
    "client_updated_at": "2026-09-01T12:00:00.000Z",
    "fed_at": "2026-09-01T12:00:00.000Z",
    "scale_factor": "1.25"
  },
  "results": []
}

POST /v1/farm/{farm_id}/feedings/{feeding_id}/undo

Undo Feeding

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

Request example

bash example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/feedings/<feeding_id>/undo' \
  -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
feeding_id	string	Required
undone	boolean	Required

json example

{
  "feeding_id": "11111111-1111-4111-8111-111111111111",
  "undone": true
}

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