Birth history API

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

GET /v1/farm/{farm_id}/birth-history/settings
PUT /v1/farm/{farm_id}/birth-history/settings
GET /v1/farm/{farm_id}/birth-history/evidence

GET /v1/farm/{farm_id}/birth-history/settings

Read producer birth-history settings

Requires read:records. Settings are species-bound and provide no biological defaults.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}

Request example

bash example

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

Responses

Status	Meaning	Content type
200	Farm-scoped birth history	application/json
401	Authentication required	No body
403	Current farm access and required scopes required	No body
404	Farm or animal not found	No body

200 response schema (application/json)

Field	Type	Presence	Constraints
species	string	Required
settings (variant 1)	object	Required
settings (variant 1).version	number	Required	const: 1
settings (variant 1).species	string	Required	enum: ["BISON","CATTLE","ELK","GOAT","HORSE","OTHER","SHEEP"]
settings (variant 1).gestation_days	object	Optional
settings (variant 1).gestation_days.min	integer	Required	minimum: 1; maximum: 2000
settings (variant 1).gestation_days.max	integer	Required	minimum: 1; maximum: 2000
settings (variant 1).minimum_sire_age_days	integer	Optional	minimum: 1; maximum: 10000
settings (variant 1).birth_windows	array	Optional	maxItems: 40; default: []
settings (variant 1).birth_windows[]	object	Required
settings (variant 1).birth_windows[].label	string	Required	minLength: 1; maxLength: 80
settings (variant 1).birth_windows[].start_date	string	Required
settings (variant 1).birth_windows[].end_date	string	Required
settings (variant 2)	null	Required

PUT /v1/farm/{farm_id}/birth-history/settings

Replace producer birth-history settings

Requires write:records and current editor membership. The producer supplies species gestation/age intervals and zero-to-many absolute birth windows. An empty window list means no planned windows. Configuration changes invalidate earlier birth previews.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}

Request body (application/json)

Field	Type	Presence	Constraints
version	number	Required	const: 1
species	string	Required	enum: ["BISON","CATTLE","ELK","GOAT","HORSE","OTHER","SHEEP"]
gestation_days	object	Optional
gestation_days.min	integer	Required	minimum: 1; maximum: 2000
gestation_days.max	integer	Required	minimum: 1; maximum: 2000
minimum_sire_age_days	integer	Optional	minimum: 1; maximum: 10000
birth_windows	array	Optional	maxItems: 40; default: []
birth_windows[]	object	Required
birth_windows[].label	string	Required	minLength: 1; maxLength: 80
birth_windows[].start_date	string	Required
birth_windows[].end_date	string	Required

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

Request example

bash example

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

Responses

Status	Meaning	Content type
200	Farm-scoped birth history	application/json
400	Invalid dates, bounds, or mismatched species	No body
401	Authentication required	No body
403	Current farm access and required scopes required	No body
404	Farm or animal not found	No body

200 response schema (application/json)

Field	Type	Presence	Constraints
species	string	Required
settings (variant 1)	object	Required
settings (variant 1).version	number	Required	const: 1
settings (variant 1).species	string	Required	enum: ["BISON","CATTLE","ELK","GOAT","HORSE","OTHER","SHEEP"]
settings (variant 1).gestation_days	object	Optional
settings (variant 1).gestation_days.min	integer	Required	minimum: 1; maximum: 2000
settings (variant 1).gestation_days.max	integer	Required	minimum: 1; maximum: 2000
settings (variant 1).minimum_sire_age_days	integer	Optional	minimum: 1; maximum: 10000
settings (variant 1).birth_windows	array	Optional	maxItems: 40; default: []
settings (variant 1).birth_windows[]	object	Required
settings (variant 1).birth_windows[].label	string	Required	minLength: 1; maxLength: 80
settings (variant 1).birth_windows[].start_date	string	Required
settings (variant 1).birth_windows[].end_date	string	Required
settings (variant 2)	null	Required

GET /v1/farm/{farm_id}/birth-history/evidence

Review explicit dated birth history

Requires read:records and read:animals. Compares configured windows with dated farm-scoped RecordItem.metadata.birth_history facts. Current group membership is never historical evidence. Missing sex, birth date, intact-at-exposure or age settings remain unknown; a sole plausible exposure may propose a presumed sire with source provenance and a conservative review score, never DNA confidence. No parentage or breeding records are written.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
dam_id	query	Yes	{"type":"string","format":"uuid"}
birth_date	query	Yes	{"type":"string","pattern":"^\d{4}-\d{2}-\d{2}$"}

Request example

bash example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/birth-history/evidence?dam_id=PLACEHOLDER_DAM_ID&birth_date=PLACEHOLDER_BIRTH_DATE' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

Status	Meaning	Content type
200	Farm-scoped birth history	application/json
401	Authentication required	No body
403	Current farm access and required scopes required	No body
404	Farm or animal not found	No body

200 response schema (application/json)

Field	Type	Presence	Constraints
evidence_version	number	Required	const: 1
settings (variant 1)	object	Required
settings (variant 1).version	number	Required	const: 1
settings (variant 1).species	string	Required	enum: ["BISON","CATTLE","ELK","GOAT","HORSE","OTHER","SHEEP"]
settings (variant 1).gestation_days	object	Optional
settings (variant 1).gestation_days.min	integer	Required	minimum: 1; maximum: 2000
settings (variant 1).gestation_days.max	integer	Required	minimum: 1; maximum: 2000
settings (variant 1).minimum_sire_age_days	integer	Optional	minimum: 1; maximum: 10000
settings (variant 1).birth_windows	array	Optional	maxItems: 40; default: []
settings (variant 1).birth_windows[]	object	Required
settings (variant 1).birth_windows[].label	string	Required	minLength: 1; maxLength: 80
settings (variant 1).birth_windows[].start_date	string	Required
settings (variant 1).birth_windows[].end_date	string	Required
settings (variant 2)	null	Required
settings_status	string	Required	enum: ["configured","not_configured"]
planned_window_status	string	Required	enum: ["within","outside","not_configured"]
matching_birth_windows	array	Optional	maxItems: 40; default: []
matching_birth_windows[]	object	Required
matching_birth_windows[].label	string	Required	minLength: 1; maxLength: 80
matching_birth_windows[].start_date	string	Required
matching_birth_windows[].end_date	string	Required
conception_window (variant 1)	object	Required
conception_window (variant 1).start_date	string	Required
conception_window (variant 1).end_date	string	Required
conception_window (variant 2)	null	Required
sire	object	Required
sire.status	string	Required	enum: ["unknown","candidates","presumed"]
sire.animal_id	string	Optional	format: "uuid"
sire.confidence	number	Optional	minimum: 0; maximum: 1
sire.provenance	string	Optional	maxLength: 1000
sire.presumed_cross	string	Optional	maxLength: 220
sire.candidates	array	Required	maxItems: 128
sire.candidates[]	object	Required
sire.candidates[].animal_id	string	Required	format: "uuid"
sire.candidates[].eligibility	string	Required	enum: ["plausible","unknown","excluded"]
sire.candidates[].reasons	array	Required	maxItems: 16
sire.candidates[].reasons[]	string	Required	maxLength: 1000
sire.candidates[].exposure_record_ids	array	Required	maxItems: 128
sire.candidates[].exposure_record_ids[]	string	Required	format: "uuid"
sire.candidates[].exposure_record_item_ids	array	Required	maxItems: 128
sire.candidates[].exposure_record_item_ids[]	string	Required	format: "uuid"
sire.candidates[].membership_record_ids	array	Required	maxItems: 128
sire.candidates[].membership_record_ids[]	string	Required	format: "uuid"
sire.candidates[].membership_record_item_ids	array	Required	maxItems: 128
sire.candidates[].membership_record_item_ids[]	string	Required	format: "uuid"
sire.candidates[].overlap_intervals	array	Required	maxItems: 128
sire.candidates[].overlap_intervals[]	object	Required
sire.candidates[].overlap_intervals[].start_date	string	Required
sire.candidates[].overlap_intervals[].end_date	string	Required
sire.candidates[].breed	string	Optional	maxLength: 100
movement_comparisons	array	Required	maxItems: 128
movement_comparisons[]	object	Required
movement_comparisons[].record_id	string	Required	format: "uuid"
movement_comparisons[].record_item_id	string	Required	format: "uuid"
movement_comparisons[].kind	string	Required	enum: ["purchase","movement_in","movement_out"]
movement_comparisons[].date	string	Required
movement_comparisons[].relation_to_conception	string	Required	enum: ["before","within","after","unknown"]
unresolved	array	Required	maxItems: 64
unresolved[]	string	Required	maxLength: 1000

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.

json example

{
  "success": false,
  "errors": [
    {
      "code": 400,
      "name": "ValidationError",
      "message": "Example validation failure"
    }
  ]
}