Records API

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

• GET /v1/farm/{farm_id}/records
• POST /v1/farm/{farm_id}/records
• DELETE /v1/farm/{farm_id}/records/{record_id}
• GET /v1/farm/{farm_id}/records/{record_id}
• PUT /v1/farm/{farm_id}/records/{record_id}

GET /v1/farm/{farm_id}/records

Get Records

Current records 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 device account, 1000 per browser session, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429. An animal_id or group_id target and/or applied_from/applied_before time bound returns filtered history with skip 0 and take 50 by default, up to 200 records per page. The response always lists same-farm animal and group attachment ids in records[].animals and records[].groups; only the current group names in match_context.current_groups and scope.authorized_groups require include_group_context. Scoped credentials: animal_id also needs read:animals, group_id also needs read:groups, and include_group_context needs both.

Request example

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

Responses

200 response schema (application/json)

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

POST /v1/farm/{farm_id}/records

Create Record

Current records HTTP operation. External credential scopes: write:records; a typed traceability payload that carries identification.profile_update additionally requires 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. Legacy creation requires at least one animal_ids or group_ids entry attached to an active entity in this farm. Typed creation supplies traceability and requires an opaque request_key (1-200 characters); it does not require those associations. The 201 response is the created record for legacy creation or a { "event": ... } envelope for typed creation. Associations must name active entities in this farm; the service filters out ids outside that set. Supply ids obtained from the same farm.

Request body (application/json)

{
  "animal_ids": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "group_ids": [],
  "name": "Example observation",
  "type": "OTHER",
  "applied_at": "2026-09-01T12:00:00.000Z"
}

Request example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/records' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"animal_ids":["11111111-1111-4111-8111-111111111111"],"group_ids":[],"name":"Example observation","type":"OTHER","applied_at":"2026-09-01T12:00:00.000Z"}'

Responses

201 response schema (application/json)

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

Legacy record response

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

Typed traceability event response

{
  "event": {
    "id": "44444444-4444-4444-8444-444444444444",
    "kind": "SALE",
    "status": "ACTIVE",
    "current_revision": 1
  }
}

DELETE /v1/farm/{farm_id}/records/{record_id}

Delete Record

Current records HTTP operation. External credential scopes: write:records. 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>/records/<record_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

GET /v1/farm/{farm_id}/records/{record_id}

Get Record

Current records HTTP operation. External credential scopes: 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>/records/<record_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

200 response schema (application/json)

{
  "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",
  "record_items": [],
  "files": [],
  "animals": [],
  "groups": []
}

PUT /v1/farm/{farm_id}/records/{record_id}

Update Record

Current records 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 device account, 1000 per browser session, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429. Provided association ids are connected to the record; they do not replace the entire association set.

Request body (application/json)

{}

Request example

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

Responses

200 response schema (application/json)

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

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