Locations API

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

• GET /v1/farm/{farm_id}/locations
• POST /v1/farm/{farm_id}/locations
• PUT /v1/farm/{farm_id}/locations/home
• DELETE /v1/farm/{farm_id}/locations/home
• GET /v1/farm/{farm_id}/locations/{location_id}
• PUT /v1/farm/{farm_id}/locations/{location_id}
• POST /v1/farm/{farm_id}/locations/{location_id}/archive
• POST /v1/farm/{farm_id}/locations/{location_id}/restore
• POST /v1/farm/{farm_id}/locations/{location_id}/identifiers
• PUT /v1/farm/{farm_id}/locations/{location_id}/identifiers/{identifier_id}
• DELETE /v1/farm/{farm_id}/locations/{location_id}/identifiers/{identifier_id}

GET /v1/farm/{farm_id}/locations

List Locations

List premises and sublocations for the farm, including identifiers and the parent path. Directory scopes use read:farms/write:farms; minimum farm role READER for reads and EDITOR for writes.

Request example

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

Responses

200 response schema (application/json)

POST /v1/farm/{farm_id}/locations

Create Location

Create a premises (no parent_id) or a sublocation beneath an existing premises. Directory scopes use read:farms/write:farms; minimum farm role READER for reads and EDITOR for writes.

Request body (application/json)

{
  "name": "Home place",
  "category": "FARM",
  "province_state": "Alberta"
}

Request example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/locations' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Home place","category":"FARM","province_state":"Alberta"}'

Responses

201 response schema (application/json)

PUT /v1/farm/{farm_id}/locations/home

Set Home Premises

Set the explicitly selected default home premises. This is never assumed as an event origin. Directory scopes use read:farms/write:farms; minimum farm role READER for reads and EDITOR for writes.

Request body (application/json)

{
  "location_id": "00000000-0000-4000-8000-000000000010"
}

Request example

curl --fail-with-body -X PUT \
  'https://api.ranch.bot/v1/farm/<farm_id>/locations/home' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"location_id":"00000000-0000-4000-8000-000000000010"}'

Responses

200 response schema (application/json)

DELETE /v1/farm/{farm_id}/locations/home

Clear Home Premises

Clear the default home premises. Directory scopes use read:farms/write:farms; minimum farm role READER for reads and EDITOR for writes.

Request example

curl --fail-with-body -X DELETE \
  'https://api.ranch.bot/v1/farm/<farm_id>/locations/home' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

GET /v1/farm/{farm_id}/locations/{location_id}

Get Location

Get one location with its sublocations and premises identifiers. Directory scopes use read:farms/write:farms; minimum farm role READER for reads and EDITOR for writes.

Request example

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

Responses

200 response schema (application/json)

PUT /v1/farm/{farm_id}/locations/{location_id}

Update Location

Edit a location directory entry. Pass expected_version to reject a stale edit. Directory scopes use read:farms/write:farms; minimum farm role READER for reads and EDITOR for writes.

Request body (application/json)

{
  "name": "North field",
  "expected_version": 1
}

Request example

curl --fail-with-body -X PUT \
  'https://api.ranch.bot/v1/farm/<farm_id>/locations/<location_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"North field","expected_version":1}'

Responses

200 response schema (application/json)

POST /v1/farm/{farm_id}/locations/{location_id}/archive

Archive Location

Archive a location. Archiving a premises archives its sublocations and clears a matching home default. Directory scopes use read:farms/write:farms; minimum farm role READER for reads and EDITOR for writes.

Request body (application/json)

{
  "expected_version": 1
}

Request example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/locations/<location_id>/archive' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"expected_version":1}'

Responses

200 response schema (application/json)

POST /v1/farm/{farm_id}/locations/{location_id}/restore

Restore Location

Restore an archived location. A sublocation requires an active parent; restoring a premises restores its sublocations. Directory scopes use read:farms/write:farms; minimum farm role READER for reads and EDITOR for writes.

Request body (application/json)

{
  "expected_version": 2
}

Request example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/locations/<location_id>/restore' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"expected_version":2}'

Responses

200 response schema (application/json)

POST /v1/farm/{farm_id}/locations/{location_id}/identifiers

Add Premises Identifier

Add a premises identifier to a root premises. Values are stored as strings with leading zeros preserved; no registry verification is claimed. Directory scopes use read:farms/write:farms; minimum farm role READER for reads and EDITOR for writes.

Request body (application/json)

{
  "scheme": "CA_PID",
  "value": "A0012345",
  "issuer": "Alberta"
}

Request example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/locations/<location_id>/identifiers' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"scheme":"CA_PID","value":"A0012345","issuer":"Alberta"}'

Responses

201 response schema (application/json)

PUT /v1/farm/{farm_id}/locations/{location_id}/identifiers/{identifier_id}

Update Premises Identifier

Update a premises identifier. Directory scopes use read:farms/write:farms; minimum farm role READER for reads and EDITOR for writes.

Request body (application/json)

{
  "value": "A0012346",
  "expected_version": 1
}

Request example

curl --fail-with-body -X PUT \
  'https://api.ranch.bot/v1/farm/<farm_id>/locations/<location_id>/identifiers/<identifier_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"value":"A0012346","expected_version":1}'

Responses

200 response schema (application/json)

DELETE /v1/farm/{farm_id}/locations/{location_id}/identifiers/{identifier_id}

Delete Premises Identifier

Remove a premises identifier. Directory scopes use read:farms/write:farms; minimum farm role READER for reads and EDITOR for writes.

Request example

curl --fail-with-body -X DELETE \
  'https://api.ranch.bot/v1/farm/<farm_id>/locations/<location_id>/identifiers/<identifier_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

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