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/lookup-by-eid

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 device account, 1000 per browser session, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429. Defaults to CURRENT inventory. Use inventory_status=ALL to include all nondeleted historical profiles, or select UNKNOWN, SOLD, DECEASED, or NOT_MANAGED. With a nonblank query, searches active saved identifiers and the canonical current profile name (metadata.name). Exact is case-sensitive full-value equality; partial is a literal case-insensitive substring over profile names, NAME and MANAGEMENT_TAG identifiers. Defaults to inventory_status=ALL and skip 0 / take 50 (max 200) while searching.

Request example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/animals' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

200 response schema (application/json)

{
  "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 device account, 1000 per browser session, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429. inventory_status is separate from deletion: CURRENT, UNKNOWN, SOLD, DECEASED, or NOT_MANAGED. New animals default to CURRENT; use UNKNOWN when present inventory membership is unconfirmed. Status changes preserve profile history and identifiers.

Request body (application/json)

{}

Request 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

201 response schema (application/json)

{
  "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,
  "inventory_status": "CURRENT"
}

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 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).

Request example

curl --fail-with-body -X DELETE \
  'https://api.ranch.bot/v1/farm/<farm_id>/animals/<animal_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

GET /v1/farm/{farm_id}/animals/{animal_id}

Get Animal

Current animals HTTP operation. External credential scopes: read:animals; include_saved_births additionally requires read:records. 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.

Request example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/animals/<animal_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

200 response schema (application/json)

{
  "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": [],
  "inventory_status": "CURRENT"
}

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 device account, 1000 per browser session, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429. inventory_status is separate from deletion: CURRENT, UNKNOWN, SOLD, DECEASED, or NOT_MANAGED. New animals default to CURRENT; use UNKNOWN when present inventory membership is unconfirmed. Status changes preserve profile history and identifiers.

Request body (application/json)

{}

Request 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

200 response schema (application/json)

{
  "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,
  "inventory_status": "CURRENT"
}

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 device account, 1000 per browser session, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429.

Request body (application/json)

{
  "eid": "example"
}

Request 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

200 response schema (application/json)

{
  "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": [],
    "inventory_status": "CURRENT"
  },
  "created": true
}

201 response schema (application/json)

{
  "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": [],
    "inventory_status": "CURRENT"
  },
  "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 device account, 1000 per browser session, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429. Defaults to CURRENT inventory. Use inventory_status=ALL to include all nondeleted historical profiles, or select UNKNOWN, SOLD, DECEASED, or NOT_MANAGED.

Request example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/animals/index' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

200 response schema (application/json)

{
  "synced_at": "2026-09-01T12:00:00.000Z",
  "total": 1,
  "animals": []
}

GET /v1/farm/{farm_id}/animals/lookup-by-eid

Look up an animal by exact EID without writing

Read-only exact EID lookup across inventory statuses. Never creates or updates inventory. Missing matches return 404; multiple matching animals return 409. Current animals HTTP operation. External credential scopes: read:animals. 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.

Request example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/animals/lookup-by-eid?eid=PLACEHOLDER_EID' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

200 response schema (application/json)

{
  "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": [],
  "inventory_status": "CURRENT"
}

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.

{
  "success": false,
  "errors": [
    {
      "code": 400,
      "name": "ValidationError",
      "message": "Example validation failure"
    }
  ]
}