Farm tasks API

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

GET /v1/farm/{farm_id}/farm-tasks
PUT /v1/farm/{farm_id}/farm-tasks/{task_id}

GET /v1/farm/{farm_id}/farm-tasks

List farm follow-up tasks

List linked birth tasks. Undated TODO tasks remain visible and sort before dated tasks. External credential scopes: read:records. Minimum farm role: READER.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
skip	query	No	{"type":"integer","minimum":0,"default":0}
take	query	No	{"type":"integer","minimum":1,"maximum":200,"default":50}
status	query	No	{"type":"string","enum":["TODO","DONE","CANCELLED"]}

Request example

bash example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/farm-tasks' \
  -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	integer	Required	minimum: 0
records	array	Required
records[]	object	Required
records[].id	string	Required	format: "uuid"
records[].farm_id	string	Required	format: "uuid"
records[].birth_event_id	string	Required	format: "uuid"
records[].name	string	Required
records[].status	string	Required	enum: ["TODO","DONE","CANCELLED"]
records[].due_date	string or null	Required	format: "date-time"
records[].created_at	string	Required	format: "date-time"
records[].updated_at	string	Required	format: "date-time"
records[].animals	array	Optional
records[].animals[]	object	Required
records[].animals[].id	string	Required	format: "uuid"

PUT /v1/farm/{farm_id}/farm-tasks/{task_id}

Update a farm follow-up task

Set status and optionally the due date. Omitting due_date preserves it; null clears it. A provided date must be a real calendar date. External credential scopes: write:records. Minimum farm role: EDITOR.

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

Request body (application/json)

Field	Type	Presence	Constraints
status	string	Required	enum: ["TODO","DONE","CANCELLED"]
due_date	string or null	Optional	format: "date"

Create request.json with a JSON body matching the request schema above before running this example.

Request example

bash example

curl --fail-with-body -X PUT \
  'https://api.ranch.bot/v1/farm/<farm_id>/farm-tasks/<task_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

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
409	The approved preview is stale, the request ID is already used, or the protocol version has different steps.	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	format: "uuid"
farm_id	string	Required	format: "uuid"
birth_event_id	string	Required	format: "uuid"
name	string	Required
status	string	Required	enum: ["TODO","DONE","CANCELLED"]
due_date	string or null	Required	format: "date-time"
created_at	string	Required	format: "date-time"
updated_at	string	Required	format: "date-time"
animals	array	Optional
animals[]	object	Required
animals[].id	string	Required	format: "uuid"

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