Workflow templates API
HTTP reference for workflow templates. Read authentication and access before using these operations. All examples use made-up data and placeholder credentials.
- GET /v1/farm/{farm_id}/workflow-templates
- POST /v1/farm/{farm_id}/workflow-templates
- GET /v1/farm/{farm_id}/workflow-templates/{template_id}
- POST /v1/farm/{farm_id}/workflow-templates/{template_id}/versions
- PUT /v1/farm/{farm_id}/workflow-templates/{template_id}/state
- PUT /v1/farm/{farm_id}/workflow-templates/{template_id}/default
GET /v1/farm/{farm_id}/workflow-templates
List workflow templates
External credential scopes: read:farms. Minimum farm role: READER. Template labels, visibility, requiredness, defaults and units are configuration; core field meanings never change.
| 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} |
| workflow | query | No | {"type":"string","maxLength":80} |
Request example
bash example
curl --fail-with-body -X GET \
'https://api.ranch.bot/v1/farm/<farm_id>/workflow-templates' \
-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 |
|---|---|---|---|
| total | integer | Required | minimum: 0 |
| records | array | Required | |
| records[] | object | Required | |
| records[].id | string | Required | format: "uuid" |
| records[].workflow | string | Required | |
| records[].name | string | Required | |
| records[].is_active | boolean | Required | |
| records[].is_default | boolean | Required | |
| records[].metadata_revision | integer | Required | |
| records[].current_version (variant 1) | null | Optional | |
| records[].current_version (variant 2) | object | Optional | |
| records[].current_version (variant 2).id | string | Required | format: "uuid" |
| records[].current_version (variant 2).version | integer | Required | |
| records[].current_version (variant 2).definition | object | Required | |
| records[].current_version (variant 2).definition.schema_version | integer | Required | const: 1 |
| records[].current_version (variant 2).definition.workflow | string | Required | const: "record_birth" |
| records[].current_version (variant 2).definition.name | string | Required | minLength: 1; maxLength: 80 |
| records[].current_version (variant 2).definition.fields | array | Required | minItems: 1 |
| records[].current_version (variant 2).definition.fields[] | object | Required | |
| records[].current_version (variant 2).definition.fields[].key | string | Required | minLength: 1; maxLength: 80 |
| records[].current_version (variant 2).definition.fields[].scope | string | Required | enum: ["event","offspring"] |
| records[].current_version (variant 2).definition.fields[].label | string | Required | minLength: 1; maxLength: 80 |
| records[].current_version (variant 2).definition.fields[].required | boolean | Optional | |
| records[].current_version (variant 2).definition.fields[].hidden | boolean | Optional | |
| records[].current_version (variant 2).definition.fields[].default | object | Optional | |
| records[].current_version (variant 2).definition.fields[].unit | string | Optional | enum: ["kg","lb"] |
| records[].current_version (variant 2).definition.fields[].type | string | Optional | enum: ["text","number","boolean","date","choice"] |
| records[].current_version (variant 2).definition.fields[].choices | array | Optional | minItems: 1 |
| records[].current_version (variant 2).definition.fields[].choices[] | object | Required | |
| records[].current_version (variant 2).definition.fields[].choices[].key | string | Required | |
| records[].current_version (variant 2).definition.fields[].choices[].label | string | Required | |
| records[].current_version (variant 2).created_at | string | Optional | format: "date-time" |
| records[].versions | array | Optional | |
| records[].versions[] | object | Required | |
| records[].created_at | string | Optional | format: "date-time" |
| records[].updated_at | string | Optional | format: "date-time" |
POST /v1/farm/{farm_id}/workflow-templates
Create a workflow template
Owner-only farm configuration. External credential scope: write:farms. Publishing is optimistic on expected_current_version; state/default changes are optimistic on expected_metadata_revision. Conflicts return 409.
| Parameter | In | Required | Schema |
|---|---|---|---|
| farm_id | path | Yes | {"type":"string","format":"uuid"} |
Request body (application/json)
| Field | Type | Presence | Constraints |
|---|---|---|---|
| definition | object | Required | |
| definition.schema_version | integer | Required | const: 1 |
| definition.workflow | string | Required | const: "record_birth" |
| definition.name | string | Required | minLength: 1; maxLength: 80 |
| definition.fields | array | Required | minItems: 1 |
| definition.fields[] | object | Required | |
| definition.fields[].key | string | Required | minLength: 1; maxLength: 80 |
| definition.fields[].scope | string | Required | enum: ["event","offspring"] |
| definition.fields[].label | string | Required | minLength: 1; maxLength: 80 |
| definition.fields[].required | boolean | Optional | |
| definition.fields[].hidden | boolean | Optional | |
| definition.fields[].default | object | Optional | |
| definition.fields[].unit | string | Optional | enum: ["kg","lb"] |
| definition.fields[].type | string | Optional | enum: ["text","number","boolean","date","choice"] |
| definition.fields[].choices | array | Optional | minItems: 1 |
| definition.fields[].choices[] | object | Required | |
| definition.fields[].choices[].key | string | Required | |
| definition.fields[].choices[].label | string | Required | |
| is_default | boolean | Optional |
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>/workflow-templates' \
-H "Authorization: Bearer $RANCHBOT_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @request.jsonResponses
| 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 |
|---|---|---|---|
| id | string | Required | format: "uuid" |
| workflow | string | Required | |
| name | string | Required | |
| is_active | boolean | Required | |
| is_default | boolean | Required | |
| metadata_revision | integer | Required | |
| current_version (variant 1) | null | Optional | |
| current_version (variant 2) | object | Optional | |
| current_version (variant 2).id | string | Required | format: "uuid" |
| current_version (variant 2).version | integer | Required | |
| current_version (variant 2).definition | object | Required | |
| current_version (variant 2).definition.schema_version | integer | Required | const: 1 |
| current_version (variant 2).definition.workflow | string | Required | const: "record_birth" |
| current_version (variant 2).definition.name | string | Required | minLength: 1; maxLength: 80 |
| current_version (variant 2).definition.fields | array | Required | minItems: 1 |
| current_version (variant 2).definition.fields[] | object | Required | |
| current_version (variant 2).definition.fields[].key | string | Required | minLength: 1; maxLength: 80 |
| current_version (variant 2).definition.fields[].scope | string | Required | enum: ["event","offspring"] |
| current_version (variant 2).definition.fields[].label | string | Required | minLength: 1; maxLength: 80 |
| current_version (variant 2).definition.fields[].required | boolean | Optional | |
| current_version (variant 2).definition.fields[].hidden | boolean | Optional | |
| current_version (variant 2).definition.fields[].default | object | Optional | |
| current_version (variant 2).definition.fields[].unit | string | Optional | enum: ["kg","lb"] |
| current_version (variant 2).definition.fields[].type | string | Optional | enum: ["text","number","boolean","date","choice"] |
| current_version (variant 2).definition.fields[].choices | array | Optional | minItems: 1 |
| current_version (variant 2).definition.fields[].choices[] | object | Required | |
| current_version (variant 2).definition.fields[].choices[].key | string | Required | |
| current_version (variant 2).definition.fields[].choices[].label | string | Required | |
| current_version (variant 2).created_at | string | Optional | format: "date-time" |
| versions | array | Optional | |
| versions[] | object | Required | |
| created_at | string | Optional | format: "date-time" |
| updated_at | string | Optional | format: "date-time" |
GET /v1/farm/{farm_id}/workflow-templates/{template_id}
Read a workflow template
External credential scopes: read:farms. Minimum farm role: READER. Template labels, visibility, requiredness, defaults and units are configuration; core field meanings never change.
| Parameter | In | Required | Schema |
|---|---|---|---|
| farm_id | path | Yes | {"type":"string","format":"uuid"} |
| template_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>/workflow-templates/<template_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 |
|---|---|---|---|
| id | string | Required | format: "uuid" |
| workflow | string | Required | |
| name | string | Required | |
| is_active | boolean | Required | |
| is_default | boolean | Required | |
| metadata_revision | integer | Required | |
| current_version (variant 1) | null | Optional | |
| current_version (variant 2) | object | Optional | |
| current_version (variant 2).id | string | Required | format: "uuid" |
| current_version (variant 2).version | integer | Required | |
| current_version (variant 2).definition | object | Required | |
| current_version (variant 2).definition.schema_version | integer | Required | const: 1 |
| current_version (variant 2).definition.workflow | string | Required | const: "record_birth" |
| current_version (variant 2).definition.name | string | Required | minLength: 1; maxLength: 80 |
| current_version (variant 2).definition.fields | array | Required | minItems: 1 |
| current_version (variant 2).definition.fields[] | object | Required | |
| current_version (variant 2).definition.fields[].key | string | Required | minLength: 1; maxLength: 80 |
| current_version (variant 2).definition.fields[].scope | string | Required | enum: ["event","offspring"] |
| current_version (variant 2).definition.fields[].label | string | Required | minLength: 1; maxLength: 80 |
| current_version (variant 2).definition.fields[].required | boolean | Optional | |
| current_version (variant 2).definition.fields[].hidden | boolean | Optional | |
| current_version (variant 2).definition.fields[].default | object | Optional | |
| current_version (variant 2).definition.fields[].unit | string | Optional | enum: ["kg","lb"] |
| current_version (variant 2).definition.fields[].type | string | Optional | enum: ["text","number","boolean","date","choice"] |
| current_version (variant 2).definition.fields[].choices | array | Optional | minItems: 1 |
| current_version (variant 2).definition.fields[].choices[] | object | Required | |
| current_version (variant 2).definition.fields[].choices[].key | string | Required | |
| current_version (variant 2).definition.fields[].choices[].label | string | Required | |
| current_version (variant 2).created_at | string | Optional | format: "date-time" |
| versions | array | Optional | |
| versions[] | object | Required | |
| created_at | string | Optional | format: "date-time" |
| updated_at | string | Optional | format: "date-time" |
POST /v1/farm/{farm_id}/workflow-templates/{template_id}/versions
Publish a workflow template version
Owner-only farm configuration. External credential scope: write:farms. Publishing is optimistic on expected_current_version; state/default changes are optimistic on expected_metadata_revision. Conflicts return 409. Versions are immutable; expect 409 when expected_current_version is stale.
| Parameter | In | Required | Schema |
|---|---|---|---|
| farm_id | path | Yes | {"type":"string","format":"uuid"} |
| template_id | path | Yes | {"type":"string","format":"uuid"} |
Request body (application/json)
| Field | Type | Presence | Constraints |
|---|---|---|---|
| expected_current_version | integer | Required | minimum: 0 |
| definition | object | Required | |
| definition.schema_version | integer | Required | const: 1 |
| definition.workflow | string | Required | const: "record_birth" |
| definition.name | string | Required | minLength: 1; maxLength: 80 |
| definition.fields | array | Required | minItems: 1 |
| definition.fields[] | object | Required | |
| definition.fields[].key | string | Required | minLength: 1; maxLength: 80 |
| definition.fields[].scope | string | Required | enum: ["event","offspring"] |
| definition.fields[].label | string | Required | minLength: 1; maxLength: 80 |
| definition.fields[].required | boolean | Optional | |
| definition.fields[].hidden | boolean | Optional | |
| definition.fields[].default | object | Optional | |
| definition.fields[].unit | string | Optional | enum: ["kg","lb"] |
| definition.fields[].type | string | Optional | enum: ["text","number","boolean","date","choice"] |
| definition.fields[].choices | array | Optional | minItems: 1 |
| definition.fields[].choices[] | object | Required | |
| definition.fields[].choices[].key | string | Required | |
| definition.fields[].choices[].label | 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>/workflow-templates/<template_id>/versions' \
-H "Authorization: Bearer $RANCHBOT_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @request.jsonResponses
| 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 |
|---|---|---|---|
| id | string | Required | format: "uuid" |
| workflow | string | Required | |
| name | string | Required | |
| is_active | boolean | Required | |
| is_default | boolean | Required | |
| metadata_revision | integer | Required | |
| current_version (variant 1) | null | Optional | |
| current_version (variant 2) | object | Optional | |
| current_version (variant 2).id | string | Required | format: "uuid" |
| current_version (variant 2).version | integer | Required | |
| current_version (variant 2).definition | object | Required | |
| current_version (variant 2).definition.schema_version | integer | Required | const: 1 |
| current_version (variant 2).definition.workflow | string | Required | const: "record_birth" |
| current_version (variant 2).definition.name | string | Required | minLength: 1; maxLength: 80 |
| current_version (variant 2).definition.fields | array | Required | minItems: 1 |
| current_version (variant 2).definition.fields[] | object | Required | |
| current_version (variant 2).definition.fields[].key | string | Required | minLength: 1; maxLength: 80 |
| current_version (variant 2).definition.fields[].scope | string | Required | enum: ["event","offspring"] |
| current_version (variant 2).definition.fields[].label | string | Required | minLength: 1; maxLength: 80 |
| current_version (variant 2).definition.fields[].required | boolean | Optional | |
| current_version (variant 2).definition.fields[].hidden | boolean | Optional | |
| current_version (variant 2).definition.fields[].default | object | Optional | |
| current_version (variant 2).definition.fields[].unit | string | Optional | enum: ["kg","lb"] |
| current_version (variant 2).definition.fields[].type | string | Optional | enum: ["text","number","boolean","date","choice"] |
| current_version (variant 2).definition.fields[].choices | array | Optional | minItems: 1 |
| current_version (variant 2).definition.fields[].choices[] | object | Required | |
| current_version (variant 2).definition.fields[].choices[].key | string | Required | |
| current_version (variant 2).definition.fields[].choices[].label | string | Required | |
| current_version (variant 2).created_at | string | Optional | format: "date-time" |
| versions | array | Optional | |
| versions[] | object | Required | |
| created_at | string | Optional | format: "date-time" |
| updated_at | string | Optional | format: "date-time" |
PUT /v1/farm/{farm_id}/workflow-templates/{template_id}/state
Archive or reactivate a workflow template
Owner-only farm configuration. External credential scope: write:farms. Publishing is optimistic on expected_current_version; state/default changes are optimistic on expected_metadata_revision. Conflicts return 409. Archiving the default template requires an active replacement_template_id in the same transaction.
| Parameter | In | Required | Schema |
|---|---|---|---|
| farm_id | path | Yes | {"type":"string","format":"uuid"} |
| template_id | path | Yes | {"type":"string","format":"uuid"} |
Request body (application/json)
| Field | Type | Presence | Constraints |
|---|---|---|---|
| expected_metadata_revision | integer | Required | minimum: 0 |
| is_active | boolean | Required | |
| replacement_template_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 PUT \
'https://api.ranch.bot/v1/farm/<farm_id>/workflow-templates/<template_id>/state' \
-H "Authorization: Bearer $RANCHBOT_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @request.jsonResponses
| 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 |
|---|---|---|---|
| id | string | Required | format: "uuid" |
| workflow | string | Required | |
| name | string | Required | |
| is_active | boolean | Required | |
| is_default | boolean | Required | |
| metadata_revision | integer | Required | |
| current_version (variant 1) | null | Optional | |
| current_version (variant 2) | object | Optional | |
| current_version (variant 2).id | string | Required | format: "uuid" |
| current_version (variant 2).version | integer | Required | |
| current_version (variant 2).definition | object | Required | |
| current_version (variant 2).definition.schema_version | integer | Required | const: 1 |
| current_version (variant 2).definition.workflow | string | Required | const: "record_birth" |
| current_version (variant 2).definition.name | string | Required | minLength: 1; maxLength: 80 |
| current_version (variant 2).definition.fields | array | Required | minItems: 1 |
| current_version (variant 2).definition.fields[] | object | Required | |
| current_version (variant 2).definition.fields[].key | string | Required | minLength: 1; maxLength: 80 |
| current_version (variant 2).definition.fields[].scope | string | Required | enum: ["event","offspring"] |
| current_version (variant 2).definition.fields[].label | string | Required | minLength: 1; maxLength: 80 |
| current_version (variant 2).definition.fields[].required | boolean | Optional | |
| current_version (variant 2).definition.fields[].hidden | boolean | Optional | |
| current_version (variant 2).definition.fields[].default | object | Optional | |
| current_version (variant 2).definition.fields[].unit | string | Optional | enum: ["kg","lb"] |
| current_version (variant 2).definition.fields[].type | string | Optional | enum: ["text","number","boolean","date","choice"] |
| current_version (variant 2).definition.fields[].choices | array | Optional | minItems: 1 |
| current_version (variant 2).definition.fields[].choices[] | object | Required | |
| current_version (variant 2).definition.fields[].choices[].key | string | Required | |
| current_version (variant 2).definition.fields[].choices[].label | string | Required | |
| current_version (variant 2).created_at | string | Optional | format: "date-time" |
| versions | array | Optional | |
| versions[] | object | Required | |
| created_at | string | Optional | format: "date-time" |
| updated_at | string | Optional | format: "date-time" |
PUT /v1/farm/{farm_id}/workflow-templates/{template_id}/default
Select the farm default workflow template
Owner-only farm configuration. External credential scope: write:farms. Publishing is optimistic on expected_current_version; state/default changes are optimistic on expected_metadata_revision. Conflicts return 409.
| Parameter | In | Required | Schema |
|---|---|---|---|
| farm_id | path | Yes | {"type":"string","format":"uuid"} |
| template_id | path | Yes | {"type":"string","format":"uuid"} |
Request body (application/json)
| Field | Type | Presence | Constraints |
|---|---|---|---|
| expected_metadata_revision | integer | Required | minimum: 0 |
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 PUT \
'https://api.ranch.bot/v1/farm/<farm_id>/workflow-templates/<template_id>/default' \
-H "Authorization: Bearer $RANCHBOT_TOKEN" \
-H "Content-Type: application/json" \
--data-binary @request.jsonResponses
| 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 |
|---|---|---|---|
| id | string | Required | format: "uuid" |
| workflow | string | Required | |
| name | string | Required | |
| is_active | boolean | Required | |
| is_default | boolean | Required | |
| metadata_revision | integer | Required | |
| current_version (variant 1) | null | Optional | |
| current_version (variant 2) | object | Optional | |
| current_version (variant 2).id | string | Required | format: "uuid" |
| current_version (variant 2).version | integer | Required | |
| current_version (variant 2).definition | object | Required | |
| current_version (variant 2).definition.schema_version | integer | Required | const: 1 |
| current_version (variant 2).definition.workflow | string | Required | const: "record_birth" |
| current_version (variant 2).definition.name | string | Required | minLength: 1; maxLength: 80 |
| current_version (variant 2).definition.fields | array | Required | minItems: 1 |
| current_version (variant 2).definition.fields[] | object | Required | |
| current_version (variant 2).definition.fields[].key | string | Required | minLength: 1; maxLength: 80 |
| current_version (variant 2).definition.fields[].scope | string | Required | enum: ["event","offspring"] |
| current_version (variant 2).definition.fields[].label | string | Required | minLength: 1; maxLength: 80 |
| current_version (variant 2).definition.fields[].required | boolean | Optional | |
| current_version (variant 2).definition.fields[].hidden | boolean | Optional | |
| current_version (variant 2).definition.fields[].default | object | Optional | |
| current_version (variant 2).definition.fields[].unit | string | Optional | enum: ["kg","lb"] |
| current_version (variant 2).definition.fields[].type | string | Optional | enum: ["text","number","boolean","date","choice"] |
| current_version (variant 2).definition.fields[].choices | array | Optional | minItems: 1 |
| current_version (variant 2).definition.fields[].choices[] | object | Required | |
| current_version (variant 2).definition.fields[].choices[].key | string | Required | |
| current_version (variant 2).definition.fields[].choices[].label | string | Required | |
| current_version (variant 2).created_at | string | Optional | format: "date-time" |
| versions | array | Optional | |
| versions[] | object | Required | |
| created_at | string | Optional | format: "date-time" |
| updated_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"
}
]
}