---
title: "Preview a birth event"
method: POST
path: "/v1/farm/{farm_id}/birth-events/preview"
tags: ["birth-events"]
---

# Preview a birth event

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

## Request

- Base URL: `https://api.ranch.bot`
- URL: `https://api.ranch.bot/v1/farm/{farm_id}/birth-events/preview`
- Auth: HTTP bearer

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.

## Path parameters

- `farm_id` string, uuid, required

## Request body

- BirthRequest
  - `request_id` string, uuid, required
  - `bundle` 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[]

## Response `200`

Success

- BirthPreview
  - `request_id` string, uuid, required
  - `bundle` 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[]
  - `confirmation_hash` string, required
  - `review` object, required: Every resolved dam, group, protocol, evidence detail and unresolved fact must be shown alongside the complete bundle before obtaining producer approval.

## 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.
- `409`: The approved preview is stale, the request ID is already used, or the protocol version has different steps.
- `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)