Animal identifiers API

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

• GET /v1/farm/{farm_id}/animals/{animal_id}/identifier
• POST /v1/farm/{farm_id}/animals/{animal_id}/identifier
• DELETE /v1/farm/{farm_id}/animals/{animal_id}/identifier/{animal_identifier_id}
• GET /v1/farm/{farm_id}/animals/{animal_id}/identifier/{animal_identifier_id}
• PUT /v1/farm/{farm_id}/animals/{animal_id}/identifier/{animal_identifier_id}

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

Get Animal Identifiers

Current animal identifiers 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.

Request example

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

Responses

200 response schema (application/json)

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

POST /v1/farm/{farm_id}/animals/{animal_id}/identifier

Create Animal Identifier

Current animal identifiers 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.

Request body (application/json)

{
  "type": "BRAND",
  "value": "EXAMPLE-001"
}

Request example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/animals/<animal_id>/identifier' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"type":"BRAND","value":"EXAMPLE-001"}'

Responses

201 response schema (application/json)

{
  "value": "EXAMPLE-001",
  "type": "BRAND",
  "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,
  "animal_id": "11111111-1111-4111-8111-111111111111",
  "is_primary": true
}

DELETE /v1/farm/{farm_id}/animals/{animal_id}/identifier/{animal_identifier_id}

Delete Animal Identifier

Current animal identifiers 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).

Request example

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

Responses

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

Get Animal Identifier

Current animal identifiers 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. Current legacy behavior: returns the active parent animal, not an identifier. The identifier id is not used by this handler. Use the identifier collection to retrieve identifiers.

Request example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/animals/<animal_id>/identifier/<animal_identifier_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
}

PUT /v1/farm/{farm_id}/animals/{animal_id}/identifier/{animal_identifier_id}

Update Animal Identifier

Current animal identifiers 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.

Request body (application/json)

{}

Request example

curl --fail-with-body -X PUT \
  'https://api.ranch.bot/v1/farm/<farm_id>/animals/<animal_id>/identifier/<animal_identifier_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'

Responses

200 response schema (application/json)

{
  "value": "EXAMPLE-001",
  "type": "BRAND",
  "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,
  "animal_id": "11111111-1111-4111-8111-111111111111",
  "is_primary": true
}

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