Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Farmbrite API Developers Documentation Animals & Livestock…
description: '# Overview
Welcome to the Farmbrite API. You can find out more about Farmbrite at
www.farmbrite.com
If you need help, check out our help center at help.farmbrite.com or email us at dev@farmbrite.com. ## API Reference
The Farmbrite API allows authorized users programatic access to their account data in order to facilitate the integration of this data with other systems and service. The API is organized around REST standards. The API uses resource-oriented URLs and returns JSON-encoded responses. It uses standard HTTP response codes, authentication, and verbs. > Base URL
```
https://api.farmbrite.com/v1
```
# Authentication
Farmbrite offers 2 authentication options for accessing the API both utilizing Personal Access Tokens (PATs) for enabling access to the API. Access Tokens (API Keys) are associated with an individual user in your account and inherit that user''s role and permissions. You can find the Access Token on the user profile page under API Key. When building an integration we recommend setting up a separate API user for the integration and changing the API KEY on a regular basis. Remember to keep your Access Tokens secret; treat them just like passwords! They act on your behalf when interacting with the API, with the same permissions and access as the user has. _Don''t hardcode them into your programs_. Instead, choose to store them as environment variables. ### Bearer Token
To make a request to the API include the Authorization Bearer header with your request and include your Access Token (API KEY) as the value. Access Token and API KEY are used interchangeably through out the documentation. > Example cURL request authenticating with Bearer Token authentication
```
curl https://api.farmbrite.com/v1/tasks \
-H "Authorization: Bearer ACCESS_TOKEN"
```
### API Key
Alternatively to using the Bearer Token authorization method, you can provide an API KEY as a header with your request. Use the header `api_key` with a value of your Access Token (API KEY). > Example cURL request authenticating with API Key header authentication
```
curl https://api.farmbrite.com/v1/tasks \
-H "api_key: ACCESS_TOKEN"
```
# Errors
Sadly, sometimes requests to the API fail. Failures can occur for a wide range of reasons. In all cases, the API should return an HTTP Status Code indicating the nature of the failure. | Code | Meaning | Description |
| --- | --- | --- |
| 200 | Success | The request was successful. If applicable the data it will be available in the data field at the top level of the response body. |
| 400 | Bad Request | Typically caused by a missing or malformed parameter. Check the documentation and your request and try again. |
| 401 | Unauthorized | No access token or an invalid access token was provided with the request. The error can also occur if the user or account is invalid or does not have access to this resource. |
| 403 | Forbidden | The authentication and request syntax was valid but the server is refusing to complete the request. This can happen if you access resources that the user or account does not have access to. |
| 404 | Not Found | Either the method and path supplied do not specify a known action or the object related to the request does not exist. |
| 429 | Too Many Requests | You have exceeded one of the rate limits in the API. See the Rate Limits section for more information. |
| 500 | Internal Server Error | There was a problem on Farmbrite''s side which was logged and reported to our technical team. You can retry, but if the problem continues please contact support. |
Details about errors can sometimes also be found in the ''message'' property at the root level of the JSON response body. # Pagination
In order to optimize performance, all list methods in the API will limit the total response data to a certain number of records and return the data in chunks (pages). API responses will include information about the total records available, the current page and total pages.'
version: 1.0.0
x-logo:
url: https://static.farmbrite.com/assets/www/images/logo.png
backgroundColor: '#FFFFFF'
altText: Farmbrite
termsOfService: https://www.farmbrite.com/terms
contact:
name: Farmbrite
url: https://developers.farmbrite.com
email: dev@farmbrite.com
servers:
- url: https://api.farmbrite.com/v1
security:
- bearerAuth: []
tags:
- name: Animals & Livestock
description: 'Livestock (animals) are the basic object that is used to store animal records. A livestock record can represent either a single animal (most common and default) or a set of animals (like a flock of chickens). Note: A set of animals is different than a livestock group, which is used to manage groups of individual animals. Sets are used to keep track of groups of animals where you don''t want or need to track each animal individually.
Livestock, like other resources have various embedded or related resources
For example:
- Notes
- Photos
- Files
- Tasks
- Measurements
- Feedings
- Treatments
- Grazings
- Tasks
- Schedule'
paths:
/animals:
post:
tags:
- Animals & Livestock
summary: Create an Animal
description: 'Create a new animal record
### **Parameters**
**type** **`REQUIRED`**
Animal type/species. You can specify a custom value for this or use one of the default types:
> "Alpaca", "Bees", "Bison", "Buffalo", "Butterflies", "Camel", "Cat", "Catfish", "Cattle", "Chicken", "Crickets", "Deer", "Dog", "Donkey", "Duck", "Elk", "Emu", "Fish", "Gayal", "Goat", "Goose", "Guineafowl", "Horse", "Llama", "Mealworms", "Mollusk", "Mule", "Muskox", "Ostrich", "Partridge", "Peafowl", "Pheasant", "Pig", "Pigeon", "Pony", "Quail", "Rabbit", "Reindeer", "Rhea", "Salmon", "Sheep", "Shellfish", "Silkworms", "Swine", "Tilapia", "Trout", "Turkey", "Water buffalo", "Waxworms", "Yak", "Zebu"
---
**status** **`REQUIRED`**
The status of the animal or livestock set. Supported values are any of the following:
> "Active", "Butchered", "Culled", "Deceased", "Dry", "Lactating", "Lost", "Off Farm", "Quarantined", "Reference", "Sick", "Sold", "Weaning", "Archived"
When setting the status to `"Butchered", "Culled", "Deceased",` you must also provide a death_date. And when setting the status to `"Sold"` a `sold_date` is required. ---
**name** **`OPTIONAL`**
The name or primary identifier for the animal (eg; tag number)
---
**tag_number** `OPTIONAL`
Animal''s primary tag number
---
**is_group** **`OPTIONAL`**
Specifies if this record is a _livestock set_ used to track multiple animals, without recording data for each animal. Defaulted to `false.`If setting to `true`, you should also set a `group_qty` which stores the initial count of the animals in your set. ---
**electronic_id** `OPTIONAL`
Electronic ID - useful to set if using an RFID or barcode scanner to search for for sync data with Farmbrite. ---
**gender** `OPTIONAL`
Sex/gender of the animal. Possible values are `Male` or `Female`
---
**bred_status** `OPTIONAL`
The current breeding status for a female animal. Supported values are any of the following:
> "Open", "Exposed", "Pregnant"
When setting `bred_status` to a value other than `Open`, it''s recommend to set the `bred_date` value to the date exposed. ---
**mother_id** `OPTIONAL`
The Farmbrite unique ID for the animal''s mother
---
**father_id** `OPTIONAL`
The Farmbrite unique ID for the animal''s father
---
**weight** `OPTIONAL`
The numeric value of animals current weight in either pounds or kilograms (depending on your account settings). When creating a new record this will create a measurement record for the animal. ---
**harvest_unit** `OPTIONAL`
The unit used to record harvests for this animal. Supported values are:
> "Bales", "Barrels", "Bunches", "Bushels", "Dozen", "Fluid Ounces", "Gallons", "Grams", "Head", "Kilograms", "Kiloliter", "Liter", "Milliliter", "Ounces", "Pounds", "Quantity", "Quarts", "Tonnes", "Tons"
The default is to store harvests as `Quantity`
---
### Additional Parameters
**birth_date** `OPTIONAL`
Birth date - formatted as `YYYY-MM-DD`
---
**birth_weight** `OPTIONAL`
Numeric value of weight at birth
---
**bred_date** `OPTIONAL`
Date of last breeding or exposure, formatted as `YYYY-MM-DD`
---
**breed** `OPTIONAL`
Breed of the animal
---
**breeding_stock** `OPTIONAL`
Boolean value to allow filter to identify animals that are prime breeding stock
---
**coloring** `OPTIONAL`
Description of animal color, markings, etc. ---
**condition_score** `OPTIONAL`
Numeric value used to track body condition score or breed specific scores. Often used for identifying key breeding candidates or for culling. When set, this will create a measurement record for the animal. ---
**death_date** `OPTIONAL`
Date deceased or culled. Required when setting the status to `"Butchered", "Culled", "Deceased"` - formatted as `YYYY-MM-DD`
---
**deceased_reason** `OPTIONAL`
Text description for the cause of death. ---
**description** `OPTIONAL`
Text description of animal
---
**harvest_label** `OPTIONAL`
Custom label to be used when displaying harvests.'
requestBody:
content:
application/json:
schema:
type: object
example:
birth_date: '2022-01-01'
birth_weight: 50
bred_date: ''
breed: Test
breeding_status: Open
breeding_stock: false
coloring: Black and White
condition_score: 0
death_date: null
deceased_reason: ''
description: API testing cow
father_id: null
gender: Female
harvest_label: lbs
harvest_unit: pounds
is_group: false
is_neutered: false
keywords: cow, breeding stock
market_price: null
mother_id: null
name: Api Tester
on_feed: false
other_tag_number: null
purchase_date: null
purchase_price: 0
purchased: true
purchased_from_id: null
registry_number: '12345'
retention_score: 0
sale_date: null
status: Active
tag_color: red
tag_number: '123'
type: Cow
internal_id: ''
weight: 500
height: 50
electronic_id: ADE184901-JKLA
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
responses:
'200':
description: Successful response
content:
application/json: {}
operationId: postAnimals
x-operation-id-source: derived
get:
tags:
- Animals & Livestock
summary: List Animals
description: By default List Animals will only return active animals. Meaning animals that in a status of "Active", "Dry", "Finishing", "For Sale", "Lactating", "Lost", "Quarantined", "Sick", "Weaning", etc. To return animals of other statuses ("Deceased", "Sold", "Culled", etc) you should supply a filter for the animal status.
parameters:
- name: session_id
in: header
schema:
type: string
example: adc87241d4d7f3ce5e1f1de55b68fe5e
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
example:
data:
- id: GUID
birth_date: '2018-03-01'
birth_weight: 22.7
bred_date: '2021-09-28'
breed: Lucky
breeder_id: null
breeding_status: Exposed
breeding_stock: false
coloring: Black and White
condition_score: 7
contact_id: Contact ID
created_at: '2015-12-20 20:19:11'
death_date: null
deceased_reason: ''
description: ''
electronic_id: ''
estimated_value: 1975.55
father_id: Father ID
feed: ''
gender: Female
group_id: Basic Group ID
group_qty: null
harvest_label: Pounds
harvest_unit: pounds
height: 50
internal_id: ''
is_group: false
is_neutered: false
keywords: ''
market_price: 3.5
measurement_date: null
mother_id: null
name: API Cow
on_feed: false
other_tag_number: USDA tag
purchase_date: '2018-08-01'
purchase_price: 27
purchased: true
purchased_from_id: Contact ID
registry_number: ''
retention_score: 7
sale_date: null
sale_price: null
sold_to: null
status: Active
tag_color: cyan
tag_number: '157'
type: Cow
updated_at: '2022-01-18 21:10:57'
weight: 1600
operationId: getAnimals
x-operation-id-source: derived
/animals/{animal_id}:
get:
tags:
- Animals & Livestock
summary: Retrieve an Animal
parameters:
- name: animal_id
in: path
schema:
type: string
required: true
example: '{{animal_id}}'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
example:
id: GUID
birth_date: '2018-03-01'
birth_weight: 22.7
bred_date: '2021-09-28'
breed: Lucky
breeder_id: null
breeding_status: Exposed
breeding_stock: false
coloring: Black and White
condition_score: 7
contact_id: Contact ID
created_at: '2015-12-20 20:19:11'
current_location_id: Read Only ID for animal grazing location
custom_fields: {}
death_date: null
deceased_reason: ''
description: ''
electronic_id: ''
estimated_value: 1975.55
father_id: Father ID
feed: ''
gender: Female
group_id: Basic Group ID
group_qty: null
harvest_label: Pounds
harvest_unit: pounds
height: 50
internal_id: ''
is_group: false
is_neutered: false
keywords: ''
market_price: 3.5
measurement_date: null
mother_id: null
name: API Cow
on_feed: false
other_tag_number: USDA tag
purchase_date: '2018-08-01'
purchase_price: 27
purchased: true
purchased_from_id: Contact ID
registry_number: ''
retention_score: 7
sale_date: null
sale_price: null
sold_to: null
status: Active
tag_color: cyan
tag_number: '157'
type: Cow
updated_at: '2022-01-18 21:10:57'
weight: 1600
operationId: getAnimalsByAnimalId
x-operation-id-source: derived
put:
tags:
- Animals & Livestock
summary: Update an Animal
requestBody:
content:
application/json:
schema:
type: object
example:
type: Bull
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
- name: animal_id
in: path
schema:
type: string
required: true
example: '{{animal_id}}'
responses:
'200':
description: Successful response
content:
application/json: {}
operationId: putAnimalsByAnimalId
x-operation-id-source: derived
delete:
tags:
- Animals & Livestock
summary: Delete an Animal
parameters:
- name: animal_id
in: path
schema:
type: string
required: true
responses:
'200':
description: Successful response
content:
application/json: {}
operationId: deleteAnimalsByAnimalId
x-operation-id-source: derived
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer