Animals API
HTTP reference for animals. Read authentication and access before using these operations. All examples use made-up data and placeholder credentials.
- GET /v1/farm/{farm_id}/animals
- POST /v1/farm/{farm_id}/animals
- DELETE /v1/farm/{farm_id}/animals/{animal_id}
- GET /v1/farm/{farm_id}/animals/{animal_id}
- PUT /v1/farm/{farm_id}/animals/{animal_id}
- POST /v1/farm/{farm_id}/animals/find-or-create-by-eid
- GET /v1/farm/{farm_id}/animals/index
GET /v1/farm/{farm_id}/animals
Get Animals
Current animals HTTP operation. External credential scopes: read:animals. 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"} |
Request example
bash example
curl --fail-with-body -X GET \
'https://api.ranch.bot/v1/farm/<farm_id>/animals' \
-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[].is_active | boolean | Required | |
| records[].farm_id | string | Required | |
| records[].metadata | JSON | Required | |
| records[].groups | array | Required | |
| records[].groups[] | object | Required | |
| records[].groups[].id (variant 1) | string | Required | |
| records[].groups[].id (variant 2) | null | Required | |
| records[].groups[].farm_id (variant 1) | string | Required | |
| records[].groups[].farm_id (variant 2) | null | Required | |
| records[].groups[].description (variant 1) | string | Required | |
| records[].groups[].description (variant 2) | null | Required | |
| records[].groups[].is_active (variant 1) | boolean | Required | |
| records[].groups[].is_active (variant 2) | null | Required | |
| records[].groups[].name (variant 1) | string | Required | |
| records[].groups[].name (variant 2) | null | Required | |
| records[].groups[].created_at (variant 1) | string | Required | format: "date-time" |
| records[].groups[].created_at (variant 2) | null | Required | |
| records[].groups[].updated_at (variant 1) | string | Required | format: "date-time" |
| records[].groups[].updated_at (variant 2) | null | Required | |
| records[].animal_identifiers | array | Required | |
| records[].animal_identifiers[] | object | Required | |
| records[].animal_identifiers[].id (variant 1) | string | Required | |
| records[].animal_identifiers[].id (variant 2) | null | Required | |
| records[].animal_identifiers[].animal_id (variant 1) | string | Required | |
| records[].animal_identifiers[].animal_id (variant 2) | null | Required | |
| records[].animal_identifiers[].is_active (variant 1) | boolean | Required | |
| records[].animal_identifiers[].is_active (variant 2) | null | Required | |
| records[].animal_identifiers[].is_primary (variant 1) | boolean | Required | |
| records[].animal_identifiers[].is_primary (variant 2) | null | Required | |
| records[].animal_identifiers[].type (variant 1) | string | Required | |
| records[].animal_identifiers[].type (variant 2) | null | Required | |
| records[].animal_identifiers[].value (variant 1) | string | Required | |
| records[].animal_identifiers[].value (variant 2) | null | Required | |
| records[].animal_identifiers[].created_at (variant 1) | string | Required | format: "date-time" |
| records[].animal_identifiers[].created_at (variant 2) | null | Required | |
| records[].animal_identifiers[].updated_at (variant 1) | string | Required | format: "date-time" |
| records[].animal_identifiers[].updated_at (variant 2) | null | Required |
json example
{
"total": 0,
"records": []
}POST /v1/farm/{farm_id}/animals
Create Animal
Current animals HTTP operation. External credential scopes: write:animals. 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 |
|---|---|---|---|
| metadata | JSON | Optional |
json example
{}Request example
bash example
curl --fail-with-body -X POST \
'https://api.ranch.bot/v1/farm/<farm_id>/animals' \
-H "Authorization: Bearer $RANCHBOT_TOKEN" \
-H "Content-Type: application/json" \
--data '{}'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 | |
| farm_id | string | Required | |
| metadata | JSON | 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,
"farm_id": "11111111-1111-4111-8111-111111111111",
"metadata": null
}DELETE /v1/farm/{farm_id}/animals/{animal_id}
Delete Animal
Current animals HTTP operation. External credential scopes: write:animals. Minimum farm role: OWNER. 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"} |
| animal_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>/animals/<animal_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}/animals/{animal_id}
Get Animal
Current animals HTTP operation. External credential scopes: read:animals. 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"} |
| animal_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>/animals/<animal_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" |
| is_active | boolean | Required | |
| farm_id | string | Required | |
| metadata | JSON | Required | |
| groups | array | Required | |
| groups[] | object | Required | |
| groups[].id (variant 1) | string | Required | |
| groups[].id (variant 2) | null | Required | |
| groups[].farm_id (variant 1) | string | Required | |
| groups[].farm_id (variant 2) | null | Required | |
| groups[].description (variant 1) | string | Required | |
| groups[].description (variant 2) | null | Required | |
| groups[].is_active (variant 1) | boolean | Required | |
| groups[].is_active (variant 2) | null | Required | |
| groups[].name (variant 1) | string | Required | |
| groups[].name (variant 2) | null | Required | |
| groups[].created_at (variant 1) | string | Required | format: "date-time" |
| groups[].created_at (variant 2) | null | Required | |
| groups[].updated_at (variant 1) | string | Required | format: "date-time" |
| groups[].updated_at (variant 2) | null | Required | |
| animal_identifiers | array | Required | |
| animal_identifiers[] | object | Required | |
| animal_identifiers[].id (variant 1) | string | Required | |
| animal_identifiers[].id (variant 2) | null | Required | |
| animal_identifiers[].animal_id (variant 1) | string | Required | |
| animal_identifiers[].animal_id (variant 2) | null | Required | |
| animal_identifiers[].is_active (variant 1) | boolean | Required | |
| animal_identifiers[].is_active (variant 2) | null | Required | |
| animal_identifiers[].is_primary (variant 1) | boolean | Required | |
| animal_identifiers[].is_primary (variant 2) | null | Required | |
| animal_identifiers[].type (variant 1) | string | Required | |
| animal_identifiers[].type (variant 2) | null | Required | |
| animal_identifiers[].value (variant 1) | string | Required | |
| animal_identifiers[].value (variant 2) | null | Required | |
| animal_identifiers[].created_at (variant 1) | string | Required | format: "date-time" |
| animal_identifiers[].created_at (variant 2) | null | Required | |
| animal_identifiers[].updated_at (variant 1) | string | Required | format: "date-time" |
| animal_identifiers[].updated_at (variant 2) | null | Required | |
| records | array | Required | |
| records[] | object | Required | |
| records[].id (variant 1) | string | Required | |
| records[].id (variant 2) | null | Required | |
| records[].applied_at (variant 1) | string | Required | format: "date-time" |
| records[].applied_at (variant 2) | null | Required | |
| records[].description (variant 1) | string | Required | |
| records[].description (variant 2) | null | Required | |
| records[].is_active (variant 1) | boolean | Required | |
| records[].is_active (variant 2) | null | Required | |
| records[].name (variant 1) | string | Required | |
| records[].name (variant 2) | null | Required | |
| records[].type (variant 1) | string | Required | |
| records[].type (variant 2) | null | Required | |
| records[].created_at (variant 1) | string | Required | format: "date-time" |
| records[].created_at (variant 2) | null | Required | |
| records[].updated_at (variant 1) | string | Required | format: "date-time" |
| records[].updated_at (variant 2) | null | Required | |
| records[].record_items | array | Required | |
| records[].record_items[] | object | Required | |
| records[].record_items[].id (variant 1) | string | Required | |
| records[].record_items[].id (variant 2) | null | Required | |
| records[].record_items[].description (variant 1) | string | Required | |
| records[].record_items[].description (variant 2) | null | Required | |
| records[].record_items[].is_active (variant 1) | boolean | Required | |
| records[].record_items[].is_active (variant 2) | null | Required | |
| records[].record_items[].metadata (variant 1) | JSON | Required | |
| records[].record_items[].metadata (variant 2) | null | Required | |
| records[].record_items[].name (variant 1) | string | Required | |
| records[].record_items[].name (variant 2) | null | Required | |
| records[].record_items[].created_at (variant 1) | string | Required | format: "date-time" |
| records[].record_items[].created_at (variant 2) | null | Required | |
| records[].record_items[].updated_at (variant 1) | string | Required | format: "date-time" |
| records[].record_items[].updated_at (variant 2) | null | Required | |
| files | array | Required | |
| files[] | object | Required | |
| files[].id (variant 1) | string | Required | |
| files[].id (variant 2) | null | Required | |
| files[].is_active (variant 1) | boolean | Required | |
| files[].is_active (variant 2) | null | Required | |
| files[].mime_type (variant 1) | string | Required | |
| files[].mime_type (variant 2) | null | Required | |
| files[].name (variant 1) | string | Required | |
| files[].name (variant 2) | null | Required | |
| files[].size (variant 1) | integer | Required | |
| files[].size (variant 2) | null | Required | |
| files[].url (variant 1) | string | Required | |
| files[].url (variant 2) | null | Required | |
| files[].created_at (variant 1) | string | Required | format: "date-time" |
| files[].created_at (variant 2) | null | Required | |
| files[].updated_at (variant 1) | string | Required | format: "date-time" |
| files[].updated_at (variant 2) | null | 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,
"farm_id": "11111111-1111-4111-8111-111111111111",
"metadata": null,
"groups": [],
"animal_identifiers": [],
"records": [],
"files": []
}PUT /v1/farm/{farm_id}/animals/{animal_id}
Update Animal
Current animals HTTP operation. External credential scopes: write:animals. 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"} |
| animal_id | path | Yes | {"type":"string","format":"uuid"} |
Request body (application/json)
| Field | Type | Presence | Constraints |
|---|---|---|---|
| metadata | JSON | Optional |
json example
{}Request example
bash example
curl --fail-with-body -X PUT \
'https://api.ranch.bot/v1/farm/<farm_id>/animals/<animal_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 | |
| farm_id | string | Required | |
| metadata | JSON | 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,
"farm_id": "11111111-1111-4111-8111-111111111111",
"metadata": null
}POST /v1/farm/{farm_id}/animals/find-or-create-by-eid
Find Or Create Animal By Eid
Current animals HTTP operation. External credential scopes: write:animals. 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 |
|---|---|---|---|
| eid | string | Required |
json example
{
"eid": "example"
}Request example
bash example
curl --fail-with-body -X POST \
'https://api.ranch.bot/v1/farm/<farm_id>/animals/find-or-create-by-eid' \
-H "Authorization: Bearer $RANCHBOT_TOKEN" \
-H "Content-Type: application/json" \
--data '{"eid":"example"}'Responses
| Status | Meaning | Content type |
|---|---|---|
| 200 | Existing match returned. | application/json |
| 201 | New animal created. | 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 |
|---|---|---|---|
| animal | object | Required | |
| animal.id | string | Required | |
| animal.created_at | string | Required | format: "date-time" |
| animal.updated_at | string | Required | format: "date-time" |
| animal.is_active | boolean | Required | |
| animal.farm_id | string | Required | |
| animal.metadata | JSON | Required | |
| animal.groups | array | Required | |
| animal.groups[] | object | Required | |
| animal.groups[].id (variant 1) | string | Required | |
| animal.groups[].id (variant 2) | null | Required | |
| animal.groups[].farm_id (variant 1) | string | Required | |
| animal.groups[].farm_id (variant 2) | null | Required | |
| animal.groups[].description (variant 1) | string | Required | |
| animal.groups[].description (variant 2) | null | Required | |
| animal.groups[].is_active (variant 1) | boolean | Required | |
| animal.groups[].is_active (variant 2) | null | Required | |
| animal.groups[].name (variant 1) | string | Required | |
| animal.groups[].name (variant 2) | null | Required | |
| animal.groups[].created_at (variant 1) | string | Required | format: "date-time" |
| animal.groups[].created_at (variant 2) | null | Required | |
| animal.groups[].updated_at (variant 1) | string | Required | format: "date-time" |
| animal.groups[].updated_at (variant 2) | null | Required | |
| animal.animal_identifiers | array | Required | |
| animal.animal_identifiers[] | object | Required | |
| animal.animal_identifiers[].id (variant 1) | string | Required | |
| animal.animal_identifiers[].id (variant 2) | null | Required | |
| animal.animal_identifiers[].animal_id (variant 1) | string | Required | |
| animal.animal_identifiers[].animal_id (variant 2) | null | Required | |
| animal.animal_identifiers[].is_active (variant 1) | boolean | Required | |
| animal.animal_identifiers[].is_active (variant 2) | null | Required | |
| animal.animal_identifiers[].is_primary (variant 1) | boolean | Required | |
| animal.animal_identifiers[].is_primary (variant 2) | null | Required | |
| animal.animal_identifiers[].type (variant 1) | string | Required | |
| animal.animal_identifiers[].type (variant 2) | null | Required | |
| animal.animal_identifiers[].value (variant 1) | string | Required | |
| animal.animal_identifiers[].value (variant 2) | null | Required | |
| animal.animal_identifiers[].created_at (variant 1) | string | Required | format: "date-time" |
| animal.animal_identifiers[].created_at (variant 2) | null | Required | |
| animal.animal_identifiers[].updated_at (variant 1) | string | Required | format: "date-time" |
| animal.animal_identifiers[].updated_at (variant 2) | null | Required | |
| created | boolean | Required |
json example
{
"animal": {
"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",
"metadata": null,
"groups": [],
"animal_identifiers": []
},
"created": true
}201 response schema (application/json)
| Field | Type | Presence | Constraints |
|---|---|---|---|
| animal | object | Required | |
| animal.id | string | Required | |
| animal.created_at | string | Required | format: "date-time" |
| animal.updated_at | string | Required | format: "date-time" |
| animal.is_active | boolean | Required | |
| animal.farm_id | string | Required | |
| animal.metadata | JSON | Required | |
| animal.groups | array | Required | |
| animal.groups[] | object | Required | |
| animal.groups[].id (variant 1) | string | Required | |
| animal.groups[].id (variant 2) | null | Required | |
| animal.groups[].farm_id (variant 1) | string | Required | |
| animal.groups[].farm_id (variant 2) | null | Required | |
| animal.groups[].description (variant 1) | string | Required | |
| animal.groups[].description (variant 2) | null | Required | |
| animal.groups[].is_active (variant 1) | boolean | Required | |
| animal.groups[].is_active (variant 2) | null | Required | |
| animal.groups[].name (variant 1) | string | Required | |
| animal.groups[].name (variant 2) | null | Required | |
| animal.groups[].created_at (variant 1) | string | Required | format: "date-time" |
| animal.groups[].created_at (variant 2) | null | Required | |
| animal.groups[].updated_at (variant 1) | string | Required | format: "date-time" |
| animal.groups[].updated_at (variant 2) | null | Required | |
| animal.animal_identifiers | array | Required | |
| animal.animal_identifiers[] | object | Required | |
| animal.animal_identifiers[].id (variant 1) | string | Required | |
| animal.animal_identifiers[].id (variant 2) | null | Required | |
| animal.animal_identifiers[].animal_id (variant 1) | string | Required | |
| animal.animal_identifiers[].animal_id (variant 2) | null | Required | |
| animal.animal_identifiers[].is_active (variant 1) | boolean | Required | |
| animal.animal_identifiers[].is_active (variant 2) | null | Required | |
| animal.animal_identifiers[].is_primary (variant 1) | boolean | Required | |
| animal.animal_identifiers[].is_primary (variant 2) | null | Required | |
| animal.animal_identifiers[].type (variant 1) | string | Required | |
| animal.animal_identifiers[].type (variant 2) | null | Required | |
| animal.animal_identifiers[].value (variant 1) | string | Required | |
| animal.animal_identifiers[].value (variant 2) | null | Required | |
| animal.animal_identifiers[].created_at (variant 1) | string | Required | format: "date-time" |
| animal.animal_identifiers[].created_at (variant 2) | null | Required | |
| animal.animal_identifiers[].updated_at (variant 1) | string | Required | format: "date-time" |
| animal.animal_identifiers[].updated_at (variant 2) | null | Required | |
| created | boolean | Required |
json example
{
"animal": {
"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",
"metadata": null,
"groups": [],
"animal_identifiers": []
},
"created": true
}GET /v1/farm/{farm_id}/animals/index
Get Animals Index
Current animals HTTP operation. External credential scopes: read:animals. 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"} |
Request example
bash example
curl --fail-with-body -X GET \
'https://api.ranch.bot/v1/farm/<farm_id>/animals/index' \
-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 |
|---|---|---|---|
| synced_at | string | Required | |
| total | number | Required | |
| animals | array | Required | |
| animals[] | object | Required | |
| animals[].id | string | Required | |
| animals[].metadata | JSON | Required | |
| animals[].identifiers | array | Required | |
| animals[].identifiers[] | object | Required | |
| animals[].identifiers[].type | string | Required | enum: ["BRAND","EID","MANAGEMENT_TAG","NAME","TATTOO"] |
| animals[].identifiers[].value | string | Required | |
| animals[].identifiers[].is_primary | boolean | Required | |
| animals[].last_weights | array | Required | |
| animals[].last_weights[] | object | Required | |
| animals[].last_weights[].value | number | Required | |
| animals[].last_weights[].unit (variant 1) | null | Required | |
| animals[].last_weights[].unit (variant 2) | string | Required | |
| animals[].last_weights[].applied_at | string | Required | format: "date-time" |
json example
{
"synced_at": "2026-09-01T12:00:00.000Z",
"total": 1,
"animals": []
}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"
}
]
}