Scheduled events API

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

GET /v1/farm/{farm_id}/scheduled-events
POST /v1/farm/{farm_id}/scheduled-events
GET /v1/farm/{farm_id}/scheduled-events/{scheduled_event_id}
POST /v1/farm/{farm_id}/scheduled-events/{scheduled_event_id}/approve
POST /v1/farm/{farm_id}/scheduled-events/{scheduled_event_id}/reject
GET /v1/farm/{farm_id}/scheduled-events/pending/approval

GET /v1/farm/{farm_id}/scheduled-events

Get Scheduled Events

Current scheduled events 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":["APPROVED","COMPLETED","PENDING","REJECTED"]}
start_date	query	No	{"type":"string","format":"date-time"}
end_date	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>/scheduled-events' \
  -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
scheduledEvents	array	Required
scheduledEvents[]	object	Required
scheduledEvents[].status	string	Required	enum: ["COMPLETED","PENDING","APPROVED","REJECTED"]
scheduledEvents[].type	string	Required	enum: ["OTHER","FEED","GENETIC","HEALTH","MOVEMENT"]
scheduledEvents[].id	string	Required
scheduledEvents[].created_at	string	Required	format: "date-time"
scheduledEvents[].updated_at	string	Required	format: "date-time"
scheduledEvents[].name	string	Required
scheduledEvents[].is_active	boolean	Required
scheduledEvents[].farm_id	string	Required
scheduledEvents[].description (variant 1)	null	Required
scheduledEvents[].description (variant 2)	string	Required
scheduledEvents[].record_id (variant 1)	null	Required
scheduledEvents[].record_id (variant 2)	string	Required
scheduledEvents[].approved_by_user_id (variant 1)	null	Required
scheduledEvents[].approved_by_user_id (variant 2)	string	Required
scheduledEvents[].recurring_event_id (variant 1)	null	Required
scheduledEvents[].recurring_event_id (variant 2)	string	Required
scheduledEvents[].animal_ids	JSON	Required
scheduledEvents[].approved_at (variant 1)	null	Required
scheduledEvents[].approved_at (variant 2)	string	Required	format: "date-time"
scheduledEvents[].group_ids	JSON	Required
scheduledEvents[].scheduled_at	string	Required	format: "date-time"
total	number	Required

json example

{
  "scheduledEvents": [],
  "total": 1
}

POST /v1/farm/{farm_id}/scheduled-events

Create Scheduled Event

Current scheduled events 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"}

Request body (application/json)

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

json example

{
  "animal_ids": [],
  "group_ids": [],
  "name": "Example",
  "scheduled_at": "2026-09-01T12:00:00.000Z",
  "type": "FEED"
}

Request example

bash example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/scheduled-events' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"animal_ids":[],"group_ids":[],"name":"Example","scheduled_at":"2026-09-01T12:00:00.000Z","type":"FEED"}'

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
status	string	Required	enum: ["COMPLETED","PENDING","APPROVED","REJECTED"]
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
farm_id	string	Required
description (variant 1)	null	Required
description (variant 2)	string	Required
record_id (variant 1)	null	Required
record_id (variant 2)	string	Required
approved_by_user_id (variant 1)	null	Required
approved_by_user_id (variant 2)	string	Required
recurring_event_id (variant 1)	null	Required
recurring_event_id (variant 2)	string	Required
animal_ids	JSON	Required
approved_at (variant 1)	null	Required
approved_at (variant 2)	string	Required	format: "date-time"
group_ids	JSON	Required
scheduled_at	string	Required	format: "date-time"

json example

{
  "status": "COMPLETED",
  "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,
  "farm_id": "11111111-1111-4111-8111-111111111111",
  "description": null,
  "record_id": null,
  "approved_by_user_id": null,
  "recurring_event_id": null,
  "animal_ids": null,
  "approved_at": null,
  "group_ids": null,
  "scheduled_at": "2026-09-01T12:00:00.000Z"
}

GET /v1/farm/{farm_id}/scheduled-events/{scheduled_event_id}

Get Scheduled Event

Current scheduled events 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"}
scheduled_event_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>/scheduled-events/<scheduled_event_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: ["COMPLETED","PENDING","APPROVED","REJECTED"]
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
farm_id	string	Required
description (variant 1)	null	Required
description (variant 2)	string	Required
record_id (variant 1)	null	Required
record_id (variant 2)	string	Required
approved_by_user_id (variant 1)	null	Required
approved_by_user_id (variant 2)	string	Required
recurring_event_id (variant 1)	null	Required
recurring_event_id (variant 2)	string	Required
animal_ids	JSON	Required
approved_at (variant 1)	null	Required
approved_at (variant 2)	string	Required	format: "date-time"
group_ids	JSON	Required
scheduled_at	string	Required	format: "date-time"

json example

{
  "status": "COMPLETED",
  "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,
  "farm_id": "11111111-1111-4111-8111-111111111111",
  "description": null,
  "record_id": null,
  "approved_by_user_id": null,
  "recurring_event_id": null,
  "animal_ids": null,
  "approved_at": null,
  "group_ids": null,
  "scheduled_at": "2026-09-01T12:00:00.000Z"
}

POST /v1/farm/{farm_id}/scheduled-events/{scheduled_event_id}/approve

Approve Scheduled Event

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
scheduled_event_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>/scheduled-events/<scheduled_event_id>/approve' \
  -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
record	object	Required
record.type	string	Required	enum: ["OTHER","FEED","GENETIC","HEALTH","MOVEMENT"]
record.id	string	Required
record.created_at	string	Required	format: "date-time"
record.updated_at	string	Required	format: "date-time"
record.name	string	Required
record.is_active	boolean	Required
record.description (variant 1)	null	Required
record.description (variant 2)	string	Required
record.applied_at	string	Required	format: "date-time"
scheduledEvent	object	Required
scheduledEvent.status	string	Required	enum: ["COMPLETED","PENDING","APPROVED","REJECTED"]
scheduledEvent.type	string	Required	enum: ["OTHER","FEED","GENETIC","HEALTH","MOVEMENT"]
scheduledEvent.id	string	Required
scheduledEvent.created_at	string	Required	format: "date-time"
scheduledEvent.updated_at	string	Required	format: "date-time"
scheduledEvent.name	string	Required
scheduledEvent.is_active	boolean	Required
scheduledEvent.farm_id	string	Required
scheduledEvent.description (variant 1)	null	Required
scheduledEvent.description (variant 2)	string	Required
scheduledEvent.record_id (variant 1)	null	Required
scheduledEvent.record_id (variant 2)	string	Required
scheduledEvent.approved_by_user_id (variant 1)	null	Required
scheduledEvent.approved_by_user_id (variant 2)	string	Required
scheduledEvent.recurring_event_id (variant 1)	null	Required
scheduledEvent.recurring_event_id (variant 2)	string	Required
scheduledEvent.animal_ids	JSON	Required
scheduledEvent.approved_at (variant 1)	null	Required
scheduledEvent.approved_at (variant 2)	string	Required	format: "date-time"
scheduledEvent.group_ids	JSON	Required
scheduledEvent.scheduled_at	string	Required	format: "date-time"

json example

{
  "record": {
    "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"
  },
  "scheduledEvent": {
    "status": "COMPLETED",
    "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,
    "farm_id": "11111111-1111-4111-8111-111111111111",
    "description": null,
    "record_id": null,
    "approved_by_user_id": null,
    "recurring_event_id": null,
    "animal_ids": null,
    "approved_at": null,
    "group_ids": null,
    "scheduled_at": "2026-09-01T12:00:00.000Z"
  }
}

POST /v1/farm/{farm_id}/scheduled-events/{scheduled_event_id}/reject

Reject Scheduled Event

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
scheduled_event_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>/scheduled-events/<scheduled_event_id>/reject' \
  -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
scheduledEvent	object	Required
scheduledEvent.status	string	Required	enum: ["COMPLETED","PENDING","APPROVED","REJECTED"]
scheduledEvent.type	string	Required	enum: ["OTHER","FEED","GENETIC","HEALTH","MOVEMENT"]
scheduledEvent.id	string	Required
scheduledEvent.created_at	string	Required	format: "date-time"
scheduledEvent.updated_at	string	Required	format: "date-time"
scheduledEvent.name	string	Required
scheduledEvent.is_active	boolean	Required
scheduledEvent.farm_id	string	Required
scheduledEvent.description (variant 1)	null	Required
scheduledEvent.description (variant 2)	string	Required
scheduledEvent.record_id (variant 1)	null	Required
scheduledEvent.record_id (variant 2)	string	Required
scheduledEvent.approved_by_user_id (variant 1)	null	Required
scheduledEvent.approved_by_user_id (variant 2)	string	Required
scheduledEvent.recurring_event_id (variant 1)	null	Required
scheduledEvent.recurring_event_id (variant 2)	string	Required
scheduledEvent.animal_ids	JSON	Required
scheduledEvent.approved_at (variant 1)	null	Required
scheduledEvent.approved_at (variant 2)	string	Required	format: "date-time"
scheduledEvent.group_ids	JSON	Required
scheduledEvent.scheduled_at	string	Required	format: "date-time"

json example

{
  "scheduledEvent": {
    "status": "COMPLETED",
    "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,
    "farm_id": "11111111-1111-4111-8111-111111111111",
    "description": null,
    "record_id": null,
    "approved_by_user_id": null,
    "recurring_event_id": null,
    "animal_ids": null,
    "approved_at": null,
    "group_ids": null,
    "scheduled_at": "2026-09-01T12:00:00.000Z"
  }
}

GET /v1/farm/{farm_id}/scheduled-events/pending/approval

Get Pending Events For Approval

Parameter	In	Required	Schema
farm_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>/scheduled-events/pending/approval' \
  -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
[]	object	Required
[].status	string	Required	enum: ["COMPLETED","PENDING","APPROVED","REJECTED"]
[].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
[].farm_id	string	Required
[].description (variant 1)	null	Required
[].description (variant 2)	string	Required
[].record_id (variant 1)	null	Required
[].record_id (variant 2)	string	Required
[].approved_by_user_id (variant 1)	null	Required
[].approved_by_user_id (variant 2)	string	Required
[].recurring_event_id (variant 1)	null	Required
[].recurring_event_id (variant 2)	string	Required
[].animal_ids	JSON	Required
[].approved_at (variant 1)	null	Required
[].approved_at (variant 2)	string	Required	format: "date-time"
[].group_ids	JSON	Required
[].scheduled_at	string	Required	format: "date-time"

json example

[]

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