Birth sources API

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

GET /v1/farm/{farm_id}/birth-sources/{source_sms_id}

GET /v1/farm/{farm_id}/birth-sources/{source_sms_id}

Read retained birth-source evidence

Returns ordered attachment processing status and current farm-matched numeric tag candidates for the original source author with current farm membership. Requires read:records and read:animals for external credentials. No source URLs, signed URLs, raw OCR text, or image bytes are returned. Partial or uncertain candidates require producer selection; this operation writes no farm records.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
source_sms_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-sources/<source_sms_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

Status	Meaning	Content type
200	Private source evidence	application/json
401	Authentication required	No body
403	Required read scope missing	No body
404	Source unavailable to the current user and farm	No body

200 response schema (application/json)

Field	Type	Presence	Constraints
source_sms_id	string	Required	format: "uuid"
source_message_id	string or null	Required
stage	string	Required	enum: ["LEGACY","CONTROL","PENDING","PROCESSING","BLOCKED","FAILED","COMPLETE"]
failure_code	string or null	Required
media	array	Required
media[]	object	Required
media[].id	string	Required	format: "uuid"
media[].ordinal	integer	Required	minimum: 0
media[].file_id	string or null	Required
media[].content_type	string or null	Required
media[].state	string	Required	enum: ["PENDING","RETAINED","FAILED"]
media[].ocr_state	string	Required	enum: ["PENDING","COMPLETE","FAILED","UNSUPPORTED"]
media[].ocr_version	string or null	Required
media[].ocr_attempts	integer	Required	minimum: 0
media[].ocr_failure_code	string or null	Required	enum: ["UNSUPPORTED_IMAGE","IMAGE_LIMIT","OCR_UNAVAILABLE","OCR_TIMEOUT","OCR_OUTPUT_LIMIT","OCR_FAILED",null]
media[].ocr_completed_at	string or null	Required	format: "date-time"
media[].candidates	array	Required	maxItems: 128
media[].candidates[]	object	Required
media[].candidates[].animal_id	string	Required	format: "uuid"
media[].candidates[].identifier_id	string	Required	format: "uuid"
media[].candidates[].identifier_value	string	Required	maxLength: 100
media[].candidates[].normalized_identifier	string	Required
media[].candidates[].is_iso_eid	boolean	Required
media[].candidates[].match_kind	string	Required	enum: ["exact","suffix","partial"]
media[].candidates[].confidence	string	Required	enum: ["high","low"]
media[].candidates[].requires_selection	boolean	Required
media[].candidates[].supporting_observations	array	Required	maxItems: 128
media[].candidates[].supporting_observations[]	object	Required
media[].candidates[].supporting_observations[].media_id	string	Required	format: "uuid"
media[].candidates[].supporting_observations[].digits	string	Required
media[].candidates[].supporting_observations[].ocr_confidence	number	Required	minimum: 0; maximum: 100
media[].candidates[].supporting_observations[].box	object	Required
media[].candidates[].supporting_observations[].box.left	number	Required	minimum: 0
media[].candidates[].supporting_observations[].box.top	number	Required	minimum: 0
media[].candidates[].supporting_observations[].box.width	number	Required
media[].candidates[].supporting_observations[].box.height	number	Required
media[].candidates[].supporting_observations[].match_kind	string	Required	enum: ["exact","suffix","partial"]
media[].candidates_truncated	boolean	Required
candidates	array	Required	maxItems: 128
candidates[]	object	Required
candidates[].animal_id	string	Required	format: "uuid"
candidates[].identifier_id	string	Required	format: "uuid"
candidates[].identifier_value	string	Required	maxLength: 100
candidates[].normalized_identifier	string	Required
candidates[].is_iso_eid	boolean	Required
candidates[].match_kind	string	Required	enum: ["exact","suffix","partial"]
candidates[].confidence	string	Required	enum: ["high","low"]
candidates[].requires_selection	boolean	Required
candidates[].supporting_observations	array	Required	maxItems: 128
candidates[].supporting_observations[]	object	Required
candidates[].supporting_observations[].media_id	string	Required	format: "uuid"
candidates[].supporting_observations[].digits	string	Required
candidates[].supporting_observations[].ocr_confidence	number	Required	minimum: 0; maximum: 100
candidates[].supporting_observations[].box	object	Required
candidates[].supporting_observations[].box.left	number	Required	minimum: 0
candidates[].supporting_observations[].box.top	number	Required	minimum: 0
candidates[].supporting_observations[].box.width	number	Required
candidates[].supporting_observations[].box.height	number	Required
candidates[].supporting_observations[].match_kind	string	Required	enum: ["exact","suffix","partial"]
candidates_truncated	boolean	Required

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