--- title: "List birth events" method: GET path: "/v1/farm/{farm_id}/birth-events" tags: ["birth-events"] --- # List birth events `GET /v1/farm/{farm_id}/birth-events` ## Request - Base URL: `https://api.ranch.bot` - URL: `https://api.ranch.bot/v1/farm/{farm_id}/birth-events` - Auth: HTTP bearer List saved births with pagination, optionally filtered by dam or offspring animal_id. External credential scopes: read:records. Minimum farm role: READER. ## Path parameters - `farm_id` string, uuid, required ## Query parameters - `skip` integer - `take` integer - `animal_id` string, uuid ## Response `200` Success - object - `total` integer, required - `records` BirthEvent[], required - `id` string, uuid, required - `farm_id` string, uuid, required - `request_id` string, uuid, required - `confirmation_hash` string, required - `created_by_user_id` string, uuid, required - `dam_id` string, uuid, required - `birth_date` string, date-time, required - `time_precision` string, nullable, required - `bundle` object, required - `input` BirthBundle, required - `dam_id` string, uuid, required - `birth_date` string, required - `time_precision` 'date_only' | 'morning' | 'afternoon' | 'evening' | 'night' - `total_born` integer: Explicitly reported biological total, including stillborn. Omit when unknown; never derived from offspring entries. - `dam_update` object - `kind` string - `notes` string - `maternal_observations` object[] - `date` string, required - `text` string, required - `lactation_observations` object[] - `date` string, required - `text` string, required - `offspring` object[] - `review_label` string, required: Temporary review label only; never an invented identifier. - `animal_id` string, uuid: Link an existing active farm animal instead of creating a profile. - `sex` 'male' | 'female' | 'unknown': Required when creating a profile; omit when linking an existing animal. - `inventory_status` 'CURRENT' | 'UNKNOWN' | 'SOLD' | 'DECEASED' | 'NOT_MANAGED': Required when creating a profile; omit when linking an existing animal. - `birth_weight` object - `value` number, required - `unit` 'kg' | 'lb', required - `basis` 'measured' | 'estimated' | 'unknown': Weight basis; omission means unknown, never measured. - `vigor` object[] - `date` string, required - `text` string, required - `supplementation` object[] - `date` string, required - `substance` string, required - `amount` number, required - `unit` string, required - `source` string, required: Producer-stated source, e.g. own dam. Never prescribe care. - `sire` object - `status` 'unknown' | 'presumed' | 'confirmed', required - `animal_id` string, uuid - `provenance` string - `confidence` number - `protocol` object - `claimed_name` string, required - `completed_date` string, required - `version_id` string, uuid - `offspring_labels` string[], required - `follow_up` object[] - `name` string, required - `due_date` string - `offspring_labels` string[], required - `group_ids` string[]: Explicitly reviewed current group memberships. Does not record movement. - `current_location` string: Explicitly reviewed current location only; does not create movement history. - `source_sms_id` string, uuid - `source_message_id` string, uuid - `evidence` object[] - `file_id` string, uuid, required - `media_id` string, uuid - `link_to_dam` boolean - `offspring_label` string - `unresolved` string[] - `additional_source_sms_ids` string[] - `review` object, required: The resolved dam, groups, protocol, evidence and unresolved facts reviewed before confirmation. - `record_id` string, uuid, required - `source_sms_id` string, uuid, nullable, required - `source_message_id` string, uuid, nullable, required - `agent_action_id` string, uuid, nullable, required - `created_at` string, date-time, required - `offspring` object[], required - `id` string, uuid, required - `birth_event_id` string, uuid, required - `animal_id` string, uuid, required - `review_label` string, required - `position` integer, required - `details` object, required - `tasks` FarmTask[], required - `id` string, uuid, required - `farm_id` string, uuid, required - `birth_event_id` string, uuid, required - `name` string, required - `status` 'TODO' | 'DONE' | 'CANCELLED', required - `due_date` string, date-time, nullable, required - `created_at` string, date-time, required - `updated_at` string, date-time, required - `animals` object[] - `id` string, uuid, required - `record` object, required - `id` string, uuid, required - `subtype` 'BIRTH' | 'null', nullable - `revision` integer - `is_active` boolean - `type` string - `applied_at` string, date-time - `files` object[], required - `id` string, uuid, required - `name` string, required - `mime_type` string, required - `birth_details` object: Canonical record-first birth facts. birth_date is a derived YYYY-MM-DD projection of record.applied_at; the legacy timestamp remains for compatibility only. - `birth_date` string, date, required - `time_precision` string, nullable, required - `dam_id` string, uuid, required - `total_born` integer, nullable, required: Explicitly reported biological total; null means unknown and is never derived from offspring links. - `subtype` 'BIRTH' | 'null', nullable, required - `revision` integer, required - `lifecycle_status` 'active' | 'entered_in_error', required - `date_source` string, required - `care_records` object[], required - `id` string, uuid, required - `name` string, required - `applied_at` string, date-time, nullable, required - `record_items` object[], required - `sire_animals` object[]: Response-only identities for the selected sire and candidates from access-filtered breeding history, scoped to this farm. Includes inactive sires and active identifiers; never stored in the bundle or approval snapshot. - `id` string, uuid, required - `is_active` boolean, required - `metadata` object, nullable, required - `animal_identifiers` object[], required - `id` string, uuid - `type` string - `value` string - `is_active` boolean - `offspring_inventory` object[]: Response-only current-litter projection built only from active offspring links. Each entry reports live animal state, which is separate from the immutable captured birth facts in `offspring`/`bundle`. Inactive links (unlinked or entered-in-error) remain in historical `offspring` but are absent here; an active link to an archived, sold, deceased, or otherwise inactive animal is still reported with that live status. Animal activity is never used to filter the list. - `animal_id` string, uuid, required - `review_label` string, required - `position` integer, required - `inventory_status` 'CURRENT' | 'UNKNOWN' | 'SOLD' | 'DECEASED' | 'NOT_MANAGED' | 'null', nullable, required: The linked animal's current inventory status; null when the animal relation is unavailable. - `is_active` boolean, nullable, required: The linked animal's live is_active flag, not the link's; null when the animal relation is unavailable. - `linked_records` object[]: Response-only, deduplicated record links. A record linked more than once appears once, keyed by UUID; the primary birth record takes precedence over a care link with the same UUID. - `id` string, uuid, required - `kind` 'primary' | 'care', required - `name` string, nullable - `applied_at` string, date-time, nullable - `file_ids` string[]: Access-filtered file UUIDs for the primary record. - `media_file_ids` string[]: Unique, access-filtered file UUIDs referenced by the accepted birth evidence and the primary record. ## Other responses - `400`: Request validation failed. - `401`: Missing/invalid authentication or insufficient farm role. - `403`: Missing required scope or credential type is disallowed. - `404`: Resource or active farm membership not found. - `429`: Rate limit exceeded. Retry after the indicated delay. - `500`: Unexpected server failure. --- [API](https://skmtc.dev/ranch/apis/ranch-bot-http-api.md) · [All operations](https://skmtc.dev/ranch/apis/ranch-bot-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ranch/apis/ranch-bot-http-api/revisions/24109d33fa02?raw)