canonical: https://jentic.com/apis/ranch.bot/ranch # Ranch.Bot HTTP API The Ranch.Bot HTTP API keeps livestock records for farms and ranches: animals and their EID tag identifiers, groups, records, feedings, rations, and calving or birth events. It schedules and approves farm events, tracks follow-up farm tasks and recurring events, and runs chute sessions that log animals as they pass through the chute. Workflow templates let a farm preview a workflow run before committing it, and exports, imports, and inventory or AgriStability reports move data in and out, all scoped by farm_id. ## For AI agents Read and update Ranch.Bot livestock records, look up animals by EID, schedule and approve farm events, track farm tasks, and run previewed workflows for a farm. ## Scope Does not handle crop field mapping, livestock sales marketplaces, or veterinary prescriptions. Use for Ranch.Bot livestock records, farm events, tasks, and workflows only. ## Capabilities - List a farm's animals by inventory_status such as CURRENT, SOLD, or DECEASED and look one up by exact EID - Find or create an animal from an EID tag scan during a chute session - Schedule farm events, approve or reject pending ones, and manage recurring events - Preview a workflow run from a template_id and inputs, then commit or discard the preview - Record feedings and assign rations to animals or groups - Preview and confirm birth events and review dated birth history - Generate inventory and AgriStability reports and create downloadable farm exports ## Use cases ### Ranch assistant agent through Jentic A ranch assistant agent can answer herd questions and log work without the rancher opening the app. Through Jentic the agent searches for 'look up an animal by EID', receives the Ranch.Bot operation with its input schema, and calls GET `/v1/farm/{farm_id}/animals/lookup-by-eid`, with the OAuth device token injected at execution time. Ranch.Bot notes that direct API writes skip the app's confirmation screen, so preview-then-commit operations are the safer path for changes. Example prompt: Look up an animal with GET `/v1/farm/{farm_id}/animals/lookup-by-eid` using its EID, then list its records with GET `/v1/farm/{farm_id}/records` ### Previewed workflow runs Farm work such as processing a group through vaccinations is easy to get wrong when written straight to the record. Ranch.Bot's POST `/v1/farm/{farm_id}/workflows/preview` takes a request_id, template_id, and inputs and returns a preview that can be read, then committed through the commit route or dropped through the discard route. Example prompt: Create a preview with POST `/v1/farm/{farm_id}/workflows/preview` using request_id, template_id, and inputs, read it back with GET `/v1/farm/{farm_id}/workflows/previews/{preview_id}`, then commit it ### Event scheduling and approvals Herd health plans run on schedules, and some events need sign-off before they land. Ranch.Bot lists scheduled events, returns those pending approval through GET `/v1/farm/{farm_id}/scheduled-events/pending/approval`, and approves or rejects each one, while recurring events and farm follow-up tasks keep routine work on the calendar. Example prompt: Call GET `/v1/farm/{farm_id}/scheduled-events/pending/approval` and approve each event with POST `/v1/farm/{farm_id}/scheduled-events/{scheduled_event_id}/approve` ### Chute-side animal logging When cattle move through a chute, each EID tag scan needs to match an animal record. Ranch.Bot chute sessions are created with a config, and POST `/v1/farm/{farm_id}/animals/find-or-create-by-eid` takes an eid and returns the matching animal or creates it, with a sync route to push session entries and an undo route for mistaken entries. Example prompt: Create a chute session with POST `/v1/farm/{farm_id}/chute-sessions` and a config, then call POST `/v1/farm/{farm_id}/animals/find-or-create-by-eid` for each scanned eid ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/v1/farm/{farm_id}/animals` | List animals | | GET | `/v1/farm/{farm_id}/animals/lookup-by-eid` | Look up an animal by EID | | POST | `/v1/farm/{farm_id}/animals/find-or-create-by-eid` | Find or create an animal by EID | | GET | `/v1/farm/{farm_id}/scheduled-events/pending/approval` | List events pending approval | | POST | `/v1/farm/{farm_id}/workflows/preview` | Preview a workflow run | | GET | `/v1/farm/{farm_id}/farm-tasks` | List farm follow-up tasks | | GET | `/v1/farm/{farm_id}/reports/inventory` | Get inventory report | | GET | `/v1/farm` | List farms | ## Key resources - **Farms** — Farms the account belongs to, plus the user's default farm - **Animals** — Animal profiles, EID identifiers, inventory status, and EID lookup or find-or-create - **Groups, records, and feedings** — Animal groups, records and record items, feedings, rations, and ration assignments - **Events and tasks** — Scheduled events with approval, recurring events, and farm follow-up tasks - **Workflows** — Workflow templates and versions, with preview, commit, and discard of workflow runs - **Birth events** — Birth event preview and confirmation, birth history settings, and evidence - **Imports, exports, and reports** — Data imports and import requests, downloadable exports, and inventory and AgriStability reports ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 59 / 100 - **Maturity:** Foundational - **Dimensions:** - Foundational Compliance: 56 / 100 - Developer Experience & Jentic Compatibility: 72 / 100 - AI-Readiness & Agent Experience: 44 / 100 - Agent Usability: 79 / 100 - Security: 68 / 100 - AI Discoverability: 51 / 100 - **View full report:** https://jentic.com/apis/ranch.bot/ranch/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring Ranch.Bot by hand means completing the OAuth device flow against `/oauth/device` and `/oauth/device/token`, keeping the JWT fresh, and matching the required scopes and farm role listed per data operation. Through Jentic you install once, import Ranch.Bot from the API Directory, store the credential once, and your agent calls it. - **Permission scoping:** Ranch.Bot puts the farm id in the URL path (`/v1/farm/{farm_id}/...`), so a rule can pin your agent to one farm and the operations you pick. You choose the operations it may call, so destructive ones like DELETE `/v1/farm/{farm_id}/animals/{animal_id}` or workflow commits are not included unless you add them. - **Credential handling:** Your Ranch.Bot token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'look up an animal by EID' or 'approve pending farm events', and Jentic returns the matching Ranch.Bot operation with its input schema so the agent calls the right endpoint without reading the reference. ## Related APIs - **Farmbrite** — Farm management with animal records, feedings, grazings, and livestock groups - **Climate FieldView** — Field boundaries and as-planted and as-harvested crop data - **USDA ERS ARMS** — US farm financial and production survey data ## FAQ ### What authentication does the Ranch.Bot HTTP API use? Per its OpenAPI spec, Ranch.Bot accepts an OAuth device access token in JWT format as a bearer token, with a deprecated LegacyKey bearer scheme for rb_sk_ keys. The /oauth routes, including device authorization and token exchange, are open and take a registered client_id. The /v1 data operations list required scopes such as read:animals or write:records and a minimum farm role, and PUT `/v1/user/default-farm` is declared for LegacyKey. Access is for directed developer use through support@ranch.bot. ### What are the rate limits for the Ranch.Bot HTTP API? The OpenAPI spec states a production limit of 100 requests per 15-minute window per legacy key or device account, 1000 per browser session, and otherwise per client IP. RateLimit headers report the current window, and clients should respect Retry-After on a 429 response. ### Can I look up an animal by its EID tag with the Ranch.Bot HTTP API? Yes. GET `/v1/farm/{farm_id}/animals/lookup-by-eid` looks up an animal by exact EID without writing anything. POST `/v1/farm/{farm_id}/animals/find-or-create-by-eid` takes an eid and creates the animal if no match exists. ### Is there a Ranch.Bot MCP server? You don't need an MCP server to give your agent Ranch.Bot. Jentic connects it directly from the API Directory: import it, store your token once, and your agent calls the animal, event, and workflow operations it needs, discovered on demand. ### Can I limit what my agent is allowed to do with the Ranch.Bot HTTP API? Yes. For example, write a rule that allows only the animal list, EID lookup, and records read operations under one farm_id, so the agent can answer herd questions for that ranch and cannot delete animals, commit workflows, or remove exports, and its calls are logged. ### How do I approve scheduled farm events through Jentic? Search Jentic for 'approve pending farm events', load GET `/v1/farm/{farm_id}/scheduled-events/pending/approval` to list them, then call POST `/v1/farm/{farm_id}/scheduled-events/{scheduled_event_id}/approve` for each one. To run it on your own infrastructure, install Jentic One from its GitHub repo.