CattleOSCattleOSDevelopers

API Reference

Base URL: https://app.cattleos.com

Authentication

All API requests require a Bearer token in the Authorization header. You can use either a Firebase ID token (for client apps) or a CattleOS API key (for server-to-server integrations).

Authorization: Bearer cos_live_your_key_here

API keys are scoped to a farm and specific resource permissions. Create and manage keys in your dashboard.

Cooper AI

POST/api/v1/cooper/chatChat with Cooper (AI assistant)

Authentication

POST/api/v1/api-keysCreate an API key
GET/api/v1/api-keysList your API keys
DELETE/api/v1/api-keys/:idRevoke an API key

Cattle

GET/api/v1/cattleList all cattle
POST/api/v1/cattleCreate a cattle record
GET/api/v1/cattle/:idGet a single animal
PATCH/api/v1/cattle/:idUpdate a cattle record
DELETE/api/v1/cattle/:idArchive a cattle record

Activities

GET/api/v1/activitiesList activities
POST/api/v1/activitiesLog an activity
GET/api/v1/activities/:idGet activity details
PATCH/api/v1/activities/:idUpdate an activity
DELETE/api/v1/activities/:idDelete an activity

Contacts

GET/api/v1/contactsList contacts
POST/api/v1/contactsCreate a contact
GET/api/v1/contacts/:idGet contact details
PATCH/api/v1/contacts/:idUpdate a contact

Financial

GET/api/v1/financial/costsList costs
POST/api/v1/financial/costsRecord a cost
GET/api/v1/financial/revenueList revenue
POST/api/v1/financial/revenueRecord revenue
GET/api/v1/financial/line-itemsList line items

Cooper AI API

Cooper is CattleOS's AI assistant. Send natural language messages and Cooper will query your farm data, create records, and perform actions — all through a simple chat interface. Requires the cooper:chat scope.

Request

POST /api/v1/cooper/chat
Authorization: Bearer cos_live_your_key_here
Content-Type: application/json

{
  "messages": [
    {"role": "user", "content": "How many cattle do I have?"}
  ],
  "model": "gpt-4o",          // optional, default: gpt-4o
  "temperature": 0.7,         // optional, 0-2
  "max_tool_rounds": 5        // optional, 1-10
}

Response

{
  "data": {
    "message": "You have 2,353 cattle across 12 pens.",
    "tool_calls": [
      {
        "name": "list_cattle",
        "arguments": {},
        "result": { "matchingCount": 2353, "items": [...] }
      }
    ],
    "model": "gpt-4o",
    "usage": {
      "prompt_tokens": 1250,
      "completion_tokens": 42,
      "total_tokens": 1292
    }
  }
}

Multi-turn Conversations

Pass previous messages to maintain context. Cooper will remember what was discussed and can reference earlier data.

{
  "messages": [
    {"role": "user", "content": "How many cattle do I have?"},
    {"role": "assistant", "content": "You have 2,353 cattle."},
    {"role": "user", "content": "How many are in the North Pen?"}
  ]
}

What Cooper Can Do

Cooper has access to 100+ tools covering:

  • Cattle — list, create, update, delete, record weights, health treatments
  • Pens & Barns — create, manage, move cattle between pens
  • Inventory — add feed, medications, track transactions
  • Activities & Notes — log daily operations
  • Financial — record costs, revenue, cattle sales
  • Zones & Properties — manage ranch map, move cattle between zones
  • Contacts — manage buyers, vets, suppliers
  • Tasks — create and manage farm tasks

Read the full Cooper AI documentation →

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Cattle record not found"
  }
}

Rate Limits

API keys are limited to 100 requests per minute. Exceeding this limit returns a 429 Too Many Requests response with a Retry-After header.