Groups API

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

GET /v1/farm/{farm_id}/groups
POST /v1/farm/{farm_id}/groups
DELETE /v1/farm/{farm_id}/groups/{group_id}
GET /v1/farm/{farm_id}/groups/{group_id}
PUT /v1/farm/{farm_id}/groups/{group_id}
POST /v1/farm/{farm_id}/groups/{group_id}/restore
POST /v1/farm/{farm_id}/groups/{group_id}/membership

GET /v1/farm/{farm_id}/groups

Get Groups

Current groups HTTP operation. External credential scopes: read:groups. 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 device account, 1000 per browser session, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429. archived uses JavaScript boolean coercion: any nonempty query string, including false, is true. Omit this parameter for active groups.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
skip	query	No	{"type":"integer"}
take	query	No	{"type":"integer"}
archived	query	No	{"type":"boolean","default":false}

Request example

bash example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/groups' \
  -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[].description (variant 1)	null	Required
records[].description (variant 2)	string	Required
records[].animals	array	Required
records[].animals[]	object	Required
records[].animals[].id (variant 1)	string	Required
records[].animals[].id (variant 2)	null	Required
records[].animals[].farm_id (variant 1)	string	Required
records[].animals[].farm_id (variant 2)	null	Required
records[].animals[].is_active (variant 1)	boolean	Required
records[].animals[].is_active (variant 2)	null	Required
records[].animals[].metadata (variant 1)	JSON	Required
records[].animals[].metadata (variant 2)	null	Required
records[].animals[].created_at (variant 1)	string	Required	format: "date-time"
records[].animals[].created_at (variant 2)	null	Required
records[].animals[].updated_at (variant 1)	string	Required	format: "date-time"
records[].animals[].updated_at (variant 2)	null	Required
records[].animals[].inventory_status	string	Required	enum: ["CURRENT","UNKNOWN","SOLD","DECEASED","NOT_MANAGED"]
records[].membership_fingerprint	string	Required

json example

{
  "total": 0,
  "records": []
}

POST /v1/farm/{farm_id}/groups

Create Group

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

Request body (application/json)

Field	Type	Presence	Constraints
name	string	Required
description	string	Optional

json example

{
  "name": "Example"
}

Request example

bash example

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

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
description (variant 1)	null	Required
description (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",
  "name": "Example",
  "is_active": true,
  "farm_id": "11111111-1111-4111-8111-111111111111",
  "description": null
}

DELETE /v1/farm/{farm_id}/groups/{group_id}

Delete Group

Current groups HTTP operation. External credential scopes: write:groups. Minimum farm role: OWNER. Direct requests execute without an app confirmation screen. Production rate limit: 100 requests per 15-minute window per device account, 1000 per browser session, 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"}
group_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>/groups/<group_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}/groups/{group_id}

Get Group

Current groups HTTP operation. External credential scopes: read:groups. Minimum farm role: READER. Production rate limit: 100 requests per 15-minute window per device account, 1000 per browser session, 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"}
group_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>/groups/<group_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
description (variant 1)	null	Required
description (variant 2)	string	Required
animals	array	Required
animals[]	object	Required
animals[].id (variant 1)	string	Required
animals[].id (variant 2)	null	Required
animals[].farm_id (variant 1)	string	Required
animals[].farm_id (variant 2)	null	Required
animals[].is_active (variant 1)	boolean	Required
animals[].is_active (variant 2)	null	Required
animals[].metadata (variant 1)	JSON	Required
animals[].metadata (variant 2)	null	Required
animals[].created_at (variant 1)	string	Required	format: "date-time"
animals[].created_at (variant 2)	null	Required
animals[].updated_at (variant 1)	string	Required	format: "date-time"
animals[].updated_at (variant 2)	null	Required
animals[].inventory_status	string	Required	enum: ["CURRENT","UNKNOWN","SOLD","DECEASED","NOT_MANAGED"]
membership_fingerprint	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",
  "name": "Example",
  "is_active": true,
  "farm_id": "11111111-1111-4111-8111-111111111111",
  "description": null,
  "animals": [],
  "membership_fingerprint": "0000000000000000000000000000000000000000000000000000000000000000"
}

PUT /v1/farm/{farm_id}/groups/{group_id}

Update Group

Current groups HTTP operation. External credential scopes: write:groups. Minimum farm role: EDITOR. Direct requests execute without an app confirmation screen. Production rate limit: 100 requests per 15-minute window per device account, 1000 per browser session, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429. Update the group name/description and/or add animals. animal_ids is additive: it connects the listed animals and never removes existing members. Omit animal_ids (or send []) to leave membership unchanged. Every requested animal must be an active animal on this farm; any unknown, archived or other-farm animal rejects the whole request. A request with a nonempty animal_ids cannot be undone.

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

Request body (application/json)

Field	Type	Presence	Constraints
name	string	Optional
description	string	Optional
animal_ids	array	Optional
animal_ids[]	string	Required	format: "uuid"

json example

{
  "name": "Replacement ewes",
  "animal_ids": [
    "22222222-2222-4222-8222-222222222222"
  ]
}

Request example

bash example

curl --fail-with-body -X PUT \
  'https://api.ranch.bot/v1/farm/<farm_id>/groups/<group_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Replacement ewes","animal_ids":["22222222-2222-4222-8222-222222222222"]}'

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
description (variant 1)	null	Required
description (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",
  "name": "Example",
  "is_active": true,
  "farm_id": "11111111-1111-4111-8111-111111111111",
  "description": null
}

POST /v1/farm/{farm_id}/groups/{group_id}/restore

Restore Group

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
group_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>/groups/<group_id>/restore' \
  -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
description (variant 1)	null	Required
description (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",
  "name": "Example",
  "is_active": true,
  "farm_id": "11111111-1111-4111-8111-111111111111",
  "description": null
}

POST /v1/farm/{farm_id}/groups/{group_id}/membership

Update Group Membership

Current groups HTTP operation. External credential scopes: write:groups. Minimum farm role: EDITOR. Explicitly add and remove group members. Pass the membership_fingerprint from a fresh group read; a stale fingerprint is a 409 conflict. add_animal_ids and remove_animal_ids must not overlap, every target must be on this farm, and additions must be active. Already-present additions and already-absent removals are no-ops. Removal unlinks membership only; it changes no animal status, record, count observation or saved birth link, and cannot be undone.

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

Request body (application/json)

Field	Type	Presence	Constraints
add_animal_ids	array	Optional	maxItems: 200
add_animal_ids[]	string	Required	format: "uuid"
remove_animal_ids	array	Optional	maxItems: 200
remove_animal_ids[]	string	Required	format: "uuid"
membership_fingerprint	string	Required

json example

{
  "add_animal_ids": [
    "22222222-2222-4222-8222-222222222222"
  ],
  "remove_animal_ids": [],
  "membership_fingerprint": "0000000000000000000000000000000000000000000000000000000000000000"
}

Request example

bash example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/groups/<group_id>/membership' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"add_animal_ids":["22222222-2222-4222-8222-222222222222"],"remove_animal_ids":[],"membership_fingerprint":"0000000000000000000000000000000000000000000000000000000000000000"}'

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 reviewed membership changed before this request was applied; reread the group.	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
group_id	string	Required	format: "uuid"
added_animal_ids	array	Required
added_animal_ids[]	string	Required	format: "uuid"
removed_animal_ids	array	Required
removed_animal_ids[]	string	Required	format: "uuid"
member_animal_ids	array	Required
member_animal_ids[]	string	Required	format: "uuid"
membership_fingerprint	string	Required
member_count	integer	Required

json example

{
  "group_id": "11111111-1111-4111-8111-111111111111",
  "added_animal_ids": [
    "22222222-2222-4222-8222-222222222222"
  ],
  "removed_animal_ids": [],
  "member_animal_ids": [
    "22222222-2222-4222-8222-222222222222"
  ],
  "membership_fingerprint": "0000000000000000000000000000000000000000000000000000000000000000",
  "member_count": 1
}

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