Ranch.Bot
Skip to reference

Chute sessions API

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

GET /v1/farm/{farm_id}/chute-sessions

Get Chute Sessions

Current chute sessions HTTP operation. External credential scopes: read:records. Minimum farm role: READER. Pagination accepts integer skip and take; set both explicitly. An omitted value passes through to the data query. Collection property names differ by resource; use the response schema. Production rate limit: 100 requests per 15-minute window, per legacy key, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429.

ParameterInRequiredSchema
farm_idpathYes{"type":"string","format":"uuid"}
skipqueryNo{"type":"integer"}
takequeryNo{"type":"integer"}
statusqueryNo{"type":"string","enum":["ACTIVE","COMPLETED","PROPOSED"]}

Request example

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

Responses

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

200 response schema (application/json)

FieldTypePresenceConstraints
totalnumberRequired
recordsarrayRequired
records[]objectRequired
records[].idstringRequired
records[].namestringRequired
records[].statusstringRequiredenum: ["ACTIVE","COMPLETED","PROPOSED"]
records[].started_atstringRequiredformat: "date-time"
records[].completed_at (variant 1)nullRequired
records[].completed_at (variant 2)stringRequiredformat: "date-time"
records[].group_id (variant 1)nullRequired
records[].group_id (variant 2)stringRequired
records[].entry_countnumberRequired
json example
{
  "total": 0,
  "records": []
}

POST /v1/farm/{farm_id}/chute-sessions

Create Chute Session

Current chute sessions HTTP operation. External credential scopes: write:records. Minimum farm role: EDITOR. Direct requests execute without an app confirmation screen. Production rate limit: 100 requests per 15-minute window, per legacy key, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429.

ParameterInRequiredSchema
farm_idpathYes{"type":"string","format":"uuid"}

Request body (application/json)

FieldTypePresenceConstraints
namestringOptionalminLength: 1
configobjectRequired
config.widgetsarrayRequiredminItems: 1
config.widgets[]objectRequired
config.widgets[].idstringRequiredminLength: 1
config.widgets[].typestringRequiredenum: ["boolean","number","photo","score","select","text","treatment","weight"]
config.widgets[].labelstringRequiredminLength: 1
config.widgets[].sizestringOptionalenum: ["full","half"]
config.widgets[].optionsobjectOptional
config.new_animal_fieldsarrayOptional
config.new_animal_fields[]stringRequired
config.record_typestringOptionalenum: ["FEED","GENETIC","HEALTH","MOVEMENT","OTHER"]
group_idstringOptionalformat: "uuid"
json example
{
  "config": {
    "widgets": [
      {
        "id": "11111111-1111-4111-8111-111111111111",
        "type": "boolean",
        "label": "example"
      }
    ]
  }
}

Request example

bash example
curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/chute-sessions' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"config":{"widgets":[{"id":"11111111-1111-4111-8111-111111111111","type":"boolean","label":"example"}]}}'

Responses

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

201 response schema (application/json)

FieldTypePresenceConstraints
statusstringRequiredenum: ["ACTIVE","COMPLETED","PROPOSED"]
idstringRequired
created_atstringRequiredformat: "date-time"
updated_atstringRequiredformat: "date-time"
namestringRequired
is_activebooleanRequired
farm_idstringRequired
group_id (variant 1)nullRequired
group_id (variant 2)stringRequired
completed_at (variant 1)nullRequired
completed_at (variant 2)stringRequiredformat: "date-time"
configJSONRequired
started_atstringRequiredformat: "date-time"
json example
{
  "status": "ACTIVE",
  "id": "11111111-1111-4111-8111-111111111111",
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:00:00.000Z",
  "name": "Example",
  "is_active": true,
  "farm_id": "11111111-1111-4111-8111-111111111111",
  "group_id": null,
  "completed_at": null,
  "config": null,
  "started_at": "2026-09-01T12:00:00.000Z"
}

DELETE /v1/farm/{farm_id}/chute-sessions/{session_id}

Delete Chute Session

Current chute sessions HTTP operation. External credential scopes: write:records. Minimum farm role: EDITOR. Direct requests execute without an app confirmation screen. Production rate limit: 100 requests per 15-minute window, per legacy key, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429. Deletion behavior is described below; a successful status does not imply erasure from all retained history. Deletes the chute session through its service; associated history has separate undo behavior. Only PROPOSED sessions can be changed or deactivated; started sessions reject this operation with 400.

ParameterInRequiredSchema
farm_idpathYes{"type":"string","format":"uuid"}
session_idpathYes{"type":"string","format":"uuid"}

Request example

bash example
curl --fail-with-body -X DELETE \
  'https://api.ranch.bot/v1/farm/<farm_id>/chute-sessions/<session_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

StatusMeaningContent type
204Completed; no response body.No body
400Request validation failed.application/json
401Missing/invalid authentication or insufficient farm role.application/json
403Missing required scope or credential type is disallowed.application/json
404Resource or active farm membership not found.application/json
429Rate limit exceeded. Retry after the indicated delay.application/json
500Unexpected server failure.application/json

GET /v1/farm/{farm_id}/chute-sessions/{session_id}

Get Chute Session

Current chute sessions HTTP operation. External credential scopes: read:records. Minimum farm role: READER. Production rate limit: 100 requests per 15-minute window, per legacy key, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429.

ParameterInRequiredSchema
farm_idpathYes{"type":"string","format":"uuid"}
session_idpathYes{"type":"string","format":"uuid"}

Request example

bash example
curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/chute-sessions/<session_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

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

200 response schema (application/json)

FieldTypePresenceConstraints
statusstringRequiredenum: ["ACTIVE","COMPLETED","PROPOSED"]
idstringRequired
created_atstringRequiredformat: "date-time"
updated_atstringRequiredformat: "date-time"
namestringRequired
is_activebooleanRequired
farm_idstringRequired
group_id (variant 1)nullRequired
group_id (variant 2)stringRequired
completed_at (variant 1)nullRequired
completed_at (variant 2)stringRequiredformat: "date-time"
configJSONRequired
started_atstringRequiredformat: "date-time"
entriesarrayRequired
entries[]objectRequired
entries[].idstringRequired
entries[].animal_idstringRequired
entries[].session_idstringRequired
entries[].captured_atstringRequiredformat: "date-time"
entries[].client_updated_atstringRequiredformat: "date-time"
entries[].is_activebooleanRequired
entries[].payloadJSONRequired
entries[].positionintegerRequired
entries[].record_idsarrayRequired
entries[].record_ids[]stringRequired
entries[].created_atstringRequiredformat: "date-time"
entries[].updated_atstringRequiredformat: "date-time"
entries[].animalJSONRequired
entries[].animalobjectRequired
entries[].animal.id (variant 1)stringRequired
entries[].animal.id (variant 2)nullRequired
entries[].animal.farm_id (variant 1)stringRequired
entries[].animal.farm_id (variant 2)nullRequired
entries[].animal.is_active (variant 1)booleanRequired
entries[].animal.is_active (variant 2)nullRequired
entries[].animal.metadata (variant 1)JSONRequired
entries[].animal.metadata (variant 2)nullRequired
entries[].animal.created_at (variant 1)stringRequiredformat: "date-time"
entries[].animal.created_at (variant 2)nullRequired
entries[].animal.updated_at (variant 1)stringRequiredformat: "date-time"
entries[].animal.updated_at (variant 2)nullRequired
entries[].animalobjectRequired
entries[].animal.animal_identifiersarrayRequired
entries[].animal.animal_identifiers[]objectRequired
entries[].animal.animal_identifiers[].id (variant 1)stringRequired
entries[].animal.animal_identifiers[].id (variant 2)nullRequired
entries[].animal.animal_identifiers[].animal_id (variant 1)stringRequired
entries[].animal.animal_identifiers[].animal_id (variant 2)nullRequired
entries[].animal.animal_identifiers[].is_active (variant 1)booleanRequired
entries[].animal.animal_identifiers[].is_active (variant 2)nullRequired
entries[].animal.animal_identifiers[].is_primary (variant 1)booleanRequired
entries[].animal.animal_identifiers[].is_primary (variant 2)nullRequired
entries[].animal.animal_identifiers[].type (variant 1)stringRequired
entries[].animal.animal_identifiers[].type (variant 2)nullRequired
entries[].animal.animal_identifiers[].value (variant 1)stringRequired
entries[].animal.animal_identifiers[].value (variant 2)nullRequired
entries[].animal.animal_identifiers[].created_at (variant 1)stringRequiredformat: "date-time"
entries[].animal.animal_identifiers[].created_at (variant 2)nullRequired
entries[].animal.animal_identifiers[].updated_at (variant 1)stringRequiredformat: "date-time"
entries[].animal.animal_identifiers[].updated_at (variant 2)nullRequired
json example
{
  "status": "ACTIVE",
  "id": "11111111-1111-4111-8111-111111111111",
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:00:00.000Z",
  "name": "Weighing",
  "is_active": true,
  "farm_id": "11111111-1111-4111-8111-111111111111",
  "group_id": null,
  "completed_at": null,
  "config": {
    "widgets": []
  },
  "started_at": "2026-09-01T12:00:00.000Z",
  "entries": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "animal_id": "11111111-1111-4111-8111-111111111111",
      "session_id": "11111111-1111-4111-8111-111111111111",
      "captured_at": "2026-09-01T12:00:00.000Z",
      "client_updated_at": "2026-09-01T12:00:00.000Z",
      "is_active": true,
      "payload": {
        "weight": 125
      },
      "position": 0,
      "record_ids": [
        "11111111-1111-4111-8111-111111111111"
      ],
      "created_at": "2026-09-01T12:00:00.000Z",
      "updated_at": "2026-09-01T12:00:00.000Z",
      "animal": {
        "id": "11111111-1111-4111-8111-111111111111",
        "farm_id": "11111111-1111-4111-8111-111111111111",
        "is_active": true,
        "metadata": null,
        "created_at": "2026-09-01T12:00:00.000Z",
        "updated_at": "2026-09-01T12:00:00.000Z",
        "animal_identifiers": [
          {
            "id": "11111111-1111-4111-8111-111111111111",
            "animal_id": "11111111-1111-4111-8111-111111111111",
            "is_active": true,
            "is_primary": true,
            "type": "MANAGEMENT_TAG",
            "value": "Ewe 42",
            "created_at": "2026-09-01T12:00:00.000Z",
            "updated_at": "2026-09-01T12:00:00.000Z"
          }
        ]
      }
    }
  ]
}

PUT /v1/farm/{farm_id}/chute-sessions/{session_id}

Update Chute Session

Current chute sessions HTTP operation. External credential scopes: write:records. Minimum farm role: EDITOR. Direct requests execute without an app confirmation screen. Production rate limit: 100 requests per 15-minute window, per legacy key, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429. Only PROPOSED sessions can be changed or deactivated; started sessions reject this operation with 400.

ParameterInRequiredSchema
farm_idpathYes{"type":"string","format":"uuid"}
session_idpathYes{"type":"string","format":"uuid"}

Request body (application/json)

FieldTypePresenceConstraints
namestringOptionalminLength: 1
configobjectOptional
config.widgetsarrayRequiredminItems: 1
config.widgets[]objectRequired
config.widgets[].idstringRequiredminLength: 1
config.widgets[].typestringRequiredenum: ["boolean","number","photo","score","select","text","treatment","weight"]
config.widgets[].labelstringRequiredminLength: 1
config.widgets[].sizestringOptionalenum: ["full","half"]
config.widgets[].optionsobjectOptional
config.new_animal_fieldsarrayOptional
config.new_animal_fields[]stringRequired
config.record_typestringOptionalenum: ["FEED","GENETIC","HEALTH","MOVEMENT","OTHER"]
group_id (variant 1)stringOptionalformat: "uuid"
group_id (variant 2)nullOptional
json example
{}

Request example

bash example
curl --fail-with-body -X PUT \
  'https://api.ranch.bot/v1/farm/<farm_id>/chute-sessions/<session_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'

Responses

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

200 response schema (application/json)

FieldTypePresenceConstraints
statusstringRequiredenum: ["ACTIVE","COMPLETED","PROPOSED"]
idstringRequired
created_atstringRequiredformat: "date-time"
updated_atstringRequiredformat: "date-time"
namestringRequired
is_activebooleanRequired
farm_idstringRequired
group_id (variant 1)nullRequired
group_id (variant 2)stringRequired
completed_at (variant 1)nullRequired
completed_at (variant 2)stringRequiredformat: "date-time"
configJSONRequired
started_atstringRequiredformat: "date-time"
json example
{
  "status": "ACTIVE",
  "id": "11111111-1111-4111-8111-111111111111",
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:00:00.000Z",
  "name": "Example",
  "is_active": true,
  "farm_id": "11111111-1111-4111-8111-111111111111",
  "group_id": null,
  "completed_at": null,
  "config": null,
  "started_at": "2026-09-01T12:00:00.000Z"
}

POST /v1/farm/{farm_id}/chute-sessions/{session_id}/entries/{entry_id}/undo

Undo Chute Entry

Current chute sessions HTTP operation. External credential scopes: write:records. Minimum farm role: EDITOR. Direct requests execute without an app confirmation screen. Production rate limit: 100 requests per 15-minute window, per legacy key, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429.

ParameterInRequiredSchema
farm_idpathYes{"type":"string","format":"uuid"}
session_idpathYes{"type":"string","format":"uuid"}
entry_idpathYes{"type":"string","format":"uuid"}

Request example

bash example
curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/chute-sessions/<session_id>/entries/<entry_id>/undo' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

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

200 response schema (application/json)

FieldTypePresenceConstraints
entry_idstringRequired
undonebooleanRequired
json example
{
  "entry_id": "11111111-1111-4111-8111-111111111111",
  "undone": true
}

POST /v1/farm/{farm_id}/chute-sessions/{session_id}/sync

Sync Chute Session

Current chute sessions HTTP operation. External credential scopes: write:records, write:animals, write:groups. Minimum farm role: EDITOR. Direct requests execute without an app confirmation screen. Production rate limit: 100 requests per 15-minute window, per legacy key, otherwise per client IP. RateLimit headers report the current window; respect Retry-After on 429.

ParameterInRequiredSchema
farm_idpathYes{"type":"string","format":"uuid"}
session_idpathYes{"type":"string","format":"uuid"}

Request body (application/json)

FieldTypePresenceConstraints
sessionobjectRequired
session.namestringRequiredminLength: 1
session.statusstringRequiredenum: ["ACTIVE","COMPLETED"]
session.started_atstringRequiredformat: "date-time"
session.completed_atstringOptionalformat: "date-time"
session.configobjectRequired
session.config.widgetsarrayRequiredminItems: 1
session.config.widgets[]objectRequired
session.config.widgets[].idstringRequiredminLength: 1
session.config.widgets[].typestringRequiredenum: ["boolean","number","photo","score","select","text","treatment","weight"]
session.config.widgets[].labelstringRequiredminLength: 1
session.config.widgets[].sizestringOptionalenum: ["full","half"]
session.config.widgets[].optionsobjectOptional
session.config.new_animal_fieldsarrayOptional
session.config.new_animal_fields[]stringRequired
session.config.record_typestringOptionalenum: ["FEED","GENETIC","HEALTH","MOVEMENT","OTHER"]
session.group_id (variant 1)stringOptionalformat: "uuid"
session.group_id (variant 2)nullOptional
entriesarrayRequired
entries[]objectRequired
entries[].idstringRequiredformat: "uuid"
entries[].animalobjectRequired
entries[].animal.idstringRequiredformat: "uuid"
entries[].animal.is_newbooleanOptional
entries[].animal.identifiersarrayOptional
entries[].animal.identifiers[]objectRequired
entries[].animal.identifiers[].typestringRequiredenum: ["BRAND","EID","MANAGEMENT_TAG","NAME","TATTOO"]
entries[].animal.identifiers[].valuestringRequiredminLength: 1
entries[].animal.metadataobjectOptional
entries[].positionintegerRequiredminimum: 0
entries[].payloadobjectRequired
entries[].captured_atstringRequiredformat: "date-time"
entries[].client_updated_atstringRequiredformat: "date-time"
entries[].deletedbooleanOptional
json example
{
  "session": {
    "name": "Example",
    "status": "ACTIVE",
    "started_at": "2026-09-01T12:00:00.000Z",
    "config": {
      "widgets": [
        {
          "id": "11111111-1111-4111-8111-111111111111",
          "type": "boolean",
          "label": "example"
        }
      ]
    }
  },
  "entries": []
}

Request example

bash example
curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/chute-sessions/<session_id>/sync' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"session":{"name":"Example","status":"ACTIVE","started_at":"2026-09-01T12:00:00.000Z","config":{"widgets":[{"id":"11111111-1111-4111-8111-111111111111","type":"boolean","label":"example"}]}},"entries":[]}'

Responses

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

200 response schema (application/json)

FieldTypePresenceConstraints
sessionobjectRequired
session.statusstringRequiredenum: ["ACTIVE","COMPLETED","PROPOSED"]
session.idstringRequired
session.created_atstringRequiredformat: "date-time"
session.updated_atstringRequiredformat: "date-time"
session.namestringRequired
session.is_activebooleanRequired
session.farm_idstringRequired
session.group_id (variant 1)nullRequired
session.group_id (variant 2)stringRequired
session.completed_at (variant 1)nullRequired
session.completed_at (variant 2)stringRequiredformat: "date-time"
session.configJSONRequired
session.started_atstringRequiredformat: "date-time"
animal_mappingsarrayRequired
animal_mappings[]objectRequired
animal_mappings[].client_animal_idstringRequired
animal_mappings[].animal_idstringRequired
animal_mappings[].createdbooleanRequired
resultsarrayRequired
results[]objectRequired
results[].entry_idstringRequired
results[].statusstringRequiredenum: ["error","created","updated","unchanged","deleted"]
results[].animal_idstringOptional
results[].record_idsarrayOptional
results[].record_ids[]stringRequired
results[].record_itemsarrayOptional
results[].record_items[]objectRequired
results[].record_items[].widget_idstringRequired
results[].record_items[].record_item_idstringRequired
results[].errorstringOptional
json example
{
  "session": {
    "status": "ACTIVE",
    "id": "11111111-1111-4111-8111-111111111111",
    "created_at": "2026-09-01T12:00:00.000Z",
    "updated_at": "2026-09-01T12:00:00.000Z",
    "name": "Example",
    "is_active": true,
    "farm_id": "11111111-1111-4111-8111-111111111111",
    "group_id": null,
    "completed_at": null,
    "config": null,
    "started_at": "2026-09-01T12:00:00.000Z"
  },
  "animal_mappings": [],
  "results": []
}

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"
    }
  ]
}