Birth events API

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

• POST /v1/farm/{farm_id}/birth-events/preview
• POST /v1/farm/{farm_id}/birth-events
• GET /v1/farm/{farm_id}/birth-events
• GET /v1/farm/{farm_id}/birth-events/{event_id}

POST /v1/farm/{farm_id}/birth-events/preview

Preview a birth event

Validate without saving farm data. Display the entire returned bundle and resolved review. Obtain explicit producer approval of this exact preview before confirmation. A read-only device session cannot call POST; an EDITOR device session needs read:records and a write scope. External credential scopes: read:records. Minimum farm role: EDITOR.

Request body (application/json)

Create request.json with a JSON body matching the request schema above before running this example.

Request example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/birth-events/preview' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

Responses

200 response schema (application/json)

POST /v1/farm/{farm_id}/birth-events

Confirm a reviewed birth event

Save all reviewed animals, observations, relationships, care records, tasks and evidence in one transaction. Submit only request_id, bundle and confirmation_hash from the approved preview. Reusing the exact request is idempotent. A changed hash or reused request ID with different data returns 409; obtain approval of a fresh preview after corrections or changed farm evidence. External credential scopes: write:records, write:animals, write:groups. Minimum farm role: EDITOR.

Request body (application/json)

Create request.json with a JSON body matching the request schema above before running this example.

Request example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/birth-events' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

Responses

201 response schema (application/json)

GET /v1/farm/{farm_id}/birth-events

List birth events

List saved births with pagination, optionally filtered by dam or offspring animal_id. External credential scopes: read:records. Minimum farm role: READER.

Request example

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

Responses

200 response schema (application/json)

GET /v1/farm/{farm_id}/birth-events/{event_id}

Get a birth event

Retrieve a saved birth and its accessible evidence from the current farm. External credential scopes: read:records. Minimum farm role: READER.

Request example

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

Responses

200 response schema (application/json)

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