Farm memory API

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

GET /v1/farm/{farm_id}/memory

GET /v1/farm/{farm_id}/memory

Get Memories

Current farm memory 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. HTTP memory creation and deletion are browser-only and reject both device credentials and legacy API keys. CLI/MCP tool availability must not be inferred from this HTTP read endpoint.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
grouped	query	No	{"type":"string","enum":["true","false"]} Only the literal true selects grouped versions; otherwise returns current memories.

Request example

bash example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/memory' \
  -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
(variant 1)	object	Required
(variant 1).memories	array	Required
(variant 1).memories[]	object	Required
(variant 1).memories[].key	string	Required
(variant 1).memories[].current	object	Required
(variant 1).memories[].current.id	string	Required
(variant 1).memories[].current.farm_id	string	Required
(variant 1).memories[].current.key	string	Required
(variant 1).memories[].current.value	JSON	Required
(variant 1).memories[].current.provenance	JSON	Optional
(variant 1).memories[].current.source (variant 1)	null	Required
(variant 1).memories[].current.source (variant 2)	string	Required
(variant 1).memories[].current.confidence (variant 1)	null	Required
(variant 1).memories[].current.confidence (variant 2)	number	Required
(variant 1).memories[].current.created_at	string	Required	format: "date-time"
(variant 1).memories[].current.updated_at	string	Required	format: "date-time"
(variant 1).memories[].versions	array	Required
(variant 1).memories[].versions[]	object	Required
(variant 1).memories[].versions[].id	string	Required
(variant 1).memories[].versions[].value	JSON	Required
(variant 1).memories[].versions[].source (variant 1)	null	Required
(variant 1).memories[].versions[].source (variant 2)	string	Required
(variant 1).memories[].versions[].provenance	JSON	Required
(variant 1).memories[].versions[].confidence (variant 1)	null	Required
(variant 1).memories[].versions[].confidence (variant 2)	number	Required
(variant 1).memories[].versions[].created_at	string	Required	format: "date-time"
(variant 1).memories[].versions[].updated_at	string	Required	format: "date-time"
(variant 2)	object	Required
(variant 2).memories	array	Required
(variant 2).memories[]	object	Required
(variant 2).memories[].id	string	Required
(variant 2).memories[].key	string	Required
(variant 2).memories[].value	JSON	Required
(variant 2).memories[].source (variant 1)	null	Required
(variant 2).memories[].source (variant 2)	string	Required
(variant 2).memories[].confidence (variant 1)	null	Required
(variant 2).memories[].confidence (variant 2)	number	Required
(variant 2).memories[].created_at	string	Required	format: "date-time"
(variant 2).memories[].updated_at	string	Required	format: "date-time"

json example

{
  "memories": []
}

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