Farm archives API

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

GET /v1/farm/{farm_id}/exports
POST /v1/farm/{farm_id}/exports
DELETE /v1/farm/{farm_id}/exports/{export_id}
GET /v1/farm/{farm_id}/exports/{export_id}
GET /v1/farm/{farm_id}/exports/{export_id}/download
POST /v1/farm/{farm_id}/exports/{export_id}/download

GET /v1/farm/{farm_id}/exports

Parameter	In	Required	Schema
farm_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>/exports' \
  -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
exports	array	Required
exports[]	object	Required
exports[].id	string	Required
exports[].farm_id	string	Required
exports[].status	string	Required
exports[].sha256 (variant 1)	null	Required
exports[].sha256 (variant 2)	string	Required
exports[].bytes (variant 1)	null	Required
exports[].bytes (variant 2)	string	Required
exports[].error (variant 1)	null	Required
exports[].error (variant 2)	string	Required
exports[].created_at	string	Required	format: "date-time"
exports[].expires_at	string	Required	format: "date-time"

json example

{
  "exports": []
}

POST /v1/farm/{farm_id}/exports

Parameter	In	Required	Schema
farm_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>/exports' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

Status	Meaning	Content type
202	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

202 response schema (application/json)

Field	Type	Presence	Constraints
id	string	Required
farm_id	string	Required
status	string	Required
sha256 (variant 1)	null	Required
sha256 (variant 2)	string	Required
bytes (variant 1)	null	Required
bytes (variant 2)	string	Required
error (variant 1)	null	Required
error (variant 2)	string	Required
created_at	string	Required	format: "date-time"
expires_at	string	Required	format: "date-time"

json example

{
  "id": "11111111-1111-4111-8111-111111111111",
  "farm_id": "11111111-1111-4111-8111-111111111111",
  "status": "example",
  "sha256": null,
  "bytes": null,
  "error": null,
  "created_at": "2026-09-01T12:00:00.000Z",
  "expires_at": "2026-09-01T12:00:00.000Z"
}

DELETE /v1/farm/{farm_id}/exports/{export_id}

Current farm archives HTTP operation. External credential scopes: read:exports. Minimum farm role: READER. 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. Cancels the export job; this does not delete farm records.

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

Request example

bash example

curl --fail-with-body -X DELETE \
  'https://api.ranch.bot/v1/farm/<farm_id>/exports/<export_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
id	string	Required
farm_id	string	Required
status	string	Required
sha256 (variant 1)	null	Required
sha256 (variant 2)	string	Required
bytes (variant 1)	null	Required
bytes (variant 2)	string	Required
error (variant 1)	null	Required
error (variant 2)	string	Required
created_at	string	Required	format: "date-time"
expires_at	string	Required	format: "date-time"

json example

{
  "id": "11111111-1111-4111-8111-111111111111",
  "farm_id": "11111111-1111-4111-8111-111111111111",
  "status": "example",
  "sha256": null,
  "bytes": null,
  "error": null,
  "created_at": "2026-09-01T12:00:00.000Z",
  "expires_at": "2026-09-01T12:00:00.000Z"
}

GET /v1/farm/{farm_id}/exports/{export_id}

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
export_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>/exports/<export_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
id	string	Required
farm_id	string	Required
status	string	Required
sha256 (variant 1)	null	Required
sha256 (variant 2)	string	Required
bytes (variant 1)	null	Required
bytes (variant 2)	string	Required
error (variant 1)	null	Required
error (variant 2)	string	Required
created_at	string	Required	format: "date-time"
expires_at	string	Required	format: "date-time"

json example

{
  "id": "11111111-1111-4111-8111-111111111111",
  "farm_id": "11111111-1111-4111-8111-111111111111",
  "status": "example",
  "sha256": null,
  "bytes": null,
  "error": null,
  "created_at": "2026-09-01T12:00:00.000Z",
  "expires_at": "2026-09-01T12:00:00.000Z"
}

GET /v1/farm/{farm_id}/exports/{export_id}/download

Current farm archives HTTP operation. External credential scopes: read:exports. 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. Downloads an available export for the requesting user. POST also accepts access_token in a form body when the Authorization header is absent.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
export_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>/exports/<export_id>/download' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

Status	Meaning	Content type
200	ZIP archive stream.	application/zip
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/zip)

Field	Type	Presence	Constraints

POST /v1/farm/{farm_id}/exports/{export_id}/download

Current farm archives HTTP operation. External credential scopes: read:exports. Minimum farm role: READER. 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. Downloads an available export for the requesting user. POST also accepts access_token in a form body when the Authorization header is absent.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
export_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>/exports/<export_id>/download' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

Status	Meaning	Content type
200	ZIP archive stream.	application/zip
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/zip)

Field	Type	Presence	Constraints

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