Integration walkthroughs

Page through animals, save an observation linked to an animal, and retrieve a farm inventory report using the existing HTTP API.

Confirm API access first. Use an authorized test farm and an animal obtained from that farm. All ids below are placeholders; dates and observations are made-up data. The linked-record example writes immediately. Run it only when you intend to create that record.

Page through animals with cURL

This Bash example uses cURL and jq. Set RANCHBOT_TOKEN through your credential setup and replace the farm id. The animal-list collection is named records. Stop on an empty page or once the returned total has been reached.

bash example

RANCHBOT_API_URL='https://api.ranch.bot'
RANCHBOT_FARM_ID='<farm_id>'
animal_skip=0
animal_take=25
while :; do
  animal_page=$(curl --fail-with-body --silent --show-error \
    "$RANCHBOT_API_URL/v1/farm/$RANCHBOT_FARM_ID/animals?skip=$animal_skip&take=$animal_take" \
    -H "Authorization: Bearer $RANCHBOT_TOKEN") || break
  printf '%s\n' "$animal_page" | jq '.records[]'
  animal_count=$(printf '%s' "$animal_page" | jq '.records | length')
  animal_total=$(printf '%s' "$animal_page" | jq '.total')
  animal_skip=$((animal_skip + animal_count))
  [ "$animal_count" -eq 0 ] && break
  [ "$animal_skip" -ge "$animal_total" ] && break
done

Required scope: read:animals; minimum role: READER. Offset pagination is not a snapshot. Avoid concurrent changes during a bulk read and deduplicate ids when combining pages. Rate limits apply to every request.

Create a linked record with cURL

Required scope: write:records; minimum role: EDITOR. Replace both ids before running. At least one animal or group association is required. This request does not show an app confirmation screen.

bash example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/records' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"animal_ids":["<animal_id>"],"group_ids":[],"name":"Example observation","type":"OTHER","applied_at":"2026-09-01T12:00:00.000Z"}'

A successful creation returns 201 and the record object, including its id. It does not return the animal/group associations. Do not automatically retry creation after an uncertain network result; check whether the record saved first.

Retrieve a farm report with cURL

Required scope: read:records; minimum role: READER. This example uses a custom window with an inclusive start and exclusive end.

bash example

curl --fail-with-body \
  'https://api.ranch.bot/v1/farm/<farm_id>/reports/inventory?preset=custom&from=2026-09-01&to=2026-09-02' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

The report reflects available farm records, not a guarantee that every real-world movement was recorded. Read its warnings and the report response schema.

The same requests in JavaScript

These functions use the standard fetch API. Supply token, farmId, and, for record creation, animalId. The pagination function deduplicates ids. The examples do not retry writes.

javascript example

// Examples use the credentials supplied through directed developer setup.
async function readJson(baseUrl, token, route, options = {}) {
  const response = await fetch(`${baseUrl}${route}`, {
    ...options,
    headers: {
      Authorization: `Bearer ${token}`,
      ...(options.body ? { 'Content-Type': 'application/json' } : {}),
    },
  });
  if (!response.ok) throw new Error(`Ranch.Bot returned HTTP ${response.status}`);
  return response.json();
}

async function listAnimals({ baseUrl = 'https://api.ranch.bot', token, farmId, take = 25 }) {
  const animals = [];
  const seen = new Set();
  let skip = 0;
  while (true) {
    const page = await readJson(baseUrl, token, `/v1/farm/${farmId}/animals?skip=${skip}&take=${take}`);
    for (const animal of page.records) {
      if (!seen.has(animal.id)) {
        animals.push(animal);
        seen.add(animal.id);
      }
    }
    skip += page.records.length;
    if (page.records.length === 0 || skip >= page.total) return animals;
  }
}

function createAnimalRecord({ baseUrl = 'https://api.ranch.bot', token, farmId, animalId }) {
  return readJson(baseUrl, token, `/v1/farm/${farmId}/records`, {
    method: 'POST',
    body: JSON.stringify({
      animal_ids: [animalId], group_ids: [], name: 'Example observation', type: 'OTHER',
      applied_at: '2026-09-01T12:00:00.000Z',
    }),
  });
}

function getFarmReport({ baseUrl = 'https://api.ranch.bot', token, farmId }) {
  return readJson(baseUrl, token, `/v1/farm/${farmId}/reports/inventory?preset=custom&from=2026-09-01&to=2026-09-02`);
}

javascript example

const options = { token: '<access_token>', farmId: '<farm_id>' };
const animals = await listAnimals(options);
const record = await createAnimalRecord({ ...options, animalId: '<animal_id>' });
const report = await getFarmReport(options);

These functions are tested against the HTTP controllers with made-up farm data. They are examples, not a published SDK. For supervised file intake, use import requests; the legacy import endpoint has a documented upload limitation.