Protocol versions API

HTTP reference for protocol versions. Read authentication and access before using these operations. All examples use made-up data and placeholder credentials.

GET /v1/farm/{farm_id}/protocol-versions
POST /v1/farm/{farm_id}/protocol-versions

GET /v1/farm/{farm_id}/protocol-versions

List farm protocol versions

List immutable protocol definitions without inventing missing care steps. External credential scopes: read:records. Minimum farm role: READER.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
skip	query	No	{"type":"integer","minimum":0,"default":0}
take	query	No	{"type":"integer","minimum":1,"maximum":200,"default":50}

Request example

bash example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/protocol-versions' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

Status	Meaning	Content type
200	Success	application/json
400	Request validation failed.	application/json
401	Missing/invalid authentication or insufficient farm role.	application/json
403	Missing required scope or credential type is disallowed.	application/json
404	Resource or active farm membership not found.	application/json
429	Rate limit exceeded. Retry after the indicated delay.	application/json
500	Unexpected server failure.	application/json

200 response schema (application/json)

Field	Type	Presence	Constraints
total	integer	Required	minimum: 0
records	array	Required
records[]	object	Required
records[].id	string	Required	format: "uuid"
records[].farm_id	string	Required	format: "uuid"
records[].name	string	Required
records[].version	string	Required
records[].steps	array	Required
records[].steps[]	string	Required
records[].created_by_user_id	string	Required	format: "uuid"
records[].created_at	string	Required	format: "date-time"

POST /v1/farm/{farm_id}/protocol-versions

Create a farm protocol version

Save the exact producer-approved protocol name, version and steps. The same version and steps are idempotent; different steps for an existing version return 409. External credential scopes: write:records. Minimum farm role: EDITOR.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}

Request body (application/json)

Field	Type	Presence	Constraints
name	string	Required	minLength: 1; maxLength: 80
version	string	Required	minLength: 1; maxLength: 80
steps	array	Required	minItems: 1; maxItems: 40
steps[]	string	Required	minLength: 1; maxLength: 1000

Create request.json with a JSON body matching the request schema above before running this example.

Request example

bash example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/protocol-versions' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

Responses

Status	Meaning	Content type
201	Success	application/json
400	Request validation failed.	application/json
401	Missing/invalid authentication or insufficient farm role.	application/json
403	Missing required scope or credential type is disallowed.	application/json
404	Resource or active farm membership not found.	application/json
409	The approved preview is stale, the request ID is already used, or the protocol version has different steps.	application/json
429	Rate limit exceeded. Retry after the indicated delay.	application/json
500	Unexpected server failure.	application/json

201 response schema (application/json)

Field	Type	Presence	Constraints
id	string	Required	format: "uuid"
farm_id	string	Required	format: "uuid"
name	string	Required
version	string	Required
steps	array	Required
steps[]	string	Required
created_by_user_id	string	Required	format: "uuid"
created_at	string	Required	format: "date-time"

Error body

Validation and authentication errors generally use this envelope. Rate-limit errors omit data; OAuth polling also has protocol-specific errors shown in its reference.

json example

{
  "success": false,
  "errors": [
    {
      "code": 400,
      "name": "ValidationError",
      "message": "Example validation failure"
    }
  ]
}