Import requests API

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

GET /v1/farm/{farm_id}/import-request
POST /v1/farm/{farm_id}/import-request
GET /v1/farm/{farm_id}/import-request/{import_request_id}

GET /v1/farm/{farm_id}/import-request

Get Import Requests

Current import requests 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.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
skip	query	No	{"type":"integer"}
take	query	No	{"type":"integer"}
status	query	No	{"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-request' \
  -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	number	Required
import_requests	array	Required
import_requests[]	object	Required
import_requests[].status	string	Required	enum: ["COMPLETED","FAILED","PENDING","PROCESSING"]
import_requests[].id	string	Required
import_requests[].created_at	string	Required	format: "date-time"
import_requests[].updated_at	string	Required	format: "date-time"
import_requests[].user_id	string	Required
import_requests[].farm_id	string	Required
import_requests[].completed_at (variant 1)	null	Required
import_requests[].completed_at (variant 2)	string	Required	format: "date-time"
import_requests[].note (variant 1)	null	Required
import_requests[].note (variant 2)	string	Required
import_requests[].summary (variant 1)	null	Required
import_requests[].summary (variant 2)	string	Required
import_requests[].files	array	Required
import_requests[].files[]	object	Required
import_requests[].files[].id	string	Required
import_requests[].files[].created_at	string	Required	format: "date-time"
import_requests[].files[].updated_at	string	Required	format: "date-time"
import_requests[].files[].name	string	Required
import_requests[].files[].is_active	boolean	Required
import_requests[].files[].mime_type	string	Required
import_requests[].files[].size	number	Required
import_requests[].files[].url	string	Required

json example

{
  "total": 1,
  "import_requests": []
}

POST /v1/farm/{farm_id}/import-request

Create Import Request

Current import requests 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. Uploads are stored for supervised review, not automatically loaded into farm records. Up to 10 files, 25 MB each; optional note is at most 2,000 characters.

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

Request body (multipart/form-data)

Field	Type	Presence	Constraints
note	string	Optional	maxLength: 2000
files	array	Required	minItems: 1; maxItems: 10
files[]	string	Required	format: "binary"

Request example

bash example

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

Responses

Status	Meaning	Content type
201	Success	application/json
400	Error	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

201 response schema (application/json)

Field	Type	Presence	Constraints
import_request	object	Required
import_request.status	string	Required	enum: ["COMPLETED","FAILED","PENDING","PROCESSING"]
import_request.id	string	Required
import_request.created_at	string	Required	format: "date-time"
import_request.updated_at	string	Required	format: "date-time"
import_request.user_id	string	Required
import_request.farm_id	string	Required
import_request.completed_at (variant 1)	null	Required
import_request.completed_at (variant 2)	string	Required	format: "date-time"
import_request.note (variant 1)	null	Required
import_request.note (variant 2)	string	Required
import_request.summary (variant 1)	null	Required
import_request.summary (variant 2)	string	Required
import_request.files	array	Required
import_request.files[]	object	Required
import_request.files[].id	string	Required
import_request.files[].created_at	string	Required	format: "date-time"
import_request.files[].updated_at	string	Required	format: "date-time"
import_request.files[].name	string	Required
import_request.files[].is_active	boolean	Required
import_request.files[].mime_type	string	Required
import_request.files[].size	number	Required
import_request.files[].url	string	Required

json example

{
  "import_request": {
    "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",
    "completed_at": null,
    "note": null,
    "summary": null,
    "files": []
  }
}

400 response schema (application/json)

Field	Type	Presence	Constraints
(variant 1)	object	Required
(variant 1).errors	array	Required
(variant 1).errors[]	object	Required
(variant 1).errors[].message	string	Required
(variant 1).data	null	Required
(variant 1).success	boolean	Required
(variant 2)	object	Required
(variant 2).success	boolean	Required	const: false
(variant 2).errors	array	Required
(variant 2).errors[]	object	Required
(variant 2).errors[].code	integer	Optional
(variant 2).errors[].name	string	Optional
(variant 2).errors[].message	string	Required
(variant 2).data	null	Optional

json example

{
  "success": false,
  "data": null,
  "errors": [
    {
      "message": "No files provided"
    }
  ]
}

GET /v1/farm/{farm_id}/import-request/{import_request_id}

Get Import Request

Current import requests 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.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
import_request_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>/import-request/<import_request_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
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
import_request	object	Required
import_request.status	string	Required	enum: ["COMPLETED","FAILED","PENDING","PROCESSING"]
import_request.id	string	Required
import_request.created_at	string	Required	format: "date-time"
import_request.updated_at	string	Required	format: "date-time"
import_request.user_id	string	Required
import_request.farm_id	string	Required
import_request.completed_at (variant 1)	null	Required
import_request.completed_at (variant 2)	string	Required	format: "date-time"
import_request.note (variant 1)	null	Required
import_request.note (variant 2)	string	Required
import_request.summary (variant 1)	null	Required
import_request.summary (variant 2)	string	Required
import_request.files	array	Required
import_request.files[]	object	Required
import_request.files[].id	string	Required
import_request.files[].created_at	string	Required	format: "date-time"
import_request.files[].updated_at	string	Required	format: "date-time"
import_request.files[].name	string	Required
import_request.files[].is_active	boolean	Required
import_request.files[].mime_type	string	Required
import_request.files[].size	number	Required
import_request.files[].url	string	Required

json example

{
  "import_request": {
    "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",
    "completed_at": null,
    "note": null,
    "summary": null,
    "files": []
  }
}

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