Default farm API

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

• GET /v1/user/default-farm
• PUT /v1/user/default-farm

GET /v1/user/default-farm

Get Default Farm

Current default farm HTTP operation. No resource-scope middleware on this operation. Access is resolved for the authenticated user or by the endpoint-specific OAuth checks. 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.

Request example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/user/default-farm' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

200 response schema (application/json)

{
  "default_farm_id": null
}

PUT /v1/user/default-farm

Set Default Farm

Current default farm HTTP operation. No resource-scope middleware on this operation. Access is resolved for the authenticated user or by the endpoint-specific OAuth checks. 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. Device credentials are rejected. Accepts a deprecated legacy key; setting a default does not grant access to that farm.

Request body (application/json)

{
  "farm_id": "11111111-1111-4111-8111-111111111111"
}

Request example

curl --fail-with-body -X PUT \
  'https://api.ranch.bot/v1/user/default-farm' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"farm_id":"11111111-1111-4111-8111-111111111111"}'

Responses

200 response schema (application/json)

{
  "default_farm_id": null
}

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.

{
  "success": false,
  "errors": [
    {
      "code": 400,
      "name": "ValidationError",
      "message": "Example validation failure"
    }
  ]
}