Ranch.Bot developer reference

Build farm-data integrations with the existing Ranch.Bot HTTP API. Browse the contract here; access remains directed developer use.

The API can read livestock inventories, identifiers, groups, dated records, feeding data, and farm reports. Authorized integrations can write records and other supported resources. Import requests submit files for supervised review. The reference records current HTTP behavior, including legacy limitations.

Start here

Read authentication and access, then try the integration walkthroughs or choose a resource from the navigation. Download the same contract as OpenAPI 3.1 JSON.

This reference is public and requires no login. Calling the API requires credentials and access to a farm. Contact support@ranch.bot with the integration you want to build and the farm owner who will authorize access. There is no self-serve developer registration in this release.

Farm data model

A farm holds animals and groups. Animals can have multiple identifiers, including EID and visual tags. Records have a name, one of five generic types, an event date, an optional description, and links to animals or groups. Record items carry additional named data. Farm memory stores contextual information; its HTTP integration surface is read-only.

Each farm request names a farm id. A credential identifies a user; active farm membership and the required role determine access. Scopes restrict what an external credential can do. A scope does not grant access to a new farm.

REST, CLI, and MCP

REST is the HTTP surface described by this contract. CLI and MCP source implementations expose farm-data tools through different transports. Do not assume every tool has an identically named HTTP endpoint or an identical response envelope.

The CLI and local stdio MCP implementations exist in source, but public installation remains pending verification. Ranch.Bot operates no hosted MCP endpoint. See current external-assistant availability.

Reading the reference

Use the canonical /v1 paths shown here. The same router is also mounted at /api/v1 today; OAuth uses /oauth. Resource pages include stable method-and-path anchors, schemas, and examples with made-up data. No new compatibility or version-support guarantee is implied.

Collection names vary. For example, animal lists use records, while file operations use their own response envelope. Use each response schema instead of assuming a universal wrapper. Dates on the wire are JSON strings.