Rations API

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

GET /v1/farm/{farm_id}/rations
POST /v1/farm/{farm_id}/rations
DELETE /v1/farm/{farm_id}/rations/{ration_id}
GET /v1/farm/{farm_id}/rations/{ration_id}
PUT /v1/farm/{farm_id}/rations/{ration_id}
POST /v1/farm/{farm_id}/rations/{ration_id}/assignments
DELETE /v1/farm/{farm_id}/rations/{ration_id}/assignments/{assignment_id}
PUT /v1/farm/{farm_id}/rations/{ration_id}/assignments/{assignment_id}

GET /v1/farm/{farm_id}/rations

Get Rations

Current rations 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"}
include_inactive	query	No	{"type":"boolean"}

Request example

bash example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/rations' \
  -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[].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[].farm_id	string	Required
records[].unit	string	Required
records[].ingredients	array	Required
records[].ingredients[]	object	Required
records[].ingredients[].id	string	Required
records[].ingredients[].name	string	Required
records[].ingredients[].per_head_lbs	string	Required
records[].ingredients[].position	integer	Required
records[].ingredients[].ration_id	string	Required
records[].ingredients[].created_at	string	Required	format: "date-time"
records[].ingredients[].updated_at	string	Required	format: "date-time"
records[].assignments	array	Required
records[].assignments[]	object	Required
records[].assignments[].id	string	Required
records[].assignments[].ration_id	string	Required
records[].assignments[].group_id	string	Required
records[].assignments[].feedings_per_day	integer	Required
records[].assignments[].label	string or null	Required
records[].assignments[].is_active	boolean	Required
records[].assignments[].created_at	string	Required	format: "date-time"
records[].assignments[].updated_at	string	Required	format: "date-time"
records[].assignments[].group	object	Required
records[].assignments[].group.id	string	Required
records[].assignments[].group.name	string	Required

json example

{
  "records": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "farm_id": "11111111-1111-4111-8111-111111111111",
      "name": "Hay ration",
      "unit": "lb",
      "is_active": true,
      "created_at": "2026-09-01T12:00:00.000Z",
      "updated_at": "2026-09-01T12:00:00.000Z",
      "ingredients": [
        {
          "id": "11111111-1111-4111-8111-111111111111",
          "name": "Hay",
          "per_head_lbs": "5.25",
          "position": 0,
          "ration_id": "11111111-1111-4111-8111-111111111111",
          "created_at": "2026-09-01T12:00:00.000Z",
          "updated_at": "2026-09-01T12:00:00.000Z"
        }
      ],
      "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,
          "is_active": true,
          "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"
          }
        }
      ]
    }
  ],
  "total": 1
}

POST /v1/farm/{farm_id}/rations

Create Ration

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

Request body (application/json)

Field	Type	Presence	Constraints
name	string	Required	minLength: 1
unit	string	Optional	minLength: 1
ingredients	array	Required	minItems: 1
ingredients[]	object	Required
ingredients[].id	string	Optional	format: "uuid"
ingredients[].name	string	Required	minLength: 1
ingredients[].per_head_lbs	number	Required	minimum: 0
ingredients[].position	integer	Optional	minimum: 0
assignments	array	Optional
assignments[]	object	Required
assignments[].group_id	string	Required	format: "uuid"
assignments[].feedings_per_day	integer	Optional	minimum: 1; maximum: 12
assignments[].label	string	Optional
assignments[].is_active	boolean	Optional

json example

{
  "name": "Example",
  "ingredients": [
    {
      "name": "Example",
      "per_head_lbs": 1
    }
  ]
}

Request example

bash example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/rations' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Example","ingredients":[{"name":"Example","per_head_lbs":1}]}'

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
id	string	Required
created_at	string	Required	format: "date-time"
updated_at	string	Required	format: "date-time"
name	string	Required
is_active	boolean	Required
farm_id	string	Required
unit	string	Required
ingredients	array	Required
ingredients[]	object	Required
ingredients[].id	string	Required
ingredients[].name	string	Required
ingredients[].per_head_lbs	string	Required
ingredients[].position	integer	Required
ingredients[].ration_id	string	Required
ingredients[].created_at	string	Required	format: "date-time"
ingredients[].updated_at	string	Required	format: "date-time"
assignments	array	Required
assignments[]	object	Required
assignments[].id	string	Required
assignments[].ration_id	string	Required
assignments[].group_id	string	Required
assignments[].feedings_per_day	integer	Required
assignments[].label	string or null	Required
assignments[].is_active	boolean	Required
assignments[].created_at	string	Required	format: "date-time"
assignments[].updated_at	string	Required	format: "date-time"
assignments[].group	object	Required
assignments[].group.id	string	Required
assignments[].group.name	string	Required

json example

{
  "id": "11111111-1111-4111-8111-111111111111",
  "farm_id": "11111111-1111-4111-8111-111111111111",
  "name": "Hay ration",
  "unit": "lb",
  "is_active": true,
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:00:00.000Z",
  "ingredients": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Hay",
      "per_head_lbs": "5.25",
      "position": 0,
      "ration_id": "11111111-1111-4111-8111-111111111111",
      "created_at": "2026-09-01T12:00:00.000Z",
      "updated_at": "2026-09-01T12:00:00.000Z"
    }
  ],
  "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,
      "is_active": true,
      "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"
      }
    }
  ]
}

DELETE /v1/farm/{farm_id}/rations/{ration_id}

Delete Ration

Current rations 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. 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"}
ration_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>/rations/<ration_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}/rations/{ration_id}

Get Ration

Current rations 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"}
ration_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>/rations/<ration_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
id	string	Required
created_at	string	Required	format: "date-time"
updated_at	string	Required	format: "date-time"
name	string	Required
is_active	boolean	Required
farm_id	string	Required
unit	string	Required
ingredients	array	Required
ingredients[]	object	Required
ingredients[].id	string	Required
ingredients[].name	string	Required
ingredients[].per_head_lbs	string	Required
ingredients[].position	integer	Required
ingredients[].ration_id	string	Required
ingredients[].created_at	string	Required	format: "date-time"
ingredients[].updated_at	string	Required	format: "date-time"
assignments	array	Required
assignments[]	object	Required
assignments[].id	string	Required
assignments[].ration_id	string	Required
assignments[].group_id	string	Required
assignments[].feedings_per_day	integer	Required
assignments[].label	string or null	Required
assignments[].is_active	boolean	Required
assignments[].created_at	string	Required	format: "date-time"
assignments[].updated_at	string	Required	format: "date-time"
assignments[].group	object	Required
assignments[].group.id	string	Required
assignments[].group.name	string	Required

json example

{
  "id": "11111111-1111-4111-8111-111111111111",
  "farm_id": "11111111-1111-4111-8111-111111111111",
  "name": "Hay ration",
  "unit": "lb",
  "is_active": true,
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:00:00.000Z",
  "ingredients": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Hay",
      "per_head_lbs": "5.25",
      "position": 0,
      "ration_id": "11111111-1111-4111-8111-111111111111",
      "created_at": "2026-09-01T12:00:00.000Z",
      "updated_at": "2026-09-01T12:00:00.000Z"
    }
  ],
  "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,
      "is_active": true,
      "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"
      }
    }
  ]
}

PUT /v1/farm/{farm_id}/rations/{ration_id}

Update Ration

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

Request body (application/json)

Field	Type	Presence	Constraints
name	string	Optional	minLength: 1
unit	string	Optional	minLength: 1
is_active	boolean	Optional
ingredients	array	Optional	minItems: 1
ingredients[]	object	Required
ingredients[].id	string	Optional	format: "uuid"
ingredients[].name	string	Required	minLength: 1
ingredients[].per_head_lbs	number	Required	minimum: 0
ingredients[].position	integer	Optional	minimum: 0

json example

{}

Request example

bash example

curl --fail-with-body -X PUT \
  'https://api.ranch.bot/v1/farm/<farm_id>/rations/<ration_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
id	string	Required
created_at	string	Required	format: "date-time"
updated_at	string	Required	format: "date-time"
name	string	Required
is_active	boolean	Required
farm_id	string	Required
unit	string	Required
ingredients	array	Required
ingredients[]	object	Required
ingredients[].id	string	Required
ingredients[].name	string	Required
ingredients[].per_head_lbs	string	Required
ingredients[].position	integer	Required
ingredients[].ration_id	string	Required
ingredients[].created_at	string	Required	format: "date-time"
ingredients[].updated_at	string	Required	format: "date-time"
assignments	array	Required
assignments[]	object	Required
assignments[].id	string	Required
assignments[].ration_id	string	Required
assignments[].group_id	string	Required
assignments[].feedings_per_day	integer	Required
assignments[].label	string or null	Required
assignments[].is_active	boolean	Required
assignments[].created_at	string	Required	format: "date-time"
assignments[].updated_at	string	Required	format: "date-time"
assignments[].group	object	Required
assignments[].group.id	string	Required
assignments[].group.name	string	Required

json example

{
  "id": "11111111-1111-4111-8111-111111111111",
  "farm_id": "11111111-1111-4111-8111-111111111111",
  "name": "Hay ration",
  "unit": "lb",
  "is_active": true,
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:00:00.000Z",
  "ingredients": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Hay",
      "per_head_lbs": "5.25",
      "position": 0,
      "ration_id": "11111111-1111-4111-8111-111111111111",
      "created_at": "2026-09-01T12:00:00.000Z",
      "updated_at": "2026-09-01T12:00:00.000Z"
    }
  ],
  "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,
      "is_active": true,
      "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}/rations/{ration_id}/assignments

Create Assignment

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

Request body (application/json)

Field	Type	Presence	Constraints
group_id	string	Required	format: "uuid"
feedings_per_day	integer	Optional	minimum: 1; maximum: 12
label	string	Optional
is_active	boolean	Optional

json example

{
  "group_id": "11111111-1111-4111-8111-111111111111"
}

Request example

bash example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/rations/<ration_id>/assignments' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"group_id":"11111111-1111-4111-8111-111111111111"}'

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
id	string	Required
created_at	string	Required	format: "date-time"
updated_at	string	Required	format: "date-time"
is_active	boolean	Required
group_id	string	Required
ration_id	string	Required
feedings_per_day	number	Required
label (variant 1)	null	Required
label (variant 2)	string	Required

json example

{
  "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,
  "group_id": "11111111-1111-4111-8111-111111111111",
  "ration_id": "11111111-1111-4111-8111-111111111111",
  "feedings_per_day": 1,
  "label": null
}

DELETE /v1/farm/{farm_id}/rations/{ration_id}/assignments/{assignment_id}

Delete Assignment

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
ration_id	path	Yes	{"type":"string","format":"uuid"}
assignment_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>/rations/<ration_id>/assignments/<assignment_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

PUT /v1/farm/{farm_id}/rations/{ration_id}/assignments/{assignment_id}

Update Assignment

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

Request body (application/json)

Field	Type	Presence	Constraints
feedings_per_day	integer	Optional	minimum: 1; maximum: 12
label	string or null	Optional
is_active	boolean	Optional

json example

{}

Request example

bash example

curl --fail-with-body -X PUT \
  'https://api.ranch.bot/v1/farm/<farm_id>/rations/<ration_id>/assignments/<assignment_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
id	string	Required
created_at	string	Required	format: "date-time"
updated_at	string	Required	format: "date-time"
is_active	boolean	Required
group_id	string	Required
ration_id	string	Required
feedings_per_day	number	Required
label (variant 1)	null	Required
label (variant 2)	string	Required

json example

{
  "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,
  "group_id": "11111111-1111-4111-8111-111111111111",
  "ration_id": "11111111-1111-4111-8111-111111111111",
  "feedings_per_day": 1,
  "label": null
}

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