Ranch.Bot
Skip to reference

Legacy imports API

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

GET /v1/farm/{farm_id}/import

Get Imports

Current legacy imports 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":["COMPLETED","FAILED","PENDING","PROCESSING"]}

Request example

bash example
curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/import' \
  -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
recordsarrayRequired
records[]objectRequired
records[].statusstringRequiredenum: ["COMPLETED","FAILED","PENDING","PROCESSING"]
records[].idstringRequired
records[].created_atstringRequiredformat: "date-time"
records[].updated_atstringRequiredformat: "date-time"
records[].user_idstringRequired
records[].farm_idstringRequired
records[].metadataJSONRequired
records[].completed_at (variant 1)nullRequired
records[].completed_at (variant 2)stringRequiredformat: "date-time"
records[].file_idstringRequired
records[].error_message (variant 1)nullRequired
records[].error_message (variant 2)stringRequired
records[].formatstringRequiredenum: ["CSV","JSON"]
records[].fileobjectRequired
records[].file.id (variant 1)stringRequired
records[].file.id (variant 2)nullRequired
records[].file.is_active (variant 1)booleanRequired
records[].file.is_active (variant 2)nullRequired
records[].file.mime_type (variant 1)stringRequired
records[].file.mime_type (variant 2)nullRequired
records[].file.name (variant 1)stringRequired
records[].file.name (variant 2)nullRequired
records[].file.size (variant 1)integerRequired
records[].file.size (variant 2)nullRequired
records[].file.url (variant 1)stringRequired
records[].file.url (variant 2)nullRequired
records[].file.created_at (variant 1)stringRequiredformat: "date-time"
records[].file.created_at (variant 2)nullRequired
records[].file.updated_at (variant 1)stringRequiredformat: "date-time"
records[].file.updated_at (variant 2)nullRequired
records[].userobjectRequired
records[].user.idstringRequired
records[].user.full_namestring or nullRequired
records[].user.phone_number_localstring or nullRequired
totalnumberRequired
json example
{
  "records": [
    {
      "status": "PENDING",
      "id": "11111111-1111-4111-8111-111111111111",
      "created_at": "2026-09-01T12:00:00.000Z",
      "updated_at": "2026-09-01T12:00:00.000Z",
      "user_id": "11111111-1111-4111-8111-111111111111",
      "farm_id": "11111111-1111-4111-8111-111111111111",
      "metadata": null,
      "completed_at": null,
      "file_id": "11111111-1111-4111-8111-111111111111",
      "error_message": null,
      "format": "CSV",
      "file": {
        "id": "11111111-1111-4111-8111-111111111111",
        "name": "flock.csv",
        "mime_type": "text/csv",
        "size": 128,
        "url": "https://example.com/flock.csv",
        "is_active": true,
        "created_at": "2026-09-01T12:00:00.000Z",
        "updated_at": "2026-09-01T12:00:00.000Z"
      },
      "user": {
        "id": "11111111-1111-4111-8111-111111111111",
        "full_name": null,
        "phone_number_local": null
      }
    }
  ],
  "total": 1
}

POST /v1/farm/{farm_id}/import

Create Import

Current legacy imports 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. Known current limitation: upload middleware populates req.file while the handler expects req.files. A normal single-file upload returns 400 No file provided. This route is not a working import walkthrough; use import requests for supervised intake.

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

Request body (multipart/form-data)

FieldTypePresenceConstraints
filestringRequiredformat: "binary"

Request example

bash example
curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/import' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -F 'file=@/path/to/example.csv'

Responses

StatusMeaningContent type
400Errorapplication/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
500Errorapplication/json

400 response schema (application/json)

FieldTypePresenceConstraints
(variant 1) (variant 1)objectRequired
(variant 1) (variant 1).errorsarrayRequired
(variant 1) (variant 1).errors[]objectRequired
(variant 1) (variant 1).errors[].messagestringRequired
(variant 1) (variant 1).datanullRequired
(variant 1) (variant 1).successbooleanRequired
(variant 1) (variant 2)objectRequired
(variant 1) (variant 2).errorsarrayRequired
(variant 1) (variant 2).errors[]objectRequired
(variant 1) (variant 2).errors[].messagestringRequired
(variant 1) (variant 2).datanullRequired
(variant 1) (variant 2).successbooleanRequired
(variant 2)objectRequired
(variant 2).errorsarrayRequired
(variant 2).errors[]objectRequired
(variant 2).errors[].messagestringRequired
(variant 2).datanullRequired
(variant 2).successbooleanRequired
json example
{
  "errors": [],
  "data": null,
  "success": true
}

500 response schema (application/json)

FieldTypePresenceConstraints
errorsarrayRequired
errors[]objectRequired
errors[].messagestringRequired
datanullRequired
successbooleanRequired
json example
{
  "errors": [],
  "data": null,
  "success": true
}

GET /v1/farm/{farm_id}/import/{import_id}

Get Import

Current legacy imports 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"}
import_idpathYes{"type":"string","format":"uuid"}

Request example

bash example
curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/import/<import_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: ["COMPLETED","FAILED","PENDING","PROCESSING"]
idstringRequired
created_atstringRequiredformat: "date-time"
updated_atstringRequiredformat: "date-time"
user_idstringRequired
farm_idstringRequired
metadataJSONRequired
completed_at (variant 1)nullRequired
completed_at (variant 2)stringRequiredformat: "date-time"
file_idstringRequired
error_message (variant 1)nullRequired
error_message (variant 2)stringRequired
formatstringRequiredenum: ["CSV","JSON"]
fileobjectRequired
file.id (variant 1)stringRequired
file.id (variant 2)nullRequired
file.is_active (variant 1)booleanRequired
file.is_active (variant 2)nullRequired
file.mime_type (variant 1)stringRequired
file.mime_type (variant 2)nullRequired
file.name (variant 1)stringRequired
file.name (variant 2)nullRequired
file.size (variant 1)integerRequired
file.size (variant 2)nullRequired
file.url (variant 1)stringRequired
file.url (variant 2)nullRequired
file.created_at (variant 1)stringRequiredformat: "date-time"
file.created_at (variant 2)nullRequired
file.updated_at (variant 1)stringRequiredformat: "date-time"
file.updated_at (variant 2)nullRequired
userobjectRequired
user.idstringRequired
user.full_namestring or nullRequired
user.phone_number_localstring or nullRequired
import_itemsarrayRequired
import_items[]objectRequired
import_items[].idstringRequired
import_items[].action_idstring or nullRequired
import_items[].import_idstringRequired
import_items[].entity_idstringRequired
import_items[].entity_typestringRequiredenum: ["ANIMAL","ANIMAL_IDENTIFIER","GROUP","RECORD","RECORD_ITEM"]
import_items[].error_messagestring or nullRequired
import_items[].mapped_dataJSONRequired
import_items[].row_numberinteger or nullRequired
import_items[].source_dataJSONRequired
import_items[].statusstringRequiredenum: ["FAILED","PENDING","PROCESSED"]
import_items[].created_atstringRequiredformat: "date-time"
import_items[].updated_atstringRequiredformat: "date-time"
import_items[].action (variant 1)objectRequired
import_items[].action (variant 1).idstringRequired
import_items[].action (variant 1).agent_action_idstring or nullRequired
import_items[].action (variant 1).action_typestringRequired
import_items[].action (variant 1).entity_idstringRequired
import_items[].action (variant 1).entity_typestringRequiredenum: ["ANIMAL","ANIMAL_IDENTIFIER","GROUP","RECORD","RECORD_ITEM"]
import_items[].action (variant 1).state_afterJSONRequired
import_items[].action (variant 1).state_beforeJSONRequired
import_items[].action (variant 1).undone_atstring or nullRequiredformat: "date-time"
import_items[].action (variant 1).created_atstringRequiredformat: "date-time"
import_items[].action (variant 1).updated_atstringRequiredformat: "date-time"
import_items[].action (variant 2)nullRequired
json example
{
  "status": "COMPLETED",
  "id": "11111111-1111-4111-8111-111111111111",
  "created_at": "2026-09-01T12:00:00.000Z",
  "updated_at": "2026-09-01T12:00:00.000Z",
  "user_id": "11111111-1111-4111-8111-111111111111",
  "farm_id": "11111111-1111-4111-8111-111111111111",
  "metadata": null,
  "completed_at": "2026-09-01T12:00:00.000Z",
  "file_id": "11111111-1111-4111-8111-111111111111",
  "error_message": null,
  "format": "CSV",
  "file": {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "flock.csv",
    "mime_type": "text/csv",
    "size": 128,
    "url": "https://example.com/flock.csv",
    "is_active": true,
    "created_at": "2026-09-01T12:00:00.000Z",
    "updated_at": "2026-09-01T12:00:00.000Z"
  },
  "user": {
    "id": "11111111-1111-4111-8111-111111111111",
    "full_name": null,
    "phone_number_local": null
  },
  "import_items": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "action_id": "44444444-4444-4444-8444-444444444444",
      "import_id": "11111111-1111-4111-8111-111111111111",
      "entity_id": "22222222-2222-4222-8222-222222222222",
      "entity_type": "ANIMAL",
      "error_message": null,
      "mapped_data": {
        "metadata": {
          "tag": "42"
        }
      },
      "row_number": 1,
      "source_data": {
        "tag": "42"
      },
      "status": "PROCESSED",
      "created_at": "2026-09-01T12:00:00.000Z",
      "updated_at": "2026-09-01T12:00:00.000Z",
      "action": {
        "id": "44444444-4444-4444-8444-444444444444",
        "agent_action_id": null,
        "action_type": "CREATE",
        "entity_id": "22222222-2222-4222-8222-222222222222",
        "entity_type": "ANIMAL",
        "state_before": null,
        "state_after": {
          "id": "22222222-2222-4222-8222-222222222222",
          "metadata": {
            "tag": "42"
          }
        },
        "undone_at": null,
        "created_at": "2026-09-01T12:00:00.000Z",
        "updated_at": "2026-09-01T12:00:00.000Z"
      }
    }
  ]
}

GET /v1/farm/{farm_id}/import/{import_id}/changes

Get Import Changes

Current legacy imports 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"}
import_idpathYes{"type":"string","format":"uuid"}

Request example

bash example
curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/import/<import_id>/changes' \
  -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
importobjectRequired
import.statusstringRequiredenum: ["COMPLETED","FAILED","PENDING","PROCESSING"]
import.idstringRequired
import.created_atstringRequiredformat: "date-time"
import.updated_atstringRequiredformat: "date-time"
import.user_idstringRequired
import.farm_idstringRequired
import.metadataJSONRequired
import.completed_at (variant 1)nullRequired
import.completed_at (variant 2)stringRequiredformat: "date-time"
import.file_idstringRequired
import.error_message (variant 1)nullRequired
import.error_message (variant 2)stringRequired
import.formatstringRequiredenum: ["CSV","JSON"]
changesarrayRequired
changes[]JSONRequired
changes[]objectRequired
changes[].idstringRequired
changes[].action_idstring or nullRequired
changes[].import_idstringRequired
changes[].entity_idstringRequired
changes[].entity_typestringRequiredenum: ["ANIMAL","ANIMAL_IDENTIFIER","GROUP","RECORD","RECORD_ITEM"]
changes[].error_messagestring or nullRequired
changes[].mapped_dataJSONRequired
changes[].row_numberinteger or nullRequired
changes[].source_dataJSONRequired
changes[].statusstringRequiredenum: ["FAILED","PENDING","PROCESSED"]
changes[].created_atstringRequiredformat: "date-time"
changes[].updated_atstringRequiredformat: "date-time"
changes[].action (variant 1)objectRequired
changes[].action (variant 1).idstringRequired
changes[].action (variant 1).agent_action_idstring or nullRequired
changes[].action (variant 1).action_typestringRequired
changes[].action (variant 1).entity_idstringRequired
changes[].action (variant 1).entity_typestringRequiredenum: ["ANIMAL","ANIMAL_IDENTIFIER","GROUP","RECORD","RECORD_ITEM"]
changes[].action (variant 1).state_afterJSONRequired
changes[].action (variant 1).state_beforeJSONRequired
changes[].action (variant 1).undone_atstring or nullRequiredformat: "date-time"
changes[].action (variant 1).created_atstringRequiredformat: "date-time"
changes[].action (variant 1).updated_atstringRequiredformat: "date-time"
changes[].action (variant 2)nullRequired
changes[]objectRequired
changes[].action_idstringRequired
changes[].actionobjectRequired
changes[].action.idstringRequired
changes[].action.agent_action_idstring or nullRequired
changes[].action.action_typestringRequired
changes[].action.entity_idstringRequired
changes[].action.entity_typestringRequiredenum: ["ANIMAL","ANIMAL_IDENTIFIER","GROUP","RECORD","RECORD_ITEM"]
changes[].action.state_afterJSONRequired
changes[].action.state_beforeJSONRequired
changes[].action.undone_atstring or nullRequiredformat: "date-time"
changes[].action.created_atstringRequiredformat: "date-time"
changes[].action.updated_atstringRequiredformat: "date-time"
json example
{
  "import": {
    "status": "COMPLETED",
    "id": "11111111-1111-4111-8111-111111111111",
    "created_at": "2026-09-01T12:00:00.000Z",
    "updated_at": "2026-09-01T12:00:00.000Z",
    "user_id": "11111111-1111-4111-8111-111111111111",
    "farm_id": "11111111-1111-4111-8111-111111111111",
    "metadata": null,
    "completed_at": "2026-09-01T12:00:00.000Z",
    "file_id": "11111111-1111-4111-8111-111111111111",
    "error_message": null,
    "format": "CSV"
  },
  "changes": [
    {
      "id": "55555555-5555-4555-8555-555555555555",
      "action_id": "44444444-4444-4444-8444-444444444444",
      "import_id": "11111111-1111-4111-8111-111111111111",
      "entity_id": "22222222-2222-4222-8222-222222222222",
      "entity_type": "ANIMAL",
      "error_message": null,
      "mapped_data": {
        "metadata": {
          "tag": "42"
        }
      },
      "row_number": 1,
      "source_data": {
        "tag": "42"
      },
      "status": "PROCESSED",
      "created_at": "2026-09-01T12:00:00.000Z",
      "updated_at": "2026-09-01T12:00:00.000Z",
      "action": {
        "id": "44444444-4444-4444-8444-444444444444",
        "agent_action_id": null,
        "action_type": "CREATE",
        "entity_id": "22222222-2222-4222-8222-222222222222",
        "entity_type": "ANIMAL",
        "state_before": null,
        "state_after": {
          "id": "22222222-2222-4222-8222-222222222222",
          "metadata": {
            "tag": "42"
          }
        },
        "undone_at": null,
        "created_at": "2026-09-01T12:00:00.000Z",
        "updated_at": "2026-09-01T12:00:00.000Z"
      }
    }
  ]
}

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