Workflows API

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

POST /v1/farm/{farm_id}/workflows/preview
GET /v1/farm/{farm_id}/workflows/previews/{preview_id}
POST /v1/farm/{farm_id}/workflows/previews/{preview_id}/commit
POST /v1/farm/{farm_id}/workflows/previews/{preview_id}/discard

POST /v1/farm/{farm_id}/workflows/preview

Preview a workflow run

External credential scope: read:records. Minimum farm role: EDITOR. Resolves literal and today defaults once, returns a non-committable preview with structured issues for field/domain problems, and creates no livestock records.

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

Request body (application/json)

Field	Type	Presence	Constraints
request_id	string	Required	format: "uuid"
template_id	string	Required	format: "uuid"
template_version	integer	Optional	minimum: 1
inputs	object	Required
inputs.event	object	Optional
inputs.offspring	array	Optional
inputs.offspring[]	object	Required
timezone	string	Optional	maxLength: 100
replaces_preview_id	string	Optional	format: "uuid"

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>/workflows/preview' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

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
409	Concurrent change, archived template, expired preview, or conflicting approval.	application/json

200 response schema (application/json)

Field	Type	Presence	Constraints
preview_id	string	Required	format: "uuid"
template_id	string	Required	format: "uuid"
template_version	integer	Required
resolved_values	object	Optional
default_sources	object	Optional
proposed_changes	object	Optional
proposed_changes.template_version	integer	Optional
proposed_changes.bundle	object	Optional
review	object or null	Optional
validation_issues	array	Optional
validation_issues[]	object	Required
validation_issues[].path	string	Required
validation_issues[].code	string	Required
validation_issues[].severity	string	Required	enum: ["error","warning"]
validation_issues[].message	string	Required
preview_hash	string	Required
expires_at	string	Optional	format: "date-time"
status	string	Required	enum: ["pending","invalid","replaced","committed","discarded"]
committed_at	string	Optional	format: "date-time"
saved_entity_ids	object	Optional
outcome	object	Optional

GET /v1/farm/{farm_id}/workflows/previews/{preview_id}

Read a workflow preview

External credential scope: read:records. Minimum farm role: EDITOR. Returns the pinned review and, when committed, the saved outcome. Committed receipts survive preview expiry and template archival.

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

Request example

bash example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/workflows/previews/<preview_id>' \
  -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
409	Concurrent change, archived template, expired preview, or conflicting approval.	application/json

200 response schema (application/json)

Field	Type	Presence	Constraints
preview_id	string	Required	format: "uuid"
template_id	string	Required	format: "uuid"
template_version	integer	Required
resolved_values	object	Optional
default_sources	object	Optional
proposed_changes	object	Optional
proposed_changes.template_version	integer	Optional
proposed_changes.bundle	object	Optional
review	object or null	Optional
validation_issues	array	Optional
validation_issues[]	object	Required
validation_issues[].path	string	Required
validation_issues[].code	string	Required
validation_issues[].severity	string	Required	enum: ["error","warning"]
validation_issues[].message	string	Required
preview_hash	string	Required
expires_at	string	Optional	format: "date-time"
status	string	Required	enum: ["pending","invalid","replaced","committed","discarded"]
committed_at	string	Optional	format: "date-time"
saved_entity_ids	object	Optional
outcome	object	Optional

POST /v1/farm/{farm_id}/workflows/previews/{preview_id}/commit

Commit an approved workflow preview

External credential scopes: write:records, write:animals and write:groups. Minimum farm role: EDITOR. Requires an explicit approval of the exact preview_hash. Rechecks access, template activity, expiry, relevant state and reuses the single atomic birth writer.

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

Request body (application/json)

Field	Type	Presence	Constraints
approval	object	Required
approval.confirmed	boolean	Required	const: true
approval.preview_hash	string	Required

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>/workflows/previews/<preview_id>/commit' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

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
409	Concurrent change, archived template, expired preview, or conflicting approval.	application/json

200 response schema (application/json)

Field	Type	Presence	Constraints
preview_id	string	Required	format: "uuid"
status	string	Required	const: "committed"
saved_entity_ids	object	Required
outcome	object	Optional

POST /v1/farm/{farm_id}/workflows/previews/{preview_id}/discard

Discard an uncommitted workflow preview

External credential scope: read:records. Minimum farm role: EDITOR. Invalidates an uncommitted preview without livestock writes.

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

Request example

bash example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/workflows/previews/<preview_id>/discard' \
  -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
409	Concurrent change, archived template, expired preview, or conflicting approval.	application/json

200 response schema (application/json)

Field	Type	Presence	Constraints
preview_id	string	Required	format: "uuid"
status	string	Required
discarded_at	string	Optional	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"
    }
  ]
}