{ "openapi": "3.1.0", "info": { "title": "Ranch.Bot HTTP API", "version": "2026-09-06", "description": "Current implemented integration endpoints. Access is directed developer use; contact support@ranch.bot. Legacy API keys are deprecated. OAuth requires a registered client and verified setup; this reference does not provide self-serve onboarding. Direct API writes execute without the app confirmation screen. The canonical HTTP prefix is /v1; /api/v1 is also mounted today. OAuth paths are at /oauth. No new versioning or compatibility guarantee is implied. JSON request bodies have a 10 MB parser limit. Browser CORS is restricted to the configured Ranch.Bot web origin; server-side clients and cURL can send requests without Origin. Scope checks and farm membership/roles are separate. OAuth/device and legacy key scopes do not grant membership. Most insufficient-role failures are 401, while missing scope is 403 and missing membership is 404. Pagination uses skip/take where listed and is not a stable snapshot; supply an explicit positive take and deduplicate by id when data changes. Unspecified pagination values are not a published fixed default." }, "servers": [ { "url": "https://api.ranch.bot" } ], "security": [ { "DeviceToken": [] }, { "LegacyKey": [] } ], "paths": { "/oauth/.well-known/oauth-authorization-server": { "get": { "operationId": "get_oauth_well_known_oauth_authorization_server", "tags": [ "oauth" ], "summary": "Discovery", "description": "Current oauth HTTP operation. No resource-scope middleware on this operation. Access is resolved for the authenticated user or by the endpoint-specific OAuth checks.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuer": { "type": "string" }, "authorization_endpoint": { "type": "string" }, "token_endpoint": { "type": "string" }, "revocation_endpoint": { "type": "string" }, "userinfo_endpoint": { "type": "string" }, "jwks_uri": { "type": "string" }, "response_types_supported": { "type": "array", "items": { "type": "string" } }, "grant_types_supported": { "type": "array", "items": { "type": "string" } }, "code_challenge_methods_supported": { "type": "array", "items": { "type": "string" } }, "scopes_supported": { "type": "array", "items": { "type": "string" } }, "token_endpoint_auth_methods_supported": { "type": "array", "items": { "type": "string" } } }, "required": [ "issuer", "authorization_endpoint", "token_endpoint", "revocation_endpoint", "userinfo_endpoint", "jwks_uri", "response_types_supported", "grant_types_supported", "code_challenge_methods_supported", "scopes_supported", "token_endpoint_auth_methods_supported" ] }, "example": { "issuer": "example", "authorization_endpoint": "example", "token_endpoint": "PLACEHOLDER_CREDENTIAL", "revocation_endpoint": "example", "userinfo_endpoint": "example", "jwks_uri": "https://example.com", "response_types_supported": [], "grant_types_supported": [], "code_challenge_methods_supported": [], "scopes_supported": [], "token_endpoint_auth_methods_supported": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/oauth.ts", "x-required-scopes": [], "x-minimum-role": "None at route middleware", "security": [] } }, "/oauth/authorize": { "get": { "operationId": "get_oauth_authorize", "tags": [ "oauth" ], "summary": "Authorize", "description": "Current oauth HTTP operation. No resource-scope middleware on this operation. Access is resolved for the authenticated user or by the endpoint-specific OAuth checks.", "parameters": [ { "in": "query", "name": "client_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "redirect_uri", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "response_type", "required": true, "schema": { "type": "string", "const": "code" } }, { "in": "query", "name": "scope", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "state", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "code_challenge", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "code_challenge_method", "required": false, "schema": { "type": "string" } } ], "responses": { "302": { "description": "Redirect to the configured authentication or consent flow.", "headers": { "Location": { "schema": { "type": "string" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/oauth.ts", "x-required-scopes": [], "x-minimum-role": "None at route middleware", "security": [] } }, "/oauth/device": { "post": { "operationId": "post_oauth_device", "tags": [ "oauth" ], "summary": "Device", "description": "Current oauth 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: 30 requests per 15-minute window, per client IP. RateLimit headers report the current window; respect Retry-After on 429. Requires an active registered client and only that client\u2019s allowed scopes. Codes expire after 900 seconds; poll no faster than every 5 seconds. The user approves in the browser. No public self-serve client registration is provided.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "device_code": { "type": "string" }, "user_code": { "type": "string" }, "verification_uri": { "type": "string" }, "verification_uri_complete": { "type": "string" }, "expires_in": { "type": "number" }, "interval": { "type": "number" } }, "required": [ "device_code", "user_code", "verification_uri", "verification_uri_complete", "expires_in", "interval" ] }, "example": { "device_code": "example", "user_code": "example", "verification_uri": "https://example.com", "verification_uri_complete": "example", "expires_in": 1, "interval": 1 } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/oauth.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string", "minLength": 1, "maxLength": 255 }, "scope": { "type": "string", "maxLength": 1024 } }, "required": [ "client_id" ] }, "example": { "client_id": "11111111-1111-4111-8111-111111111111" } } } }, "x-required-scopes": [], "x-minimum-role": "None at route middleware", "security": [] } }, "/oauth/device/token": { "post": { "operationId": "post_oauth_device_token", "tags": [ "oauth" ], "summary": "Device Token", "description": "Current oauth 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: 240 requests per 15-minute window, per client IP. RateLimit headers report the current window; respect Retry-After on 429. Poll with the returned device_code and original client_id. Pending authorization returns an OAuth 400 body. Malformed request bodies return the standard validation 400 envelope. Invalid, consumed, expired, mismatched-client, or disallowed-permission device codes return the standard 401 envelope.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string" }, "access_token": { "type": "string" }, "token_type": { "type": "string", "const": "Bearer" }, "expires_in": { "type": "number" }, "refresh_token": { "type": "string", "description": "Returned for normal registered clients. The observer client (ranchbot-pi-observer-v1) omits this field; observer sessions cannot be refreshed." } }, "required": [ "scope", "access_token", "token_type", "expires_in" ] }, "example": { "scope": "read:animals", "access_token": "PLACEHOLDER_ACCESS_TOKEN", "refresh_token": "PLACEHOLDER_REFRESH_TOKEN", "token_type": "Bearer", "expires_in": 900 } } } }, "400": { "description": "Pending authorization returns an OAuth error object; malformed request bodies return the standard validation error envelope.", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "required": [ "error", "error_description" ] }, { "$ref": "#/components/schemas/Error" } ] }, "example": { "error": "authorization_pending", "error_description": "The authorization request is still pending" } } } }, "401": { "description": "Invalid, consumed, expired, mismatched-client, or disallowed-permission device code; returns the standard error envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "AuthError", "message": "Invalid device code" } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/oauth.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "const": "urn:ietf:params:oauth:grant-type:device_code" }, "device_code": { "type": "string", "minLength": 1, "maxLength": 128 }, "client_id": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "grant_type", "device_code", "client_id" ] }, "example": { "grant_type": "urn:ietf:params:oauth:grant-type:device_code", "device_code": "example", "client_id": "11111111-1111-4111-8111-111111111111" } } } }, "x-required-scopes": [], "x-minimum-role": "None at route middleware", "security": [] } }, "/oauth/revoke": { "post": { "operationId": "post_oauth_revoke", "tags": [ "oauth" ], "summary": "Revoke", "description": "Current oauth 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: 240 requests per 15-minute window, per client IP. RateLimit headers report the current window; respect Retry-After on 429.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ] }, "example": { "revoked": true } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/oauth.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 2048 }, "client_id": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "token", "client_id" ] }, "example": { "token": "PLACEHOLDER_CREDENTIAL", "client_id": "11111111-1111-4111-8111-111111111111" } } } }, "x-required-scopes": [], "x-minimum-role": "None at route middleware", "security": [] } }, "/oauth/token": { "post": { "operationId": "post_oauth_token", "tags": [ "oauth" ], "summary": "Token", "description": "Current oauth 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: 240 requests per 15-minute window, per client IP. RateLimit headers report the current window; respect Retry-After on 429. Authorization-code exchange requires code and redirect_uri. A refresh-token grant requires refresh_token. Use the configured client and its directed setup; do not infer a working public client from endpoint existence.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "number" }, "refresh_token": { "type": "string" }, "scope": { "type": "string" } }, "required": [ "access_token", "token_type", "expires_in", "refresh_token", "scope" ] }, { "type": "object", "properties": { "refresh_token": { "type": "string" }, "scope": { "type": "string" }, "access_token": { "type": "string" }, "token_type": { "type": "string", "const": "Bearer" }, "expires_in": { "type": "number" } }, "required": [ "refresh_token", "scope", "access_token", "token_type", "expires_in" ] } ] }, { "type": "object", "properties": { "access_token": { "type": "string" }, "token_type": { "type": "string" }, "expires_in": { "type": "number" }, "refresh_token": { "type": "string" } }, "required": [ "access_token", "token_type", "expires_in", "refresh_token" ] } ] }, "example": { "access_token": "PLACEHOLDER_CREDENTIAL", "token_type": "PLACEHOLDER_CREDENTIAL", "expires_in": 1, "refresh_token": "PLACEHOLDER_CREDENTIAL", "scope": "example" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/oauth.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code", "refresh_token" ] }, "code": { "type": "string" }, "redirect_uri": { "type": "string" }, "refresh_token": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "code_verifier": { "type": "string" } }, "required": [ "grant_type", "client_id" ] }, "example": { "grant_type": "authorization_code", "client_id": "11111111-1111-4111-8111-111111111111" } } } }, "x-required-scopes": [], "x-minimum-role": "None at route middleware", "security": [] } }, "/v1/farm": { "get": { "operationId": "get_v1_farm", "tags": [ "farms" ], "summary": "Get Farms", "description": "Current farms HTTP operation. External credential scopes: read:farms. Access is resolved for the authenticated user or by the endpoint-specific OAuth checks. 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.", "parameters": [ { "in": "query", "name": "skip", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "take", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "number" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "allow_private_threads": { "type": "boolean" }, "current_month_start": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "is_active": { "type": "boolean" }, "species": { "type": "string", "enum": [ "BISON", "CATTLE", "ELK", "GOAT", "HORSE", "OTHER", "SHEEP" ] }, "species_other": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "farm_users": { "type": "array", "items": { "$ref": "#/components/schemas/FarmMember" } } }, "required": [ "id", "created_at", "updated_at", "name", "allow_private_threads", "current_month_start", "is_active", "species", "species_other", "farm_users" ] } } }, "required": [ "total", "records" ] }, "example": { "total": 0, "records": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/farm.ts", "x-required-scopes": [ "read:farms" ], "x-minimum-role": "None at route middleware" }, "post": { "operationId": "post_v1_farm", "tags": [ "farms" ], "summary": "Create Farm", "description": "Current farms HTTP operation. External credential scopes: write:farms. 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.", "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "farm": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "allow_private_threads": { "type": "boolean" }, "current_month_start": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "is_active": { "type": "boolean" }, "species": { "type": "string", "enum": [ "BISON", "CATTLE", "ELK", "GOAT", "HORSE", "OTHER", "SHEEP" ] }, "species_other": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "farm_users": { "type": "array", "items": { "$ref": "#/components/schemas/FarmMember" } } }, "required": [ "id", "created_at", "updated_at", "name", "allow_private_threads", "current_month_start", "is_active", "species", "species_other", "farm_users" ] }, "welcome_thread_id": { "type": "string" } }, "required": [ "farm", "welcome_thread_id" ] }, "example": { "farm": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "allow_private_threads": true, "current_month_start": null, "is_active": true, "species": "BISON", "species_other": null, "farm_users": [] }, "welcome_thread_id": "11111111-1111-4111-8111-111111111111" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/farm.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2 }, "species": { "type": "string", "enum": [ "BISON", "CATTLE", "ELK", "GOAT", "HORSE", "OTHER", "SHEEP" ] }, "species_other": { "type": "string", "maxLength": 100 } }, "required": [ "name", "species" ] }, "example": { "name": "Example", "species": "BISON" } } } }, "x-required-scopes": [ "write:farms" ], "x-minimum-role": "None at route middleware" } }, "/v1/farm/{farm_id}": { "delete": { "operationId": "delete_v1_farm_farm_id", "tags": [ "farms" ], "summary": "Delete Farm", "description": "Current farms HTTP operation. External credential scopes: write:farms. Minimum farm role: OWNER. 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. Marks the stored entity inactive (soft deletion).", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Completed; no response body." }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/farm.ts", "x-required-scopes": [ "write:farms" ], "x-minimum-role": "OWNER" }, "get": { "operationId": "get_v1_farm_farm_id", "tags": [ "farms" ], "summary": "Get Farm", "description": "Current farms HTTP operation. External credential scopes: read:farms. 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "farm": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allow_private_threads": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "current_month_start": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "species": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "species_other": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "farm_users": { "type": "array", "items": { "$ref": "#/components/schemas/FarmMember" } } }, "required": [ "id", "allow_private_threads", "current_month_start", "is_active", "name", "species", "species_other", "created_at", "updated_at", "farm_users" ] } }, "required": [ "farm" ] }, "example": { "farm": { "id": "11111111-1111-4111-8111-111111111111", "allow_private_threads": true, "current_month_start": "2026-09-01T12:00:00.000Z", "is_active": true, "name": "example", "species": "example", "species_other": "example", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "farm_users": [] } } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/farm.ts", "x-required-scopes": [ "read:farms" ], "x-minimum-role": "READER" }, "put": { "operationId": "put_v1_farm_farm_id", "tags": [ "farms" ], "summary": "Update Farm", "description": "Current farms HTTP operation. External credential scopes: write:farms. 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "farm": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "allow_private_threads": { "type": "boolean" }, "current_month_start": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "is_active": { "type": "boolean" }, "species": { "type": "string", "enum": [ "BISON", "CATTLE", "ELK", "GOAT", "HORSE", "OTHER", "SHEEP" ] }, "species_other": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "farm_users": { "type": "array", "items": { "$ref": "#/components/schemas/FarmMember" } } }, "required": [ "id", "created_at", "updated_at", "name", "allow_private_threads", "current_month_start", "is_active", "species", "species_other", "farm_users" ] } }, "required": [ "farm" ] }, "example": { "farm": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "allow_private_threads": true, "current_month_start": null, "is_active": true, "species": "BISON", "species_other": null, "farm_users": [] } } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/farm.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allow_private_threads": { "type": "boolean" }, "name": { "type": "string", "minLength": 2 }, "species": { "type": "string", "enum": [ "BISON", "CATTLE", "ELK", "GOAT", "HORSE", "OTHER", "SHEEP" ] }, "species_other": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] } } }, "example": {} } } }, "x-required-scopes": [ "write:farms" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/animals": { "get": { "operationId": "get_v1_farm_farm_id_animals", "tags": [ "animals" ], "summary": "Get Animals", "description": "Current animals HTTP operation. External credential scopes: read:animals. 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "skip", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "take", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "number" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "metadata": {}, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } }, "animal_identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/AnimalIdentifier" } } }, "required": [ "id", "created_at", "updated_at", "is_active", "farm_id", "metadata", "groups", "animal_identifiers" ] } } }, "required": [ "total", "records" ] }, "example": { "total": 0, "records": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/animal.ts", "x-required-scopes": [ "read:animals" ], "x-minimum-role": "READER" }, "post": { "operationId": "post_v1_farm_farm_id_animals", "tags": [ "animals" ], "summary": "Create Animal", "description": "Current animals HTTP operation. External credential scopes: write:animals. 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "metadata": {} }, "required": [ "id", "created_at", "updated_at", "is_active", "farm_id", "metadata" ] }, "example": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "metadata": null } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/animal.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": {} } }, "example": {} } } }, "x-required-scopes": [ "write:animals" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/animals/{animal_id}": { "delete": { "operationId": "delete_v1_farm_farm_id_animals_animal_id", "tags": [ "animals" ], "summary": "Delete Animal", "description": "Current animals HTTP operation. External credential scopes: write:animals. Minimum farm role: OWNER. 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. Marks the stored entity inactive (soft deletion).", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "animal_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Completed; no response body." }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/animal.ts", "x-required-scopes": [ "write:animals" ], "x-minimum-role": "OWNER" }, "get": { "operationId": "get_v1_farm_farm_id_animals_animal_id", "tags": [ "animals" ], "summary": "Get Animal", "description": "Current animals HTTP operation. External credential scopes: read:animals. 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "animal_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "metadata": {}, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } }, "animal_identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/AnimalIdentifier" } }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/RecordWithItems" } }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/File" } } }, "required": [ "id", "created_at", "updated_at", "is_active", "farm_id", "metadata", "groups", "animal_identifiers", "records", "files" ] }, "example": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "metadata": null, "groups": [], "animal_identifiers": [], "records": [], "files": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/animal.ts", "x-required-scopes": [ "read:animals" ], "x-minimum-role": "READER" }, "put": { "operationId": "put_v1_farm_farm_id_animals_animal_id", "tags": [ "animals" ], "summary": "Update Animal", "description": "Current animals HTTP operation. External credential scopes: write:animals. 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "animal_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "metadata": {} }, "required": [ "id", "created_at", "updated_at", "is_active", "farm_id", "metadata" ] }, "example": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "metadata": null } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/animal.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": {} } }, "example": {} } } }, "x-required-scopes": [ "write:animals" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/animals/{animal_id}/identifier": { "get": { "operationId": "get_v1_farm_farm_id_animals_animal_id_identifier", "tags": [ "identifiers" ], "summary": "Get Animal Identifiers", "description": "Current animal identifiers HTTP operation. External credential scopes: read:animals. 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "animal_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "skip", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "take", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "number" }, "records": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "type": "string", "enum": [ "BRAND", "EID", "MANAGEMENT_TAG", "NAME", "TATTOO" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "animal_id": { "type": "string" }, "is_primary": { "type": "boolean" } }, "required": [ "value", "type", "id", "created_at", "updated_at", "is_active", "animal_id", "is_primary" ] } } }, "required": [ "total", "records" ] }, "example": { "total": 0, "records": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/animalIdentifier.ts", "x-required-scopes": [ "read:animals" ], "x-minimum-role": "READER" }, "post": { "operationId": "post_v1_farm_farm_id_animals_animal_id_identifier", "tags": [ "identifiers" ], "summary": "Create Animal Identifier", "description": "Current animal identifiers HTTP operation. External credential scopes: write:animals. 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "animal_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "type": "string", "enum": [ "BRAND", "EID", "MANAGEMENT_TAG", "NAME", "TATTOO" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "animal_id": { "type": "string" }, "is_primary": { "type": "boolean" } }, "required": [ "value", "type", "id", "created_at", "updated_at", "is_active", "animal_id", "is_primary" ] }, "example": { "value": "EXAMPLE-001", "type": "BRAND", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "is_active": true, "animal_id": "11111111-1111-4111-8111-111111111111", "is_primary": true } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/animalIdentifier.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "BRAND", "EID", "MANAGEMENT_TAG", "NAME", "TATTOO" ] }, "value": { "type": "string" }, "is_primary": { "type": "boolean" } }, "required": [ "type", "value" ] }, "example": { "type": "BRAND", "value": "EXAMPLE-001" } } } }, "x-required-scopes": [ "write:animals" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/animals/{animal_id}/identifier/{animal_identifier_id}": { "delete": { "operationId": "delete_v1_farm_farm_id_animals_animal_id_identifier_animal_identifier_id", "tags": [ "identifiers" ], "summary": "Delete Animal Identifier", "description": "Current animal identifiers HTTP operation. External credential scopes: write:animals. Minimum farm role: OWNER. 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. Marks the stored entity inactive (soft deletion).", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "animal_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "animal_identifier_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Completed; no response body." }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/animalIdentifier.ts", "x-required-scopes": [ "write:animals" ], "x-minimum-role": "OWNER" }, "get": { "operationId": "get_v1_farm_farm_id_animals_animal_id_identifier_animal_identifier_id", "tags": [ "identifiers" ], "summary": "Get Animal Identifier", "description": "Current animal identifiers HTTP operation. External credential scopes: read:animals. 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. Current legacy behavior: returns the active parent animal, not an identifier. The identifier id is not used by this handler. Use the identifier collection to retrieve identifiers.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "animal_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "animal_identifier_id", "required": true, "schema": { "type": "string" }, "description": "Ignored and not validated by this legacy detail handler." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "metadata": {} }, "required": [ "id", "created_at", "updated_at", "is_active", "farm_id", "metadata" ] }, "example": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "metadata": null } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/animalIdentifier.ts", "x-required-scopes": [ "read:animals" ], "x-minimum-role": "READER" }, "put": { "operationId": "put_v1_farm_farm_id_animals_animal_id_identifier_animal_identifier_id", "tags": [ "identifiers" ], "summary": "Update Animal Identifier", "description": "Current animal identifiers HTTP operation. External credential scopes: write:animals. 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "animal_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "animal_identifier_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "string" }, "type": { "type": "string", "enum": [ "BRAND", "EID", "MANAGEMENT_TAG", "NAME", "TATTOO" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "animal_id": { "type": "string" }, "is_primary": { "type": "boolean" } }, "required": [ "value", "type", "id", "created_at", "updated_at", "is_active", "animal_id", "is_primary" ] }, "example": { "value": "EXAMPLE-001", "type": "BRAND", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "is_active": true, "animal_id": "11111111-1111-4111-8111-111111111111", "is_primary": true } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/animalIdentifier.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "BRAND", "EID", "MANAGEMENT_TAG", "NAME", "TATTOO" ] }, "value": { "type": "string" }, "is_primary": { "type": "boolean" } } }, "example": {} } } }, "x-required-scopes": [ "write:animals" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/animals/find-or-create-by-eid": { "post": { "operationId": "post_v1_farm_farm_id_animals_find_or_create_by_eid", "tags": [ "animals" ], "summary": "Find Or Create Animal By Eid", "description": "Current animals HTTP operation. External credential scopes: write:animals. 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Existing match returned.", "content": { "application/json": { "schema": { "type": "object", "properties": { "animal": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "metadata": {}, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } }, "animal_identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/AnimalIdentifier" } } }, "required": [ "id", "created_at", "updated_at", "is_active", "farm_id", "metadata", "groups", "animal_identifiers" ] }, "created": { "type": "boolean" } }, "required": [ "animal", "created" ] }, "example": { "animal": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "metadata": null, "groups": [], "animal_identifiers": [] }, "created": true } } } }, "201": { "description": "New animal created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "animal": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "metadata": {}, "groups": { "type": "array", "items": { "$ref": "#/components/schemas/Group" } }, "animal_identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/AnimalIdentifier" } } }, "required": [ "id", "created_at", "updated_at", "is_active", "farm_id", "metadata", "groups", "animal_identifiers" ] }, "created": { "type": "boolean" } }, "required": [ "animal", "created" ] }, "example": { "animal": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "metadata": null, "groups": [], "animal_identifiers": [] }, "created": true } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/animal.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "eid": { "type": "string" } }, "required": [ "eid" ] }, "example": { "eid": "example" } } } }, "x-required-scopes": [ "write:animals" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/animals/index": { "get": { "operationId": "get_v1_farm_farm_id_animals_index", "tags": [ "animals" ], "summary": "Get Animals Index", "description": "Current animals HTTP operation. External credential scopes: read:animals. 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "synced_at": { "type": "string" }, "total": { "type": "number" }, "animals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "metadata": {}, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "BRAND", "EID", "MANAGEMENT_TAG", "NAME", "TATTOO" ] }, "value": { "type": "string" }, "is_primary": { "type": "boolean" } }, "required": [ "type", "value", "is_primary" ] } }, "last_weights": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "number" }, "unit": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "applied_at": { "type": "string", "format": "date-time" } }, "required": [ "value", "unit", "applied_at" ] } } }, "required": [ "id", "metadata", "identifiers", "last_weights" ] } } }, "required": [ "synced_at", "total", "animals" ] }, "example": { "synced_at": "2026-09-01T12:00:00.000Z", "total": 1, "animals": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/animal.ts", "x-required-scopes": [ "read:animals" ], "x-minimum-role": "READER" } }, "/v1/farm/{farm_id}/chute-sessions": { "get": { "operationId": "get_v1_farm_farm_id_chute_sessions", "tags": [ "chute-sessions" ], "summary": "Get Chute Sessions", "description": "Current chute sessions 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "skip", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "take", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "COMPLETED", "PROPOSED" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "number" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "COMPLETED", "PROPOSED" ] }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "group_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "entry_count": { "type": "number" } }, "required": [ "id", "name", "status", "started_at", "completed_at", "group_id", "entry_count" ] } } }, "required": [ "total", "records" ] }, "example": { "total": 0, "records": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/chuteSession.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" }, "post": { "operationId": "post_v1_farm_farm_id_chute_sessions", "tags": [ "chute-sessions" ], "summary": "Create Chute Session", "description": "Current chute sessions 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "COMPLETED", "PROPOSED" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "group_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "completed_at": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "config": {}, "started_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "id", "created_at", "updated_at", "name", "is_active", "farm_id", "group_id", "completed_at", "config", "started_at" ] }, "example": { "status": "ACTIVE", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "group_id": null, "completed_at": null, "config": null, "started_at": "2026-09-01T12:00:00.000Z" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/chuteSession.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "config": { "type": "object", "properties": { "widgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "boolean", "number", "photo", "score", "select", "text", "treatment", "weight" ] }, "label": { "type": "string", "minLength": 1 }, "size": { "type": "string", "enum": [ "full", "half" ] }, "options": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "type", "label" ] }, "minItems": 1 }, "new_animal_fields": { "type": "array", "items": { "type": "string" } }, "record_type": { "type": "string", "enum": [ "FEED", "GENETIC", "HEALTH", "MOVEMENT", "OTHER" ] } }, "required": [ "widgets" ] }, "group_id": { "type": "string", "format": "uuid" } }, "required": [ "config" ] }, "example": { "config": { "widgets": [ { "id": "11111111-1111-4111-8111-111111111111", "type": "boolean", "label": "example" } ] } } } } }, "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/chute-sessions/{session_id}": { "delete": { "operationId": "delete_v1_farm_farm_id_chute_sessions_session_id", "tags": [ "chute-sessions" ], "summary": "Delete Chute Session", "description": "Current chute sessions 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. Deletion behavior is described below; a successful status does not imply erasure from all retained history. Deletes the chute session through its service; associated history has separate undo behavior. Only PROPOSED sessions can be changed or deactivated; started sessions reject this operation with 400.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "session_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Completed; no response body." }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/chuteSession.ts", "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" }, "get": { "operationId": "get_v1_farm_farm_id_chute_sessions_session_id", "tags": [ "chute-sessions" ], "summary": "Get Chute Session", "description": "Current chute sessions 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "session_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "COMPLETED", "PROPOSED" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "group_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "completed_at": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "config": {}, "started_at": { "type": "string", "format": "date-time" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/ChuteSessionEntryWithAnimal" } } }, "required": [ "status", "id", "created_at", "updated_at", "name", "is_active", "farm_id", "group_id", "completed_at", "config", "started_at", "entries" ] }, "example": { "status": "ACTIVE", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Weighing", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "group_id": null, "completed_at": null, "config": { "widgets": [] }, "started_at": "2026-09-01T12:00:00.000Z", "entries": [ { "id": "11111111-1111-4111-8111-111111111111", "animal_id": "11111111-1111-4111-8111-111111111111", "session_id": "11111111-1111-4111-8111-111111111111", "captured_at": "2026-09-01T12:00:00.000Z", "client_updated_at": "2026-09-01T12:00:00.000Z", "is_active": true, "payload": { "weight": 125 }, "position": 0, "record_ids": [ "11111111-1111-4111-8111-111111111111" ], "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "animal": { "id": "11111111-1111-4111-8111-111111111111", "farm_id": "11111111-1111-4111-8111-111111111111", "is_active": true, "metadata": null, "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "animal_identifiers": [ { "id": "11111111-1111-4111-8111-111111111111", "animal_id": "11111111-1111-4111-8111-111111111111", "is_active": true, "is_primary": true, "type": "MANAGEMENT_TAG", "value": "Ewe 42", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z" } ] } } ] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/chuteSession.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" }, "put": { "operationId": "put_v1_farm_farm_id_chute_sessions_session_id", "tags": [ "chute-sessions" ], "summary": "Update Chute Session", "description": "Current chute sessions 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. Only PROPOSED sessions can be changed or deactivated; started sessions reject this operation with 400.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "session_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "COMPLETED", "PROPOSED" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "group_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "completed_at": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "config": {}, "started_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "id", "created_at", "updated_at", "name", "is_active", "farm_id", "group_id", "completed_at", "config", "started_at" ] }, "example": { "status": "ACTIVE", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "group_id": null, "completed_at": null, "config": null, "started_at": "2026-09-01T12:00:00.000Z" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/chuteSession.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "config": { "type": "object", "properties": { "widgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "boolean", "number", "photo", "score", "select", "text", "treatment", "weight" ] }, "label": { "type": "string", "minLength": 1 }, "size": { "type": "string", "enum": [ "full", "half" ] }, "options": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "type", "label" ] }, "minItems": 1 }, "new_animal_fields": { "type": "array", "items": { "type": "string" } }, "record_type": { "type": "string", "enum": [ "FEED", "GENETIC", "HEALTH", "MOVEMENT", "OTHER" ] } }, "required": [ "widgets" ] }, "group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } } }, "example": {} } } }, "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/chute-sessions/{session_id}/entries/{entry_id}/undo": { "post": { "operationId": "post_v1_farm_farm_id_chute_sessions_session_id_entries_entry_id_undo", "tags": [ "chute-sessions" ], "summary": "Undo Chute Entry", "description": "Current chute sessions 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "session_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "entry_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "entry_id": { "type": "string" }, "undone": { "type": "boolean" } }, "required": [ "entry_id", "undone" ] }, "example": { "entry_id": "11111111-1111-4111-8111-111111111111", "undone": true } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/chuteSession.ts", "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/chute-sessions/{session_id}/sync": { "post": { "operationId": "post_v1_farm_farm_id_chute_sessions_session_id_sync", "tags": [ "chute-sessions" ], "summary": "Sync Chute Session", "description": "Current chute sessions HTTP operation. External credential scopes: write:records, write:animals, write:groups. 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "session_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "COMPLETED", "PROPOSED" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "group_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "completed_at": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "config": {}, "started_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "id", "created_at", "updated_at", "name", "is_active", "farm_id", "group_id", "completed_at", "config", "started_at" ] }, "animal_mappings": { "type": "array", "items": { "type": "object", "properties": { "client_animal_id": { "type": "string" }, "animal_id": { "type": "string" }, "created": { "type": "boolean" } }, "required": [ "client_animal_id", "animal_id", "created" ] } }, "results": { "type": "array", "items": { "type": "object", "properties": { "entry_id": { "type": "string" }, "status": { "type": "string", "enum": [ "error", "created", "updated", "unchanged", "deleted" ] }, "animal_id": { "type": "string" }, "record_ids": { "type": "array", "items": { "type": "string" } }, "record_items": { "type": "array", "items": { "type": "object", "properties": { "widget_id": { "type": "string" }, "record_item_id": { "type": "string" } }, "required": [ "widget_id", "record_item_id" ] } }, "error": { "type": "string" } }, "required": [ "entry_id", "status" ] } } }, "required": [ "session", "animal_mappings", "results" ] }, "example": { "session": { "status": "ACTIVE", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "group_id": null, "completed_at": null, "config": null, "started_at": "2026-09-01T12:00:00.000Z" }, "animal_mappings": [], "results": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/chuteSession.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "ACTIVE", "COMPLETED" ] }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "config": { "type": "object", "properties": { "widgets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "boolean", "number", "photo", "score", "select", "text", "treatment", "weight" ] }, "label": { "type": "string", "minLength": 1 }, "size": { "type": "string", "enum": [ "full", "half" ] }, "options": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "type", "label" ] }, "minItems": 1 }, "new_animal_fields": { "type": "array", "items": { "type": "string" } }, "record_type": { "type": "string", "enum": [ "FEED", "GENETIC", "HEALTH", "MOVEMENT", "OTHER" ] } }, "required": [ "widgets" ] }, "group_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "name", "status", "started_at", "config" ] }, "entries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "animal": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "is_new": { "type": "boolean" }, "identifiers": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "BRAND", "EID", "MANAGEMENT_TAG", "NAME", "TATTOO" ] }, "value": { "type": "string", "minLength": 1 } }, "required": [ "type", "value" ] } }, "metadata": { "type": "object", "additionalProperties": {} } }, "required": [ "id" ] }, "position": { "type": "integer", "minimum": 0 }, "payload": { "type": "object", "additionalProperties": {} }, "captured_at": { "type": "string", "format": "date-time" }, "client_updated_at": { "type": "string", "format": "date-time" }, "deleted": { "type": "boolean" } }, "required": [ "id", "animal", "position", "payload", "captured_at", "client_updated_at" ] } } }, "required": [ "session", "entries" ] }, "example": { "session": { "name": "Example", "status": "ACTIVE", "started_at": "2026-09-01T12:00:00.000Z", "config": { "widgets": [ { "id": "11111111-1111-4111-8111-111111111111", "type": "boolean", "label": "example" } ] } }, "entries": [] } } } }, "x-required-scopes": [ "write:records", "write:animals", "write:groups" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/exports": { "get": { "operationId": "get_v1_farm_farm_id_exports", "tags": [ "exports" ], "summary": "GET /v1/farm/{farm_id}/exports", "description": "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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "exports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "farm_id": { "type": "string" }, "status": { "type": "string" }, "sha256": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "bytes": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "error": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "farm_id", "status", "sha256", "bytes", "error", "created_at", "expires_at" ] } } }, "required": [ "exports" ] }, "example": { "exports": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/farmExport.ts", "x-required-scopes": [ "read:exports" ], "x-minimum-role": "READER" }, "post": { "operationId": "post_v1_farm_farm_id_exports", "tags": [ "exports" ], "summary": "POST /v1/farm/{farm_id}/exports", "description": "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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "farm_id": { "type": "string" }, "status": { "type": "string" }, "sha256": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "bytes": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "error": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "farm_id", "status", "sha256", "bytes", "error", "created_at", "expires_at" ] }, "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" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/farmExport.ts", "x-required-scopes": [ "read:exports" ], "x-minimum-role": "READER" } }, "/v1/farm/{farm_id}/exports/{export_id}": { "delete": { "operationId": "delete_v1_farm_farm_id_exports_export_id", "tags": [ "exports" ], "summary": "DELETE /v1/farm/{farm_id}/exports/{export_id}", "description": "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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "export_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "farm_id": { "type": "string" }, "status": { "type": "string" }, "sha256": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "bytes": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "error": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "farm_id", "status", "sha256", "bytes", "error", "created_at", "expires_at" ] }, "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" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/farmExport.ts", "x-required-scopes": [ "read:exports" ], "x-minimum-role": "READER" }, "get": { "operationId": "get_v1_farm_farm_id_exports_export_id", "tags": [ "exports" ], "summary": "GET /v1/farm/{farm_id}/exports/{export_id}", "description": "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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "export_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "farm_id": { "type": "string" }, "status": { "type": "string" }, "sha256": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "bytes": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "error": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "farm_id", "status", "sha256", "bytes", "error", "created_at", "expires_at" ] }, "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" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/farmExport.ts", "x-required-scopes": [ "read:exports" ], "x-minimum-role": "READER" } }, "/v1/farm/{farm_id}/exports/{export_id}/download": { "get": { "operationId": "get_v1_farm_farm_id_exports_export_id_download", "tags": [ "exports" ], "summary": "GET /v1/farm/{farm_id}/exports/{export_id}/download", "description": "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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "export_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "ZIP archive stream.", "headers": { "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-SHA256": { "schema": { "type": "string" } }, "Content-Length": { "schema": { "type": "string" } } }, "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/farmExport.ts", "x-required-scopes": [ "read:exports" ], "x-minimum-role": "READER" }, "post": { "operationId": "post_v1_farm_farm_id_exports_export_id_download", "tags": [ "exports" ], "summary": "POST /v1/farm/{farm_id}/exports/{export_id}/download", "description": "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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "export_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "ZIP archive stream.", "headers": { "Content-Disposition": { "schema": { "type": "string" } }, "X-Content-SHA256": { "schema": { "type": "string" } }, "Content-Length": { "schema": { "type": "string" } } }, "content": { "application/zip": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/farmExport.ts", "x-required-scopes": [ "read:exports" ], "x-minimum-role": "READER" } }, "/v1/farm/{farm_id}/feed-plan": { "get": { "operationId": "get_v1_farm_farm_id_feed_plan", "tags": [ "feeding-plans" ], "summary": "Get Feed Plan", "description": "Current feeding plans 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "since", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "synced_at": { "type": "string" }, "rations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "unit": { "type": "string" }, "ingredients": { "type": "array", "items": { "$ref": "#/components/schemas/FeedPlanIngredient" } } }, "required": [ "id", "name", "unit", "ingredients" ] } }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "ration_id": { "type": "string" }, "group_id": { "type": "string" }, "feedings_per_day": { "type": "number" }, "label": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "group": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "head_count": { "type": "number" } }, "required": [ "id", "name", "head_count" ] } }, "required": [ "id", "ration_id", "group_id", "feedings_per_day", "label", "group" ] } }, "recent_deliveries": { "type": "array", "items": { "type": "object", "properties": { "feeding_id": { "type": "string" }, "ration_id": { "type": "string" }, "group_id": { "type": "string" }, "fed_at": { "type": "string", "format": "date-time" }, "delivered_lbs": { "type": "string", "description": "Decimal value serialized as a JSON string.", "examples": [ "12.5" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "COMPLETED" ] } }, "required": [ "feeding_id", "ration_id", "group_id", "fed_at", "delivered_lbs", "status" ] } } }, "required": [ "synced_at", "rations", "assignments", "recent_deliveries" ] }, "example": { "synced_at": "2026-09-01T12:00:00.000Z", "rations": [ { "id": "11111111-1111-4111-8111-111111111111", "name": "Hay ration", "unit": "lb", "ingredients": [ { "id": "11111111-1111-4111-8111-111111111111", "name": "Hay", "per_head_lbs": "5.25", "position": 0 } ] } ], "assignments": [ { "id": "11111111-1111-4111-8111-111111111111", "ration_id": "11111111-1111-4111-8111-111111111111", "group_id": "11111111-1111-4111-8111-111111111111", "feedings_per_day": 2, "label": null, "group": { "id": "11111111-1111-4111-8111-111111111111", "name": "Ewes", "head_count": 10 } } ], "recent_deliveries": [ { "feeding_id": "11111111-1111-4111-8111-111111111111", "ration_id": "11111111-1111-4111-8111-111111111111", "group_id": "11111111-1111-4111-8111-111111111111", "fed_at": "2026-09-01T12:00:00.000Z", "delivered_lbs": "12.5", "status": "ACTIVE" } ] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/feedPlan.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" } }, "/v1/farm/{farm_id}/feedings": { "get": { "operationId": "get_v1_farm_farm_id_feedings", "tags": [ "feedings" ], "summary": "Get Feedings", "description": "Current feedings 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "skip", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "take", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "COMPLETED" ] } }, { "in": "query", "name": "since", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "number" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "ration_id": { "type": "string" }, "ration_name": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "COMPLETED" ] }, "fed_at": { "type": "string", "format": "date-time" }, "scale_factor": { "type": "string", "description": "Decimal value serialized as a JSON string.", "examples": [ "12.5" ] }, "delivery_count": { "type": "number" }, "total_delivered_lbs": { "type": "number" } }, "required": [ "id", "ration_id", "ration_name", "status", "fed_at", "scale_factor", "delivery_count", "total_delivered_lbs" ] } } }, "required": [ "total", "records" ] }, "example": { "total": 1, "records": [ { "id": "11111111-1111-4111-8111-111111111111", "ration_id": "11111111-1111-4111-8111-111111111111", "ration_name": "Hay ration", "status": "ACTIVE", "fed_at": "2026-09-01T12:00:00.000Z", "scale_factor": "1.25", "delivery_count": 1, "total_delivered_lbs": 12.5 } ] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/feeding.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" } }, "/v1/farm/{farm_id}/feedings/{feeding_id}": { "get": { "operationId": "get_v1_farm_farm_id_feedings_feeding_id", "tags": [ "feedings" ], "summary": "Get Feeding", "description": "Current feedings 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "feeding_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "COMPLETED" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "ingredients": {}, "ration_id": { "type": "string" }, "client_updated_at": { "type": "string", "format": "date-time" }, "fed_at": { "type": "string", "format": "date-time" }, "scale_factor": { "type": "string", "description": "Decimal value serialized as a JSON string.", "examples": [ "12.5" ] }, "ration": { "$ref": "#/components/schemas/RationIdentity" }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/FeedingDeliveryWithGroup" } } }, "required": [ "status", "id", "created_at", "updated_at", "is_active", "farm_id", "ingredients", "ration_id", "client_updated_at", "fed_at", "scale_factor", "ration", "deliveries" ] }, "example": { "status": "ACTIVE", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "ingredients": [ { "name": "Hay", "per_head_lbs": 5.25, "position": 0, "target_lbs": 12.5, "actual_lbs": 12.5 } ], "ration_id": "11111111-1111-4111-8111-111111111111", "client_updated_at": "2026-09-01T12:00:00.000Z", "fed_at": "2026-09-01T12:00:00.000Z", "scale_factor": "1.25", "ration": { "id": "11111111-1111-4111-8111-111111111111", "name": "Hay ration", "unit": "lb" }, "deliveries": [ { "id": "11111111-1111-4111-8111-111111111111", "feeding_id": "11111111-1111-4111-8111-111111111111", "group_id": "11111111-1111-4111-8111-111111111111", "actual_lbs": "12.5", "client_updated_at": "2026-09-01T12:00:00.000Z", "head_count": 10, "is_active": true, "record_id": null, "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "group": { "id": "11111111-1111-4111-8111-111111111111", "name": "Ewes" } } ] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/feeding.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" } }, "/v1/farm/{farm_id}/feedings/{feeding_id}/sync": { "post": { "operationId": "post_v1_farm_farm_id_feedings_feeding_id_sync", "tags": [ "feedings" ], "summary": "Sync Feeding", "description": "Current feedings 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "feeding_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "feeding": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "COMPLETED" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "ingredients": {}, "ration_id": { "type": "string" }, "client_updated_at": { "type": "string", "format": "date-time" }, "fed_at": { "type": "string", "format": "date-time" }, "scale_factor": { "type": "string", "description": "Decimal value serialized as a JSON string.", "examples": [ "12.5" ] } }, "required": [ "status", "id", "created_at", "updated_at", "is_active", "farm_id", "ingredients", "ration_id", "client_updated_at", "fed_at", "scale_factor" ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "delivery_id": { "type": "string" }, "status": { "type": "string", "enum": [ "error", "created", "updated", "unchanged", "deleted" ] }, "record_id": { "type": "string" }, "error": { "type": "string" } }, "required": [ "delivery_id", "status" ] } } }, "required": [ "feeding", "results" ] }, "example": { "feeding": { "status": "ACTIVE", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "ingredients": null, "ration_id": "11111111-1111-4111-8111-111111111111", "client_updated_at": "2026-09-01T12:00:00.000Z", "fed_at": "2026-09-01T12:00:00.000Z", "scale_factor": "1.25" }, "results": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/feeding.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "feeding": { "type": "object", "properties": { "ration_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "ACTIVE", "COMPLETED" ] }, "fed_at": { "type": "string", "format": "date-time" }, "scale_factor": { "type": "number", "exclusiveMinimum": 0 }, "ingredients": { "type": "array", "items": { "type": "object", "properties": { "ingredient_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1 }, "per_head_lbs": { "type": "number", "minimum": 0 }, "position": { "type": "integer", "minimum": 0 }, "target_lbs": { "type": "number", "minimum": 0 }, "actual_lbs": { "type": "number", "minimum": 0 }, "skipped": { "type": "boolean" } }, "required": [ "name", "per_head_lbs", "position", "target_lbs" ] }, "minItems": 1 }, "client_updated_at": { "type": "string", "format": "date-time" } }, "required": [ "ration_id", "status", "fed_at", "scale_factor", "ingredients", "client_updated_at" ] }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "group_id": { "type": "string", "format": "uuid" }, "head_count": { "type": "integer", "minimum": 0 }, "actual_lbs": { "type": "number", "minimum": 0 }, "client_updated_at": { "type": "string", "format": "date-time" }, "deleted": { "type": "boolean" } }, "required": [ "id", "group_id", "head_count", "actual_lbs", "client_updated_at" ] } } }, "required": [ "feeding", "deliveries" ] }, "example": { "feeding": { "ration_id": "11111111-1111-4111-8111-111111111111", "status": "ACTIVE", "fed_at": "2026-09-01T12:00:00.000Z", "scale_factor": 1, "ingredients": [ { "name": "Example", "per_head_lbs": 1, "position": 1, "target_lbs": 1 } ], "client_updated_at": "2026-09-01T12:00:00.000Z" }, "deliveries": [] } } } }, "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/feedings/{feeding_id}/undo": { "post": { "operationId": "post_v1_farm_farm_id_feedings_feeding_id_undo", "tags": [ "feedings" ], "summary": "Undo Feeding", "description": "Current feedings 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "feeding_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "feeding_id": { "type": "string" }, "undone": { "type": "boolean" } }, "required": [ "feeding_id", "undone" ] }, "example": { "feeding_id": "11111111-1111-4111-8111-111111111111", "undone": true } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/feeding.ts", "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/groups": { "get": { "operationId": "get_v1_farm_farm_id_groups", "tags": [ "groups" ], "summary": "Get Groups", "description": "Current groups HTTP operation. External credential scopes: read:groups. 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. archived uses JavaScript boolean coercion: any nonempty query string, including false, is true. Omit this parameter for active groups.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "skip", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "take", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "archived", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "number" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "animals": { "type": "array", "items": { "$ref": "#/components/schemas/Animal" } } }, "required": [ "id", "created_at", "updated_at", "name", "is_active", "farm_id", "description", "animals" ] } } }, "required": [ "total", "records" ] }, "example": { "total": 0, "records": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/group.ts", "x-required-scopes": [ "read:groups" ], "x-minimum-role": "READER" }, "post": { "operationId": "post_v1_farm_farm_id_groups", "tags": [ "groups" ], "summary": "Create Group", "description": "Current groups HTTP operation. External credential scopes: write:groups. 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "id", "created_at", "updated_at", "name", "is_active", "farm_id", "description" ] }, "example": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "description": null } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/group.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name" ] }, "example": { "name": "Example" } } } }, "x-required-scopes": [ "write:groups" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/groups/{group_id}": { "delete": { "operationId": "delete_v1_farm_farm_id_groups_group_id", "tags": [ "groups" ], "summary": "Delete Group", "description": "Current groups HTTP operation. External credential scopes: write:groups. Minimum farm role: OWNER. 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. Marks the stored entity inactive (soft deletion).", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "group_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Completed; no response body." }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/group.ts", "x-required-scopes": [ "write:groups" ], "x-minimum-role": "OWNER" }, "get": { "operationId": "get_v1_farm_farm_id_groups_group_id", "tags": [ "groups" ], "summary": "Get Group", "description": "Current groups HTTP operation. External credential scopes: read:groups. 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "group_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "animals": { "type": "array", "items": { "$ref": "#/components/schemas/Animal" } } }, "required": [ "id", "created_at", "updated_at", "name", "is_active", "farm_id", "description", "animals" ] }, "example": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "description": null, "animals": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/group.ts", "x-required-scopes": [ "read:groups" ], "x-minimum-role": "READER" }, "put": { "operationId": "put_v1_farm_farm_id_groups_group_id", "tags": [ "groups" ], "summary": "Update Group", "description": "Current groups HTTP operation. External credential scopes: write:groups. 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "group_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "id", "created_at", "updated_at", "name", "is_active", "farm_id", "description" ] }, "example": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "description": null } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/group.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "animal_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "example": {} } } }, "x-required-scopes": [ "write:groups" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/groups/{group_id}/restore": { "post": { "operationId": "post_v1_farm_farm_id_groups_group_id_restore", "tags": [ "groups" ], "summary": "Restore Group", "description": "Current groups HTTP operation. External credential scopes: write:groups. Minimum farm role: OWNER. 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "group_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "id", "created_at", "updated_at", "name", "is_active", "farm_id", "description" ] }, "example": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "description": null } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/group.ts", "x-required-scopes": [ "write:groups" ], "x-minimum-role": "OWNER" } }, "/v1/farm/{farm_id}/import": { "get": { "operationId": "get_v1_farm_farm_id_import", "tags": [ "imports" ], "summary": "Get Imports", "description": "Current legacy imports 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "skip", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "take", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "COMPLETED", "FAILED", "PENDING", "PROCESSING" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "records": { "type": "array", "items": { "$ref": "#/components/schemas/ImportWithRelations" } }, "total": { "type": "number" } }, "required": [ "records", "total" ] }, "example": { "records": [ { "status": "PENDING", "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", "metadata": null, "completed_at": null, "file_id": "11111111-1111-4111-8111-111111111111", "error_message": null, "format": "CSV", "file": { "id": "11111111-1111-4111-8111-111111111111", "name": "flock.csv", "mime_type": "text/csv", "size": 128, "url": "https://example.com/flock.csv", "is_active": true, "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z" }, "user": { "id": "11111111-1111-4111-8111-111111111111", "full_name": null, "phone_number_local": null } } ], "total": 1 } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/import.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" }, "post": { "operationId": "post_v1_farm_farm_id_import", "tags": [ "imports" ], "summary": "Create Import", "description": "Current legacy imports 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. Known current limitation: upload middleware populates req.file while the handler expects req.files. A normal single-file upload returns 400 No file provided. This route is not a working import walkthrough; use import requests for supervised intake.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "description": "Error", "content": { "application/json": { "schema": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "data": { "type": "null" }, "success": { "type": "boolean" } }, "required": [ "errors", "data", "success" ] }, { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "data": { "type": "null" }, "success": { "type": "boolean" } }, "required": [ "errors", "data", "success" ] } ] }, { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "data": { "type": "null" }, "success": { "type": "boolean" } }, "required": [ "errors", "data", "success" ] } ] }, "example": { "errors": [], "data": null, "success": true } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "data": { "type": "null" }, "success": { "type": "boolean" } }, "required": [ "errors", "data", "success" ] }, "example": { "errors": [], "data": null, "success": true } } } } }, "x-source": "api/src/lib/controllers/import.ts", "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } } } }, "/v1/farm/{farm_id}/import-request": { "get": { "operationId": "get_v1_farm_farm_id_import_request", "tags": [ "import-requests" ], "summary": "Get Import Requests", "description": "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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "skip", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "take", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "COMPLETED", "FAILED", "PENDING", "PROCESSING" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "number" }, "import_requests": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "COMPLETED", "FAILED", "PENDING", "PROCESSING" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string" }, "farm_id": { "type": "string" }, "completed_at": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "note": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "summary": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "mime_type": { "type": "string" }, "size": { "type": "number" }, "url": { "type": "string" } }, "required": [ "id", "created_at", "updated_at", "name", "is_active", "mime_type", "size", "url" ] } } }, "required": [ "status", "id", "created_at", "updated_at", "user_id", "farm_id", "completed_at", "note", "summary", "files" ] } } }, "required": [ "total", "import_requests" ] }, "example": { "total": 1, "import_requests": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/importRequest.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" }, "post": { "operationId": "post_v1_farm_farm_id_import_request", "tags": [ "import-requests" ], "summary": "Create Import Request", "description": "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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "import_request": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "COMPLETED", "FAILED", "PENDING", "PROCESSING" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string" }, "farm_id": { "type": "string" }, "completed_at": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "note": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "summary": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "mime_type": { "type": "string" }, "size": { "type": "number" }, "url": { "type": "string" } }, "required": [ "id", "created_at", "updated_at", "name", "is_active", "mime_type", "size", "url" ] } } }, "required": [ "status", "id", "created_at", "updated_at", "user_id", "farm_id", "completed_at", "note", "summary", "files" ] } }, "required": [ "import_request" ] }, "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": { "description": "Error", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "data": { "type": "null" }, "success": { "type": "boolean" } }, "required": [ "errors", "data", "success" ] }, { "$ref": "#/components/schemas/Error" } ] }, "example": { "success": false, "data": null, "errors": [ { "message": "No files provided" } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/importRequest.ts", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "files" ], "properties": { "note": { "type": "string", "maxLength": 2000 }, "files": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "format": "binary" } } } } } } }, "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/import-request/{import_request_id}": { "get": { "operationId": "get_v1_farm_farm_id_import_request_import_request_id", "tags": [ "import-requests" ], "summary": "Get Import Request", "description": "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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "import_request_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "import_request": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "COMPLETED", "FAILED", "PENDING", "PROCESSING" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string" }, "farm_id": { "type": "string" }, "completed_at": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "note": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "summary": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "mime_type": { "type": "string" }, "size": { "type": "number" }, "url": { "type": "string" } }, "required": [ "id", "created_at", "updated_at", "name", "is_active", "mime_type", "size", "url" ] } } }, "required": [ "status", "id", "created_at", "updated_at", "user_id", "farm_id", "completed_at", "note", "summary", "files" ] } }, "required": [ "import_request" ] }, "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": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/importRequest.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" } }, "/v1/farm/{farm_id}/import/{import_id}": { "get": { "operationId": "get_v1_farm_farm_id_import_import_id", "tags": [ "imports" ], "summary": "Get Import", "description": "Current legacy imports 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "import_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportDetail" }, "example": { "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", "metadata": null, "completed_at": "2026-09-01T12:00:00.000Z", "file_id": "11111111-1111-4111-8111-111111111111", "error_message": null, "format": "CSV", "file": { "id": "11111111-1111-4111-8111-111111111111", "name": "flock.csv", "mime_type": "text/csv", "size": 128, "url": "https://example.com/flock.csv", "is_active": true, "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z" }, "user": { "id": "11111111-1111-4111-8111-111111111111", "full_name": null, "phone_number_local": null }, "import_items": [ { "id": "55555555-5555-4555-8555-555555555555", "action_id": "44444444-4444-4444-8444-444444444444", "import_id": "11111111-1111-4111-8111-111111111111", "entity_id": "22222222-2222-4222-8222-222222222222", "entity_type": "ANIMAL", "error_message": null, "mapped_data": { "metadata": { "tag": "42" } }, "row_number": 1, "source_data": { "tag": "42" }, "status": "PROCESSED", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "action": { "id": "44444444-4444-4444-8444-444444444444", "agent_action_id": null, "action_type": "CREATE", "entity_id": "22222222-2222-4222-8222-222222222222", "entity_type": "ANIMAL", "state_before": null, "state_after": { "id": "22222222-2222-4222-8222-222222222222", "metadata": { "tag": "42" } }, "undone_at": null, "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z" } } ] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/import.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" } }, "/v1/farm/{farm_id}/import/{import_id}/changes": { "get": { "operationId": "get_v1_farm_farm_id_import_import_id_changes", "tags": [ "imports" ], "summary": "Get Import Changes", "description": "Current legacy imports 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "import_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "import": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "COMPLETED", "FAILED", "PENDING", "PROCESSING" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string" }, "farm_id": { "type": "string" }, "metadata": {}, "completed_at": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "file_id": { "type": "string" }, "error_message": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "format": { "type": "string", "enum": [ "CSV", "JSON" ] } }, "required": [ "status", "id", "created_at", "updated_at", "user_id", "farm_id", "metadata", "completed_at", "file_id", "error_message", "format" ] }, "changes": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/ImportItemWithAction" }, { "type": "object", "properties": { "action_id": { "type": "string" }, "action": { "$ref": "#/components/schemas/Action" } }, "required": [ "action_id", "action" ] } ] } } }, "required": [ "import", "changes" ] }, "example": { "import": { "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", "metadata": null, "completed_at": "2026-09-01T12:00:00.000Z", "file_id": "11111111-1111-4111-8111-111111111111", "error_message": null, "format": "CSV" }, "changes": [ { "id": "55555555-5555-4555-8555-555555555555", "action_id": "44444444-4444-4444-8444-444444444444", "import_id": "11111111-1111-4111-8111-111111111111", "entity_id": "22222222-2222-4222-8222-222222222222", "entity_type": "ANIMAL", "error_message": null, "mapped_data": { "metadata": { "tag": "42" } }, "row_number": 1, "source_data": { "tag": "42" }, "status": "PROCESSED", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "action": { "id": "44444444-4444-4444-8444-444444444444", "agent_action_id": null, "action_type": "CREATE", "entity_id": "22222222-2222-4222-8222-222222222222", "entity_type": "ANIMAL", "state_before": null, "state_after": { "id": "22222222-2222-4222-8222-222222222222", "metadata": { "tag": "42" } }, "undone_at": null, "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z" } } ] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/import.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" } }, "/v1/farm/{farm_id}/memory": { "get": { "operationId": "get_v1_farm_farm_id_memory", "tags": [ "memory" ], "summary": "Get Memories", "description": "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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "grouped", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Only the literal true selects grouped versions; otherwise returns current memories." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "memories": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "current": { "type": "object", "properties": { "id": { "type": "string" }, "farm_id": { "type": "string" }, "key": { "type": "string" }, "value": {}, "provenance": {}, "source": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "confidence": { "anyOf": [ { "type": "null" }, { "type": "number" } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "farm_id", "key", "value", "source", "confidence", "created_at", "updated_at" ] }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "value": {}, "source": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "provenance": {}, "confidence": { "anyOf": [ { "type": "null" }, { "type": "number" } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "value", "source", "provenance", "confidence", "created_at", "updated_at" ] } } }, "required": [ "key", "current", "versions" ] } } }, "required": [ "memories" ] }, { "type": "object", "properties": { "memories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "value": {}, "source": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "confidence": { "anyOf": [ { "type": "null" }, { "type": "number" } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "key", "value", "source", "confidence", "created_at", "updated_at" ] } } }, "required": [ "memories" ] } ] }, "example": { "memories": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/farmMemory.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" } }, "/v1/farm/{farm_id}/notifications": { "get": { "operationId": "get_v1_farm_farm_id_notifications", "tags": [ "notifications" ], "summary": "Get Notifications", "description": "Current notifications 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "skip", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "take", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "FAILED", "PENDING", "SENT" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "notifications": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "FAILED", "PENDING", "SENT" ] }, "type": { "type": "string", "enum": [ "EMAIL", "IN_APP", "SMS" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string" }, "farm_id": { "type": "string" }, "error_message": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "scheduled_event_id": { "type": "string" }, "sent_at": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] } }, "required": [ "status", "type", "id", "created_at", "updated_at", "user_id", "farm_id", "error_message", "scheduled_event_id", "sent_at" ] } }, "total": { "type": "number" } }, "required": [ "notifications", "total" ] }, "example": { "notifications": [], "total": 1 } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/notification.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" } }, "/v1/farm/{farm_id}/rations": { "get": { "operationId": "get_v1_farm_farm_id_rations", "tags": [ "rations" ], "summary": "Get Rations", "description": "Current rations 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "skip", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "take", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "include_inactive", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "number" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/RationWithRelations" } } }, "required": [ "total", "records" ] }, "example": { "records": [ { "id": "11111111-1111-4111-8111-111111111111", "farm_id": "11111111-1111-4111-8111-111111111111", "name": "Hay ration", "unit": "lb", "is_active": true, "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "ingredients": [ { "id": "11111111-1111-4111-8111-111111111111", "name": "Hay", "per_head_lbs": "5.25", "position": 0, "ration_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z" } ], "assignments": [ { "id": "11111111-1111-4111-8111-111111111111", "ration_id": "11111111-1111-4111-8111-111111111111", "group_id": "11111111-1111-4111-8111-111111111111", "feedings_per_day": 2, "label": null, "is_active": true, "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "group": { "id": "11111111-1111-4111-8111-111111111111", "name": "Ewes" } } ] } ], "total": 1 } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/ration.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" }, "post": { "operationId": "post_v1_farm_farm_id_rations", "tags": [ "rations" ], "summary": "Create Ration", "description": "Current rations 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RationWithRelations" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "farm_id": "11111111-1111-4111-8111-111111111111", "name": "Hay ration", "unit": "lb", "is_active": true, "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "ingredients": [ { "id": "11111111-1111-4111-8111-111111111111", "name": "Hay", "per_head_lbs": "5.25", "position": 0, "ration_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z" } ], "assignments": [ { "id": "11111111-1111-4111-8111-111111111111", "ration_id": "11111111-1111-4111-8111-111111111111", "group_id": "11111111-1111-4111-8111-111111111111", "feedings_per_day": 2, "label": null, "is_active": true, "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "group": { "id": "11111111-1111-4111-8111-111111111111", "name": "Ewes" } } ] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/ration.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "unit": { "type": "string", "minLength": 1 }, "ingredients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1 }, "per_head_lbs": { "type": "number", "minimum": 0 }, "position": { "type": "integer", "minimum": 0 } }, "required": [ "name", "per_head_lbs" ] }, "minItems": 1 }, "assignments": { "type": "array", "items": { "type": "object", "properties": { "group_id": { "type": "string", "format": "uuid" }, "feedings_per_day": { "type": "integer", "minimum": 1, "maximum": 12 }, "label": { "type": "string" }, "is_active": { "type": "boolean" } }, "required": [ "group_id" ] } } }, "required": [ "name", "ingredients" ] }, "example": { "name": "Example", "ingredients": [ { "name": "Example", "per_head_lbs": 1 } ] } } } }, "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/rations/{ration_id}": { "delete": { "operationId": "delete_v1_farm_farm_id_rations_ration_id", "tags": [ "rations" ], "summary": "Delete Ration", "description": "Current rations 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. Deletion behavior is described below; a successful status does not imply erasure from all retained history. Marks the stored entity inactive (soft deletion).", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "ration_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Completed; no response body." }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/ration.ts", "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" }, "get": { "operationId": "get_v1_farm_farm_id_rations_ration_id", "tags": [ "rations" ], "summary": "Get Ration", "description": "Current rations 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "ration_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RationWithRelations" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "farm_id": "11111111-1111-4111-8111-111111111111", "name": "Hay ration", "unit": "lb", "is_active": true, "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "ingredients": [ { "id": "11111111-1111-4111-8111-111111111111", "name": "Hay", "per_head_lbs": "5.25", "position": 0, "ration_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z" } ], "assignments": [ { "id": "11111111-1111-4111-8111-111111111111", "ration_id": "11111111-1111-4111-8111-111111111111", "group_id": "11111111-1111-4111-8111-111111111111", "feedings_per_day": 2, "label": null, "is_active": true, "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "group": { "id": "11111111-1111-4111-8111-111111111111", "name": "Ewes" } } ] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/ration.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" }, "put": { "operationId": "put_v1_farm_farm_id_rations_ration_id", "tags": [ "rations" ], "summary": "Update Ration", "description": "Current rations 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "ration_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RationWithRelations" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "farm_id": "11111111-1111-4111-8111-111111111111", "name": "Hay ration", "unit": "lb", "is_active": true, "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "ingredients": [ { "id": "11111111-1111-4111-8111-111111111111", "name": "Hay", "per_head_lbs": "5.25", "position": 0, "ration_id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z" } ], "assignments": [ { "id": "11111111-1111-4111-8111-111111111111", "ration_id": "11111111-1111-4111-8111-111111111111", "group_id": "11111111-1111-4111-8111-111111111111", "feedings_per_day": 2, "label": null, "is_active": true, "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "group": { "id": "11111111-1111-4111-8111-111111111111", "name": "Ewes" } } ] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/ration.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "unit": { "type": "string", "minLength": 1 }, "is_active": { "type": "boolean" }, "ingredients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1 }, "per_head_lbs": { "type": "number", "minimum": 0 }, "position": { "type": "integer", "minimum": 0 } }, "required": [ "name", "per_head_lbs" ] }, "minItems": 1 } } }, "example": {} } } }, "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/rations/{ration_id}/assignments": { "post": { "operationId": "post_v1_farm_farm_id_rations_ration_id_assignments", "tags": [ "rations" ], "summary": "Create Assignment", "description": "Current rations 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "ration_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "group_id": { "type": "string" }, "ration_id": { "type": "string" }, "feedings_per_day": { "type": "number" }, "label": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "id", "created_at", "updated_at", "is_active", "group_id", "ration_id", "feedings_per_day", "label" ] }, "example": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "is_active": true, "group_id": "11111111-1111-4111-8111-111111111111", "ration_id": "11111111-1111-4111-8111-111111111111", "feedings_per_day": 1, "label": null } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/ration.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group_id": { "type": "string", "format": "uuid" }, "feedings_per_day": { "type": "integer", "minimum": 1, "maximum": 12 }, "label": { "type": "string" }, "is_active": { "type": "boolean" } }, "required": [ "group_id" ] }, "example": { "group_id": "11111111-1111-4111-8111-111111111111" } } } }, "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/rations/{ration_id}/assignments/{assignment_id}": { "delete": { "operationId": "delete_v1_farm_farm_id_rations_ration_id_assignments_assignment_id", "tags": [ "rations" ], "summary": "Delete Assignment", "description": "Current rations 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. Deletion behavior is described below; a successful status does not imply erasure from all retained history. Marks the stored entity inactive (soft deletion).", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "ration_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "assignment_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Completed; no response body." }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/ration.ts", "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" }, "put": { "operationId": "put_v1_farm_farm_id_rations_ration_id_assignments_assignment_id", "tags": [ "rations" ], "summary": "Update Assignment", "description": "Current rations 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "ration_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "assignment_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "group_id": { "type": "string" }, "ration_id": { "type": "string" }, "feedings_per_day": { "type": "number" }, "label": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "id", "created_at", "updated_at", "is_active", "group_id", "ration_id", "feedings_per_day", "label" ] }, "example": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "is_active": true, "group_id": "11111111-1111-4111-8111-111111111111", "ration_id": "11111111-1111-4111-8111-111111111111", "feedings_per_day": 1, "label": null } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/ration.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "feedings_per_day": { "type": "integer", "minimum": 1, "maximum": 12 }, "label": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" } } }, "example": {} } } }, "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/records": { "get": { "operationId": "get_v1_farm_farm_id_records", "tags": [ "records" ], "summary": "Get Records", "description": "Current records 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "skip", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "take", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "number" }, "records": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "OTHER", "FEED", "GENETIC", "HEALTH", "MOVEMENT" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "applied_at": { "type": "string", "format": "date-time" }, "record_items": { "type": "array", "items": { "$ref": "#/components/schemas/RecordItem" } }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/File" } } }, "required": [ "type", "id", "created_at", "updated_at", "name", "is_active", "description", "applied_at", "record_items", "files" ] } } }, "required": [ "total", "records" ] }, "example": { "total": 0, "records": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/record.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" }, "post": { "operationId": "post_v1_farm_farm_id_records", "tags": [ "records" ], "summary": "Create Record", "description": "Current records 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. At least one animal_ids or group_ids entry is required. Associations must name active entities in this farm; the service filters out ids outside that set. Supply ids obtained from the same farm.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "OTHER", "FEED", "GENETIC", "HEALTH", "MOVEMENT" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "applied_at": { "type": "string", "format": "date-time" } }, "required": [ "type", "id", "created_at", "updated_at", "name", "is_active", "description", "applied_at" ] }, "example": { "type": "OTHER", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "description": null, "applied_at": "2026-09-01T12:00:00.000Z" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/record.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "animal_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [] }, "group_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [] }, "description": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "FEED", "GENETIC", "HEALTH", "MOVEMENT", "OTHER" ] }, "applied_at": { "type": "string", "format": "date-time" } }, "required": [ "name", "type", "applied_at" ], "anyOf": [ { "required": [ "animal_ids" ], "properties": { "animal_ids": { "minItems": 1 } } }, { "required": [ "group_ids" ], "properties": { "group_ids": { "minItems": 1 } } } ] }, "example": { "animal_ids": [ "11111111-1111-4111-8111-111111111111" ], "group_ids": [], "name": "Example observation", "type": "OTHER", "applied_at": "2026-09-01T12:00:00.000Z" } } } }, "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/records/{record_id}": { "delete": { "operationId": "delete_v1_farm_farm_id_records_record_id", "tags": [ "records" ], "summary": "Delete Record", "description": "Current records HTTP operation. External credential scopes: write:records. Minimum farm role: OWNER. 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. Marks the stored entity inactive (soft deletion).", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "record_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Completed; no response body." }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/record.ts", "x-required-scopes": [ "write:records" ], "x-minimum-role": "OWNER" }, "get": { "operationId": "get_v1_farm_farm_id_records_record_id", "tags": [ "records" ], "summary": "Get Record", "description": "Current records 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "record_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "OTHER", "FEED", "GENETIC", "HEALTH", "MOVEMENT" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "applied_at": { "type": "string", "format": "date-time" }, "record_items": { "type": "array", "items": { "$ref": "#/components/schemas/RecordItem" } }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/File" } } }, "required": [ "type", "id", "created_at", "updated_at", "name", "is_active", "description", "applied_at", "record_items", "files" ] }, "example": { "type": "OTHER", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "description": null, "applied_at": "2026-09-01T12:00:00.000Z", "record_items": [], "files": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/record.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" }, "put": { "operationId": "put_v1_farm_farm_id_records_record_id", "tags": [ "records" ], "summary": "Update Record", "description": "Current records 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. Provided association ids are connected to the record; they do not replace the entire association set.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "record_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "OTHER", "FEED", "GENETIC", "HEALTH", "MOVEMENT" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "applied_at": { "type": "string", "format": "date-time" } }, "required": [ "type", "id", "created_at", "updated_at", "name", "is_active", "description", "applied_at" ] }, "example": { "type": "OTHER", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "description": null, "applied_at": "2026-09-01T12:00:00.000Z" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/record.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "animal_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [] }, "group_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "default": [] }, "description": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "FEED", "GENETIC", "HEALTH", "MOVEMENT", "OTHER" ] }, "applied_at": { "type": "string", "format": "date-time" } } }, "example": {} } } }, "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/records/{record_id}/items": { "get": { "operationId": "get_v1_farm_farm_id_records_record_id_items", "tags": [ "record-items" ], "summary": "Get Record Items", "description": "Current record items 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "record_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "skip", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "take", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "number" }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "metadata": {}, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "id", "created_at", "updated_at", "name", "is_active", "metadata", "description" ] } } }, "required": [ "total", "records" ] }, "example": { "total": 0, "records": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/recordItem.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" }, "post": { "operationId": "post_v1_farm_farm_id_records_record_id_items", "tags": [ "record-items" ], "summary": "Create Record Item", "description": "Current record items 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "record_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "metadata": {}, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "id", "created_at", "updated_at", "name", "is_active", "metadata", "description" ] }, "example": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "metadata": null, "description": null } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/recordItem.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "metadata": {} }, "required": [ "name" ] }, "example": { "name": "Example" } } } }, "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/records/{record_id}/items/{record_item_id}": { "delete": { "operationId": "delete_v1_farm_farm_id_records_record_id_items_record_item_id", "tags": [ "record-items" ], "summary": "Delete Record Item", "description": "Current record items HTTP operation. External credential scopes: write:records. Minimum farm role: OWNER. 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. Marks the stored entity inactive (soft deletion).", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "record_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "record_item_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Completed; no response body." }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/recordItem.ts", "x-required-scopes": [ "write:records" ], "x-minimum-role": "OWNER" }, "get": { "operationId": "get_v1_farm_farm_id_records_record_id_items_record_item_id", "tags": [ "record-items" ], "summary": "Get Record Item", "description": "Current record items 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "record_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "record_item_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "metadata": {}, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "id", "created_at", "updated_at", "name", "is_active", "metadata", "description" ] }, "example": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "metadata": null, "description": null } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/recordItem.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" }, "put": { "operationId": "put_v1_farm_farm_id_records_record_id_items_record_item_id", "tags": [ "record-items" ], "summary": "Update Record Item", "description": "Current record items 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "record_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "record_item_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "metadata": {}, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "id", "created_at", "updated_at", "name", "is_active", "metadata", "description" ] }, "example": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "metadata": null, "description": null } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/recordItem.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "metadata": {} } }, "example": {} } } }, "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/recurring-events": { "get": { "operationId": "get_v1_farm_farm_id_recurring_events", "tags": [ "recurring-events" ], "summary": "Get Recurring Events", "description": "Current recurring events 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "OTHER", "FEED", "GENETIC", "HEALTH", "MOVEMENT" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "animal_ids": {}, "group_ids": {}, "end_date": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "recurrence_type": { "type": "string", "enum": [ "DAILY", "MONTHLY", "WEEKLY" ] }, "start_date": { "type": "string", "format": "date-time" } }, "required": [ "type", "id", "created_at", "updated_at", "name", "is_active", "farm_id", "description", "animal_ids", "group_ids", "end_date", "recurrence_type", "start_date" ] } }, "example": [] } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/recurringEvent.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" }, "post": { "operationId": "post_v1_farm_farm_id_recurring_events", "tags": [ "recurring-events" ], "summary": "Create Recurring Event", "description": "Current recurring events 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "OTHER", "FEED", "GENETIC", "HEALTH", "MOVEMENT" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "animal_ids": {}, "group_ids": {}, "end_date": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "recurrence_type": { "type": "string", "enum": [ "DAILY", "MONTHLY", "WEEKLY" ] }, "start_date": { "type": "string", "format": "date-time" } }, "required": [ "type", "id", "created_at", "updated_at", "name", "is_active", "farm_id", "description", "animal_ids", "group_ids", "end_date", "recurrence_type", "start_date" ] }, "example": { "type": "OTHER", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "description": null, "animal_ids": null, "group_ids": null, "end_date": null, "recurrence_type": "DAILY", "start_date": "2026-09-01T12:00:00.000Z" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/recurringEvent.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "animal_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "description": { "type": "string" }, "end_date": { "type": "string", "format": "date-time" }, "group_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "name": { "type": "string" }, "recurrence_type": { "type": "string", "enum": [ "DAILY", "MONTHLY", "WEEKLY" ] }, "start_date": { "type": "string", "format": "date-time" }, "type": { "type": "string", "enum": [ "FEED", "GENETIC", "HEALTH", "MOVEMENT", "OTHER" ] } }, "required": [ "animal_ids", "group_ids", "name", "recurrence_type", "start_date", "type" ] }, "example": { "animal_ids": [], "group_ids": [], "name": "Example", "recurrence_type": "DAILY", "start_date": "2026-09-01T12:00:00.000Z", "type": "FEED" } } } }, "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/recurring-events/{recurring_event_id}": { "delete": { "operationId": "delete_v1_farm_farm_id_recurring_events_recurring_event_id", "tags": [ "recurring-events" ], "summary": "Delete Recurring Event", "description": "Current recurring events 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. Deletion behavior is described below; a successful status does not imply erasure from all retained history. Marks the stored entity inactive (soft deletion).", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "recurring_event_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Completed; no response body." }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/recurringEvent.ts", "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" }, "get": { "operationId": "get_v1_farm_farm_id_recurring_events_recurring_event_id", "tags": [ "recurring-events" ], "summary": "Get Recurring Event", "description": "Current recurring events 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "recurring_event_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "OTHER", "FEED", "GENETIC", "HEALTH", "MOVEMENT" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "animal_ids": {}, "group_ids": {}, "end_date": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "recurrence_type": { "type": "string", "enum": [ "DAILY", "MONTHLY", "WEEKLY" ] }, "start_date": { "type": "string", "format": "date-time" } }, "required": [ "type", "id", "created_at", "updated_at", "name", "is_active", "farm_id", "description", "animal_ids", "group_ids", "end_date", "recurrence_type", "start_date" ] }, "example": { "type": "OTHER", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "description": null, "animal_ids": null, "group_ids": null, "end_date": null, "recurrence_type": "DAILY", "start_date": "2026-09-01T12:00:00.000Z" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/recurringEvent.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" }, "put": { "operationId": "put_v1_farm_farm_id_recurring_events_recurring_event_id", "tags": [ "recurring-events" ], "summary": "Update Recurring Event", "description": "Current recurring events 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "recurring_event_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "recurringEvent": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "OTHER", "FEED", "GENETIC", "HEALTH", "MOVEMENT" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "animal_ids": {}, "group_ids": {}, "end_date": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "recurrence_type": { "type": "string", "enum": [ "DAILY", "MONTHLY", "WEEKLY" ] }, "start_date": { "type": "string", "format": "date-time" } }, "required": [ "type", "id", "created_at", "updated_at", "name", "is_active", "farm_id", "description", "animal_ids", "group_ids", "end_date", "recurrence_type", "start_date" ] } }, "required": [ "recurringEvent" ] }, "example": { "recurringEvent": { "type": "OTHER", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "description": null, "animal_ids": null, "group_ids": null, "end_date": null, "recurrence_type": "DAILY", "start_date": "2026-09-01T12:00:00.000Z" } } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/recurringEvent.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "animal_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "description": { "type": "string" }, "end_date": { "type": "string", "format": "date-time" }, "group_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "name": { "type": "string" }, "recurrence_type": { "type": "string", "enum": [ "DAILY", "MONTHLY", "WEEKLY" ] }, "start_date": { "type": "string", "format": "date-time" }, "type": { "type": "string", "enum": [ "FEED", "GENETIC", "HEALTH", "MOVEMENT", "OTHER" ] } } }, "example": {} } } }, "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/reports/agristability": { "get": { "operationId": "get_v1_farm_farm_id_reports_agristability", "tags": [ "reports" ], "summary": "Get Agri Stability Schedule", "description": "Current farm reports 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "year", "required": false, "schema": { "type": "integer", "minimum": 1900, "maximum": 9999 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "farm": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "species": { "type": "string" } }, "required": [ "id", "name", "species" ] }, "year": { "type": "number" }, "generatedAt": { "type": "string" }, "schedule": { "type": "object", "properties": { "year": { "type": "number" }, "period": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ] }, "opening": { "type": "number" }, "births": { "type": "number" }, "purchases": { "type": "number" }, "deaths": { "type": "number" }, "sales": { "type": "number" }, "closing": { "type": "number" }, "headDays": { "type": "number" }, "averageHead": { "type": "number" }, "birthEvents": { "type": "number" }, "saleEvents": { "type": "number" } }, "required": [ "year", "period", "opening", "births", "purchases", "deaths", "sales", "closing", "headDays", "averageHead", "birthEvents", "saleEvents" ] }, "priorYearClosing": { "type": "number" }, "continuity": { "type": "object", "properties": { "openingMatchesPriorClosing": { "type": "boolean" }, "breakHead": { "type": "number" }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "openingMatchesPriorClosing", "breakHead", "notes" ] }, "gaps": { "type": "array", "items": { "type": "string" } }, "byGroup": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "closing": { "type": "number" } }, "required": [ "group", "closing" ] } } }, "required": [ "farm", "year", "generatedAt", "schedule", "priorYearClosing", "continuity", "gaps", "byGroup" ] }, "example": { "farm": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example", "species": "example" }, "year": 1, "generatedAt": "example", "schedule": { "year": 1, "period": { "start": "example", "end": "example" }, "opening": 1, "births": 1, "purchases": 1, "deaths": 1, "sales": 1, "closing": 1, "headDays": 1, "averageHead": 1, "birthEvents": 1, "saleEvents": 1 }, "priorYearClosing": 1, "continuity": { "openingMatchesPriorClosing": true, "breakHead": 1, "notes": [] }, "gaps": [], "byGroup": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/reports.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" } }, "/v1/farm/{farm_id}/reports/inventory": { "get": { "operationId": "get_v1_farm_farm_id_reports_inventory", "tags": [ "reports" ], "summary": "Get Inventory Report", "description": "Current farm reports 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "preset", "required": false, "schema": { "type": "string", "enum": [ "month", "quarter", "year", "custom" ], "default": "month" } }, { "in": "query", "name": "from", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "to", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "farm": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "species": { "type": "string" } }, "required": [ "id", "name", "species" ] }, "period": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ] }, "generatedAt": { "type": "string" }, "totals": { "type": "object", "properties": { "opening": { "type": "number" }, "births": { "type": "number" }, "purchases": { "type": "number" }, "deaths": { "type": "number" }, "sales": { "type": "number" }, "transfers": { "type": "number" }, "closing": { "type": "number" } }, "required": [ "opening", "births", "purchases", "deaths", "sales", "transfers", "closing" ] }, "byGroup": { "type": "array", "items": { "type": "object", "properties": { "group": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "opening": { "type": "number" }, "births": { "type": "number" }, "purchases": { "type": "number" }, "deaths": { "type": "number" }, "sales": { "type": "number" }, "transfers": { "type": "number" }, "closing": { "type": "number" } }, "required": [ "group", "opening", "births", "purchases", "deaths", "sales", "transfers", "closing" ] } }, "byCategory": { "type": "object", "properties": {} }, "reconciliation": { "type": "object", "properties": { "closingCount": { "type": "number" }, "ledgerAdditions": { "type": "number" }, "ledgerRemovals": { "type": "number" }, "animalAdditions": { "type": "number" }, "additionsDrift": { "type": "number" }, "drift": { "type": "boolean" }, "notes": { "type": "array", "items": { "type": "string" } } }, "required": [ "closingCount", "ledgerAdditions", "ledgerRemovals", "animalAdditions", "additionsDrift", "drift", "notes" ] }, "unclassifiedRecords": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "applied_at": { "type": "string" }, "headCount": { "type": "number" } }, "required": [ "id", "name", "type", "applied_at", "headCount" ] } }, "records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "type": { "type": "string" }, "applied_at": { "type": "string" }, "category": { "type": "string", "enum": [ "BIRTH", "PURCHASE", "DEATH", "SALE", "TRANSFER", "OTHER" ] }, "groupIds": { "type": "array", "items": { "type": "string" } }, "headCount": { "type": "number" }, "headCountKnown": { "type": "boolean" } }, "required": [ "id", "name", "description", "type", "applied_at", "category", "groupIds", "headCount", "headCountKnown" ] } }, "preset": { "type": "string", "enum": [ "custom", "month", "quarter", "year" ] } }, "required": [ "farm", "period", "generatedAt", "totals", "byGroup", "byCategory", "reconciliation", "unclassifiedRecords", "records", "preset" ] }, "example": { "farm": { "id": "11111111-1111-4111-8111-111111111111", "name": "Example", "species": "example" }, "period": { "start": "example", "end": "example" }, "generatedAt": "example", "totals": { "opening": 1, "births": 1, "purchases": 1, "deaths": 1, "sales": 1, "transfers": 1, "closing": 1 }, "byGroup": [], "byCategory": {}, "reconciliation": { "closingCount": 1, "ledgerAdditions": 1, "ledgerRemovals": 1, "animalAdditions": 1, "additionsDrift": 1, "drift": true, "notes": [] }, "unclassifiedRecords": [], "records": [], "preset": "custom" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/reports.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" } }, "/v1/farm/{farm_id}/scheduled-events": { "get": { "operationId": "get_v1_farm_farm_id_scheduled_events", "tags": [ "scheduled-events" ], "summary": "Get Scheduled Events", "description": "Current scheduled events 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "skip", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "take", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string", "enum": [ "APPROVED", "COMPLETED", "PENDING", "REJECTED" ] } }, { "in": "query", "name": "start_date", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "end_date", "required": false, "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduledEvents": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "COMPLETED", "PENDING", "APPROVED", "REJECTED" ] }, "type": { "type": "string", "enum": [ "OTHER", "FEED", "GENETIC", "HEALTH", "MOVEMENT" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "record_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "approved_by_user_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "recurring_event_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "animal_ids": {}, "approved_at": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "group_ids": {}, "scheduled_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "type", "id", "created_at", "updated_at", "name", "is_active", "farm_id", "description", "record_id", "approved_by_user_id", "recurring_event_id", "animal_ids", "approved_at", "group_ids", "scheduled_at" ] } }, "total": { "type": "number" } }, "required": [ "scheduledEvents", "total" ] }, "example": { "scheduledEvents": [], "total": 1 } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/scheduledEvent.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" }, "post": { "operationId": "post_v1_farm_farm_id_scheduled_events", "tags": [ "scheduled-events" ], "summary": "Create Scheduled Event", "description": "Current scheduled events 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "COMPLETED", "PENDING", "APPROVED", "REJECTED" ] }, "type": { "type": "string", "enum": [ "OTHER", "FEED", "GENETIC", "HEALTH", "MOVEMENT" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "record_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "approved_by_user_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "recurring_event_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "animal_ids": {}, "approved_at": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "group_ids": {}, "scheduled_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "type", "id", "created_at", "updated_at", "name", "is_active", "farm_id", "description", "record_id", "approved_by_user_id", "recurring_event_id", "animal_ids", "approved_at", "group_ids", "scheduled_at" ] }, "example": { "status": "COMPLETED", "type": "OTHER", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "description": null, "record_id": null, "approved_by_user_id": null, "recurring_event_id": null, "animal_ids": null, "approved_at": null, "group_ids": null, "scheduled_at": "2026-09-01T12:00:00.000Z" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/scheduledEvent.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "animal_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "description": { "type": "string" }, "group_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "name": { "type": "string" }, "scheduled_at": { "type": "string", "format": "date-time" }, "type": { "type": "string", "enum": [ "FEED", "GENETIC", "HEALTH", "MOVEMENT", "OTHER" ] } }, "required": [ "animal_ids", "group_ids", "name", "scheduled_at", "type" ] }, "example": { "animal_ids": [], "group_ids": [], "name": "Example", "scheduled_at": "2026-09-01T12:00:00.000Z", "type": "FEED" } } } }, "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/scheduled-events/{scheduled_event_id}": { "get": { "operationId": "get_v1_farm_farm_id_scheduled_events_scheduled_event_id", "tags": [ "scheduled-events" ], "summary": "Get Scheduled Event", "description": "Current scheduled events 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "scheduled_event_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "COMPLETED", "PENDING", "APPROVED", "REJECTED" ] }, "type": { "type": "string", "enum": [ "OTHER", "FEED", "GENETIC", "HEALTH", "MOVEMENT" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "record_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "approved_by_user_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "recurring_event_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "animal_ids": {}, "approved_at": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "group_ids": {}, "scheduled_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "type", "id", "created_at", "updated_at", "name", "is_active", "farm_id", "description", "record_id", "approved_by_user_id", "recurring_event_id", "animal_ids", "approved_at", "group_ids", "scheduled_at" ] }, "example": { "status": "COMPLETED", "type": "OTHER", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "description": null, "record_id": null, "approved_by_user_id": null, "recurring_event_id": null, "animal_ids": null, "approved_at": null, "group_ids": null, "scheduled_at": "2026-09-01T12:00:00.000Z" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/scheduledEvent.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" } }, "/v1/farm/{farm_id}/scheduled-events/{scheduled_event_id}/approve": { "post": { "operationId": "post_v1_farm_farm_id_scheduled_events_scheduled_event_id_approve", "tags": [ "scheduled-events" ], "summary": "Approve Scheduled Event", "description": "Current scheduled events 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "scheduled_event_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "record": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "OTHER", "FEED", "GENETIC", "HEALTH", "MOVEMENT" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "applied_at": { "type": "string", "format": "date-time" } }, "required": [ "type", "id", "created_at", "updated_at", "name", "is_active", "description", "applied_at" ] }, "scheduledEvent": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "COMPLETED", "PENDING", "APPROVED", "REJECTED" ] }, "type": { "type": "string", "enum": [ "OTHER", "FEED", "GENETIC", "HEALTH", "MOVEMENT" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "record_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "approved_by_user_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "recurring_event_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "animal_ids": {}, "approved_at": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "group_ids": {}, "scheduled_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "type", "id", "created_at", "updated_at", "name", "is_active", "farm_id", "description", "record_id", "approved_by_user_id", "recurring_event_id", "animal_ids", "approved_at", "group_ids", "scheduled_at" ] } }, "required": [ "record", "scheduledEvent" ] }, "example": { "record": { "type": "OTHER", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "description": null, "applied_at": "2026-09-01T12:00:00.000Z" }, "scheduledEvent": { "status": "COMPLETED", "type": "OTHER", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "description": null, "record_id": null, "approved_by_user_id": null, "recurring_event_id": null, "animal_ids": null, "approved_at": null, "group_ids": null, "scheduled_at": "2026-09-01T12:00:00.000Z" } } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/scheduledEvent.ts", "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/scheduled-events/{scheduled_event_id}/reject": { "post": { "operationId": "post_v1_farm_farm_id_scheduled_events_scheduled_event_id_reject", "tags": [ "scheduled-events" ], "summary": "Reject Scheduled Event", "description": "Current scheduled events 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "scheduled_event_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduledEvent": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "COMPLETED", "PENDING", "APPROVED", "REJECTED" ] }, "type": { "type": "string", "enum": [ "OTHER", "FEED", "GENETIC", "HEALTH", "MOVEMENT" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "record_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "approved_by_user_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "recurring_event_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "animal_ids": {}, "approved_at": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "group_ids": {}, "scheduled_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "type", "id", "created_at", "updated_at", "name", "is_active", "farm_id", "description", "record_id", "approved_by_user_id", "recurring_event_id", "animal_ids", "approved_at", "group_ids", "scheduled_at" ] } }, "required": [ "scheduledEvent" ] }, "example": { "scheduledEvent": { "status": "COMPLETED", "type": "OTHER", "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "farm_id": "11111111-1111-4111-8111-111111111111", "description": null, "record_id": null, "approved_by_user_id": null, "recurring_event_id": null, "animal_ids": null, "approved_at": null, "group_ids": null, "scheduled_at": "2026-09-01T12:00:00.000Z" } } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/scheduledEvent.ts", "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/scheduled-events/pending/approval": { "get": { "operationId": "get_v1_farm_farm_id_scheduled_events_pending_approval", "tags": [ "scheduled-events" ], "summary": "Get Pending Events For Approval", "description": "Current scheduled events 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.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "COMPLETED", "PENDING", "APPROVED", "REJECTED" ] }, "type": { "type": "string", "enum": [ "OTHER", "FEED", "GENETIC", "HEALTH", "MOVEMENT" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "description": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "record_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "approved_by_user_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "recurring_event_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "animal_ids": {}, "approved_at": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "group_ids": {}, "scheduled_at": { "type": "string", "format": "date-time" } }, "required": [ "status", "type", "id", "created_at", "updated_at", "name", "is_active", "farm_id", "description", "record_id", "approved_by_user_id", "recurring_event_id", "animal_ids", "approved_at", "group_ids", "scheduled_at" ] } }, "example": [] } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/scheduledEvent.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" } }, "/v1/file": { "get": { "operationId": "get_v1_file", "tags": [ "files" ], "summary": "Get Files", "description": "Current files HTTP operation. External credential scopes: read:records. Access is resolved for the authenticated user or by the endpoint-specific OAuth checks. 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.", "parameters": [ { "in": "query", "name": "skip", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "take", "required": false, "schema": { "type": "integer" } }, { "in": "query", "name": "animal_id", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "group_id", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "record_id", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "record_item_id", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "user_id", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "number" }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "mime_type": { "type": "string" }, "size": { "type": "number" }, "url": { "type": "string" } }, "required": [ "id", "created_at", "updated_at", "name", "is_active", "mime_type", "size", "url" ] } } }, "required": [ "total", "files" ] }, "example": { "total": 1, "files": [] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/file.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "None at route middleware" } }, "/v1/file/{file_id}": { "delete": { "operationId": "delete_v1_file_file_id", "tags": [ "files" ], "summary": "Delete File", "description": "Current files HTTP operation. External credential scopes: write:records. 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. Deletion behavior is described below; a successful status does not imply erasure from all retained history. Deletes the accessible file through the file service. Marks the file inactive; do not interpret this as immediate storage erasure.", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Completed; no response body." }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/file.ts", "x-required-scopes": [ "write:records" ], "x-minimum-role": "None at route middleware" }, "get": { "operationId": "get_v1_file_file_id", "tags": [ "files" ], "summary": "Get File", "description": "Current files HTTP operation. External credential scopes: read:records. 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.", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "mime_type": { "type": "string" }, "size": { "type": "number" }, "url": { "type": "string" } }, "required": [ "id", "created_at", "updated_at", "name", "is_active", "mime_type", "size", "url" ] }, "signedUrl": { "type": "string" } }, "required": [ "file", "signedUrl" ] }, "example": { "file": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "mime_type": "example", "size": 1, "url": "example" }, "signedUrl": "example" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/file.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "None at route middleware" } }, "/v1/file/{file_id}/link": { "delete": { "operationId": "delete_v1_file_file_id_link", "tags": [ "files" ], "summary": "Unlink File", "description": "Current files HTTP operation. External credential scopes: write:records. 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. Deletion behavior is described below; a successful status does not imply erasure from all retained history. Removes the supplied associations; this is not file deletion.", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "mime_type": { "type": "string" }, "size": { "type": "number" }, "url": { "type": "string" } }, "required": [ "id", "created_at", "updated_at", "name", "is_active", "mime_type", "size", "url" ] } }, "required": [ "file" ] }, "example": { "file": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "mime_type": "example", "size": 1, "url": "example" } } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/file.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "animal_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "group_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "record_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "record_item_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "user_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "example": {} } } }, "x-required-scopes": [ "write:records" ], "x-minimum-role": "None at route middleware" }, "post": { "operationId": "post_v1_file_file_id_link", "tags": [ "files" ], "summary": "Link File", "description": "Current files HTTP operation. External credential scopes: write:records. 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.", "parameters": [ { "in": "path", "name": "file_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "mime_type": { "type": "string" }, "size": { "type": "number" }, "url": { "type": "string" } }, "required": [ "id", "created_at", "updated_at", "name", "is_active", "mime_type", "size", "url" ] } }, "required": [ "file" ] }, "example": { "file": { "id": "11111111-1111-4111-8111-111111111111", "created_at": "2026-09-01T12:00:00.000Z", "updated_at": "2026-09-01T12:00:00.000Z", "name": "Example", "is_active": true, "mime_type": "example", "size": 1, "url": "example" } } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/file.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "animal_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "group_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "record_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "record_item_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "user_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "example": {} } } }, "x-required-scopes": [ "write:records" ], "x-minimum-role": "None at route middleware" } }, "/v1/file/upload": { "post": { "operationId": "post_v1_file_upload", "tags": [ "files" ], "summary": "Upload File", "description": "Current files HTTP operation. External credential scopes: write:records. 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. Accepted types: JPEG, PNG, GIF, WebP images (10 MB each); MP4, QuickTime and AVI video (100 MB each); JSON, PDF and CSV documents (5 MB each). Maximum 10 files per request.", "parameters": [ { "in": "query", "name": "entity_type", "required": false, "schema": { "type": "string", "enum": [ "animal", "group", "record", "user" ] } }, { "in": "query", "name": "entity_id", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object" } }, "data": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "mime_type": { "type": "string" }, "size": { "type": "number" }, "url": { "type": "string" } }, "required": [ "id", "created_at", "updated_at", "name", "is_active", "mime_type", "size", "url" ] } } }, "required": [ "files" ] } }, "required": [ "success", "errors", "data" ] }, "example": { "success": true, "errors": [], "data": { "files": [] } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "success": { "type": "boolean" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } }, "data": { "type": "null" } }, "required": [ "success", "errors", "data" ] }, { "$ref": "#/components/schemas/Error" } ] }, "example": { "success": false, "errors": [ { "message": "No files provided" } ], "data": null } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/file.ts", "x-required-scopes": [ "write:records" ], "x-minimum-role": "None at route middleware", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "files" ], "properties": { "files": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "format": "binary" } } } } } } } } }, "/v1/user/default-farm": { "get": { "operationId": "get_v1_user_default_farm", "tags": [ "default-farm" ], "summary": "Get Default Farm", "description": "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.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "default_farm_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "default_farm_id" ] }, "example": { "default_farm_id": null } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/user.ts", "x-required-scopes": [], "x-minimum-role": "None at route middleware" }, "put": { "operationId": "put_v1_user_default_farm", "tags": [ "default-farm" ], "summary": "Set Default Farm", "description": "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.", "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "default_farm_id": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "default_farm_id" ] }, "example": { "default_farm_id": null } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/user.ts", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "farm_id": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "farm_id" ] }, "example": { "farm_id": "11111111-1111-4111-8111-111111111111" } } } }, "x-required-scopes": [], "x-minimum-role": "None at route middleware", "security": [ { "LegacyKey": [] } ] } }, "/v1/farm/{farm_id}/birth-events/preview": { "post": { "operationId": "post_v1_farm__farm_id__birth_events_preview", "tags": [ "birth-events" ], "summary": "Preview a birth event", "description": "Validate without saving farm data. Display the entire returned bundle and resolved review. Obtain explicit producer approval of this exact preview before confirmation. A read-only device session cannot call POST; an EDITOR device session needs read:records and a write scope. External credential scopes: read:records. Minimum farm role: EDITOR.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BirthPreview" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "409": { "description": "The approved preview is stale, the request ID is already used, or the protocol version has different steps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BirthRequest" } } } }, "x-source": "api/src/lib/controllers/birthEvent.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/birth-events": { "post": { "operationId": "post_v1_farm__farm_id__birth_events", "tags": [ "birth-events" ], "summary": "Confirm a reviewed birth event", "description": "Save all reviewed animals, observations, relationships, care records, tasks and evidence in one transaction. Submit only request_id, bundle and confirmation_hash from the approved preview. Reusing the exact request is idempotent. A changed hash or reused request ID with different data returns 409; obtain approval of a fresh preview after corrections or changed farm evidence. External credential scopes: write:records, write:animals, write:groups. Minimum farm role: EDITOR.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BirthEvent" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "409": { "description": "The approved preview is stale, the request ID is already used, or the protocol version has different steps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BirthConfirmation" } } } }, "x-source": "api/src/lib/controllers/birthEvent.ts", "x-required-scopes": [ "write:records", "write:animals", "write:groups" ], "x-minimum-role": "EDITOR" }, "get": { "operationId": "get_v1_farm__farm_id__birth_events", "tags": [ "birth-events" ], "summary": "List birth events", "description": "List saved births with pagination, optionally filtered by dam or offspring animal_id. External credential scopes: read:records. Minimum farm role: READER.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "skip", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "in": "query", "name": "take", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "in": "query", "name": "animal_id", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/BirthEvent" } } }, "required": [ "total", "records" ] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/birthEvent.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" } }, "/v1/farm/{farm_id}/birth-events/{event_id}": { "get": { "operationId": "get_v1_farm__farm_id__birth_events__event_id_", "tags": [ "birth-events" ], "summary": "Get a birth event", "description": "Retrieve a saved birth and its accessible evidence from the current farm. External credential scopes: read:records. Minimum farm role: READER.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "event_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BirthEvent" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/birthEvent.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" } }, "/v1/farm/{farm_id}/farm-tasks": { "get": { "operationId": "get_v1_farm__farm_id__farm_tasks", "tags": [ "farm-tasks" ], "summary": "List farm follow-up tasks", "description": "List linked birth tasks. Undated TODO tasks remain visible and sort before dated tasks. External credential scopes: read:records. Minimum farm role: READER.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "skip", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "in": "query", "name": "take", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "in": "query", "name": "status", "schema": { "type": "string", "enum": [ "TODO", "DONE", "CANCELLED" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/FarmTask" } } }, "required": [ "total", "records" ] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/birthEvent.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" } }, "/v1/farm/{farm_id}/farm-tasks/{task_id}": { "put": { "operationId": "put_v1_farm__farm_id__farm_tasks__task_id_", "tags": [ "farm-tasks" ], "summary": "Update a farm follow-up task", "description": "Set status and optionally the due date. Omitting due_date preserves it; null clears it. A provided date must be a real calendar date. External credential scopes: write:records. Minimum farm role: EDITOR.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "path", "name": "task_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FarmTask" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "409": { "description": "The approved preview is stale, the request ID is already used, or the protocol version has different steps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "TODO", "DONE", "CANCELLED" ] }, "due_date": { "type": [ "string", "null" ], "format": "date" } }, "required": [ "status" ], "additionalProperties": false } } } }, "x-source": "api/src/lib/controllers/birthEvent.ts", "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/protocol-versions": { "get": { "operationId": "get_v1_farm__farm_id__protocol_versions", "tags": [ "protocol-versions" ], "summary": "List farm protocol versions", "description": "List immutable protocol definitions without inventing missing care steps. External credential scopes: read:records. Minimum farm role: READER.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "skip", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "in": "query", "name": "take", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0 }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/FarmProtocolVersion" } } }, "required": [ "total", "records" ] } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "x-source": "api/src/lib/controllers/birthEvent.ts", "x-required-scopes": [ "read:records" ], "x-minimum-role": "READER" }, "post": { "operationId": "post_v1_farm__farm_id__protocol_versions", "tags": [ "protocol-versions" ], "summary": "Create a farm protocol version", "description": "Save the exact producer-approved protocol name, version and steps. The same version and steps are idempotent; different steps for an existing version return 409. External credential scopes: write:records. Minimum farm role: EDITOR.", "parameters": [ { "in": "path", "name": "farm_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FarmProtocolVersion" } } } }, "400": { "description": "Request validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 400, "name": "ValidationError", "message": "Request validation failed." } ] } } } }, "401": { "description": "Missing/invalid authentication or insufficient farm role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 401, "name": "Unauthorized", "message": "Missing/invalid authentication or insufficient farm role." } ] } } } }, "403": { "description": "Missing required scope or credential type is disallowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 403, "name": "ForbiddenError", "message": "Missing required scope or credential type is disallowed." } ] } } } }, "404": { "description": "Resource or active farm membership not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 404, "name": "RanchBotError", "message": "Resource or active farm membership not found." } ] } } } }, "409": { "description": "The approved preview is stale, the request ID is already used, or the protocol version has different steps.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded. Retry after the indicated delay.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 429, "name": "RanchBotError", "message": "Rate limit exceeded. Retry after the indicated delay." } ] } } } }, "500": { "description": "Unexpected server failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "errors": [ { "code": 500, "name": "RanchBotError", "message": "Unexpected server failure." } ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FarmProtocolVersionInput" } } } }, "x-source": "api/src/lib/controllers/birthEvent.ts", "x-required-scopes": [ "write:records" ], "x-minimum-role": "EDITOR" } }, "/v1/farm/{farm_id}/birth-sources/{source_sms_id}": { "get": { "operationId": "getBirthSourceEvidence", "tags": [ "birth-sources" ], "summary": "Read retained birth-source evidence", "description": "Returns ordered attachment processing status and current farm-matched numeric tag candidates for the original source author with current farm membership. Requires read:records and read:animals for external credentials. No source URLs, signed URLs, raw OCR text, or image bytes are returned. Partial or uncertain candidates require producer selection; this operation writes no farm records.", "parameters": [ { "name": "farm_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "source_sms_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Private source evidence", "content": { "application/json": { "schema": { "type": "object", "properties": { "source_sms_id": { "type": "string", "format": "uuid" }, "source_message_id": { "type": [ "string", "null" ] }, "stage": { "type": "string", "enum": [ "LEGACY", "CONTROL", "PENDING", "PROCESSING", "BLOCKED", "FAILED", "COMPLETE" ] }, "failure_code": { "type": [ "string", "null" ] }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "ordinal": { "type": "integer", "minimum": 0 }, "file_id": { "type": [ "string", "null" ] }, "content_type": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "PENDING", "RETAINED", "FAILED" ] }, "ocr_state": { "type": "string", "enum": [ "PENDING", "COMPLETE", "FAILED", "UNSUPPORTED" ] }, "ocr_version": { "type": [ "string", "null" ] }, "ocr_attempts": { "type": "integer", "minimum": 0 }, "ocr_failure_code": { "type": [ "string", "null" ], "enum": [ "UNSUPPORTED_IMAGE", "IMAGE_LIMIT", "OCR_UNAVAILABLE", "OCR_TIMEOUT", "OCR_OUTPUT_LIMIT", "OCR_FAILED", null ] }, "ocr_completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "animal_id": { "type": "string", "format": "uuid" }, "identifier_id": { "type": "string", "format": "uuid" }, "identifier_value": { "type": "string", "maxLength": 100 }, "normalized_identifier": { "type": "string", "pattern": "^[0-9]{1,15}$" }, "is_iso_eid": { "type": "boolean" }, "match_kind": { "type": "string", "enum": [ "exact", "suffix", "partial" ] }, "confidence": { "type": "string", "enum": [ "high", "low" ] }, "requires_selection": { "type": "boolean" }, "supporting_observations": { "type": "array", "items": { "type": "object", "properties": { "media_id": { "type": "string", "format": "uuid" }, "digits": { "type": "string", "pattern": "^[0-9]{1,15}$" }, "ocr_confidence": { "type": "number", "minimum": 0, "maximum": 100 }, "box": { "type": "object", "properties": { "left": { "type": "number", "minimum": 0 }, "top": { "type": "number", "minimum": 0 }, "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "left", "top", "width", "height" ], "additionalProperties": false }, "match_kind": { "type": "string", "enum": [ "exact", "suffix", "partial" ] } }, "required": [ "media_id", "digits", "ocr_confidence", "box", "match_kind" ], "additionalProperties": false }, "maxItems": 128 } }, "required": [ "animal_id", "identifier_id", "identifier_value", "normalized_identifier", "is_iso_eid", "match_kind", "confidence", "requires_selection", "supporting_observations" ], "additionalProperties": false }, "maxItems": 128 }, "candidates_truncated": { "type": "boolean", "description": "When true, the candidate list requires manual selection." } }, "required": [ "id", "ordinal", "file_id", "content_type", "state", "ocr_state", "ocr_version", "ocr_attempts", "ocr_failure_code", "ocr_completed_at", "candidates", "candidates_truncated" ], "additionalProperties": false } }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "animal_id": { "type": "string", "format": "uuid" }, "identifier_id": { "type": "string", "format": "uuid" }, "identifier_value": { "type": "string", "maxLength": 100 }, "normalized_identifier": { "type": "string", "pattern": "^[0-9]{1,15}$" }, "is_iso_eid": { "type": "boolean" }, "match_kind": { "type": "string", "enum": [ "exact", "suffix", "partial" ] }, "confidence": { "type": "string", "enum": [ "high", "low" ] }, "requires_selection": { "type": "boolean" }, "supporting_observations": { "type": "array", "items": { "type": "object", "properties": { "media_id": { "type": "string", "format": "uuid" }, "digits": { "type": "string", "pattern": "^[0-9]{1,15}$" }, "ocr_confidence": { "type": "number", "minimum": 0, "maximum": 100 }, "box": { "type": "object", "properties": { "left": { "type": "number", "minimum": 0 }, "top": { "type": "number", "minimum": 0 }, "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "left", "top", "width", "height" ], "additionalProperties": false }, "match_kind": { "type": "string", "enum": [ "exact", "suffix", "partial" ] } }, "required": [ "media_id", "digits", "ocr_confidence", "box", "match_kind" ], "additionalProperties": false }, "maxItems": 128 } }, "required": [ "animal_id", "identifier_id", "identifier_value", "normalized_identifier", "is_iso_eid", "match_kind", "confidence", "requires_selection", "supporting_observations" ], "additionalProperties": false }, "maxItems": 128 }, "candidates_truncated": { "type": "boolean", "description": "When true, the candidate list requires manual selection." } }, "required": [ "source_sms_id", "source_message_id", "stage", "failure_code", "media", "candidates", "candidates_truncated" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Required read scope missing" }, "404": { "description": "Source unavailable to the current user and farm" } } } } }, "components": { "securitySchemes": { "LegacyKey": { "type": "http", "scheme": "bearer", "description": "Deprecated. Legacy rb_sk_ keys are for directed developer use only; they are not part of customer onboarding.", "x-deprecated": true }, "DeviceToken": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OAuth device access token from a registered, directed client. Scope requirements are listed per operation. Public client installation remains pending verification." } }, "schemas": { "Error": { "type": "object", "required": [ "success", "errors" ], "properties": { "success": { "const": false }, "errors": { "type": "array", "items": { "type": "object", "required": [ "message" ], "properties": { "code": { "type": "integer" }, "name": { "type": "string" }, "message": { "type": "string" } } } }, "data": { "type": "null" } } }, "Farm": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allow_private_threads": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "current_month_start": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "species": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "species_other": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "allow_private_threads", "current_month_start", "is_active", "name", "species", "species_other", "created_at", "updated_at" ] }, "FarmUsers": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "farm_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "farm_id", "user_id", "is_active", "role", "created_at", "updated_at" ] }, "Animal": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "farm_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "metadata": { "anyOf": [ {}, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "farm_id", "is_active", "metadata", "created_at", "updated_at" ] }, "AnimalIdentifier": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "animal_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_primary": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "value": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "animal_id", "is_active", "is_primary", "type", "value", "created_at", "updated_at" ] }, "Group": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "farm_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "farm_id", "description", "is_active", "name", "created_at", "updated_at" ] }, "Record": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "applied_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "applied_at", "description", "is_active", "name", "type", "created_at", "updated_at" ] }, "RecordItem": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "metadata": { "anyOf": [ {}, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "description", "is_active", "metadata", "name", "created_at", "updated_at" ] }, "File": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "mime_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "size": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "is_active", "mime_type", "name", "size", "url", "created_at", "updated_at" ] }, "FarmMember": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "farm_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "user_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "full_name": { "type": [ "string", "null" ] }, "phone_number_local": { "type": "string" } }, "required": [ "id", "full_name", "phone_number_local" ] } }, "required": [ "id", "farm_id", "user_id", "is_active", "role", "created_at", "updated_at", "user" ] }, "RecordWithItems": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "applied_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_active": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "record_items": { "type": "array", "items": { "$ref": "#/components/schemas/RecordItem" } } }, "required": [ "id", "applied_at", "description", "is_active", "name", "type", "created_at", "updated_at", "record_items" ] }, "GroupIdentity": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "RationIdentity": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "unit": { "type": "string" } }, "required": [ "id", "name", "unit" ] }, "FeedPlanIngredient": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "per_head_lbs": { "type": "string", "description": "Persisted decimal serialized as a JSON string." }, "position": { "type": "integer" } }, "required": [ "id", "name", "per_head_lbs", "position" ] }, "RationIngredient": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "per_head_lbs": { "type": "string", "description": "Persisted decimal serialized as a JSON string." }, "position": { "type": "integer" }, "ration_id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "per_head_lbs", "position", "ration_id", "created_at", "updated_at" ] }, "RationAssignmentWithGroup": { "type": "object", "properties": { "id": { "type": "string" }, "ration_id": { "type": "string" }, "group_id": { "type": "string" }, "feedings_per_day": { "type": "integer" }, "label": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "group": { "$ref": "#/components/schemas/GroupIdentity" } }, "required": [ "id", "ration_id", "group_id", "feedings_per_day", "label", "is_active", "created_at", "updated_at", "group" ] }, "RationWithRelations": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "farm_id": { "type": "string" }, "unit": { "type": "string" }, "ingredients": { "type": "array", "items": { "$ref": "#/components/schemas/RationIngredient" } }, "assignments": { "type": "array", "items": { "$ref": "#/components/schemas/RationAssignmentWithGroup" } } }, "required": [ "id", "created_at", "updated_at", "name", "is_active", "farm_id", "unit", "ingredients", "assignments" ] }, "FeedingDeliveryWithGroup": { "type": "object", "properties": { "id": { "type": "string" }, "feeding_id": { "type": "string" }, "group_id": { "type": "string" }, "actual_lbs": { "type": "string", "description": "Persisted decimal serialized as a JSON string." }, "client_updated_at": { "type": "string", "format": "date-time" }, "head_count": { "type": "integer" }, "is_active": { "type": "boolean" }, "record_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "group": { "$ref": "#/components/schemas/GroupIdentity" } }, "required": [ "id", "feeding_id", "group_id", "actual_lbs", "client_updated_at", "head_count", "is_active", "record_id", "created_at", "updated_at", "group" ] }, "AnimalWithIdentifiers": { "allOf": [ { "$ref": "#/components/schemas/Animal" }, { "type": "object", "properties": { "animal_identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/AnimalIdentifier" } } }, "required": [ "animal_identifiers" ] } ] }, "ChuteSessionEntryWithAnimal": { "type": "object", "properties": { "id": { "type": "string" }, "animal_id": { "type": "string" }, "session_id": { "type": "string" }, "captured_at": { "type": "string", "format": "date-time" }, "client_updated_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" }, "payload": {}, "position": { "type": "integer" }, "record_ids": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "animal": { "$ref": "#/components/schemas/AnimalWithIdentifiers" } }, "required": [ "id", "animal_id", "session_id", "captured_at", "client_updated_at", "is_active", "payload", "position", "record_ids", "created_at", "updated_at", "animal" ] }, "ImportWithRelations": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "COMPLETED", "FAILED", "PENDING", "PROCESSING" ] }, "id": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "user_id": { "type": "string" }, "farm_id": { "type": "string" }, "metadata": {}, "completed_at": { "anyOf": [ { "type": "null" }, { "type": "string", "format": "date-time" } ] }, "file_id": { "type": "string" }, "error_message": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "format": { "type": "string", "enum": [ "CSV", "JSON" ] }, "file": { "$ref": "#/components/schemas/File" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "full_name": { "type": [ "string", "null" ] }, "phone_number_local": { "type": [ "string", "null" ] } }, "required": [ "id", "full_name", "phone_number_local" ] } }, "required": [ "status", "id", "created_at", "updated_at", "user_id", "farm_id", "metadata", "completed_at", "file_id", "error_message", "format", "file", "user" ] }, "Action": { "type": "object", "properties": { "id": { "type": "string" }, "agent_action_id": { "type": [ "string", "null" ] }, "action_type": { "type": "string" }, "entity_id": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "ANIMAL", "ANIMAL_IDENTIFIER", "GROUP", "RECORD", "RECORD_ITEM" ] }, "state_after": {}, "state_before": {}, "undone_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "agent_action_id", "action_type", "entity_id", "entity_type", "state_after", "state_before", "undone_at", "created_at", "updated_at" ] }, "ImportItemWithAction": { "type": "object", "properties": { "id": { "type": "string" }, "action_id": { "type": [ "string", "null" ] }, "import_id": { "type": "string" }, "entity_id": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "ANIMAL", "ANIMAL_IDENTIFIER", "GROUP", "RECORD", "RECORD_ITEM" ] }, "error_message": { "type": [ "string", "null" ] }, "mapped_data": {}, "row_number": { "type": [ "integer", "null" ] }, "source_data": {}, "status": { "type": "string", "enum": [ "FAILED", "PENDING", "PROCESSED" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "action": { "anyOf": [ { "$ref": "#/components/schemas/Action" }, { "type": "null" } ] } }, "required": [ "id", "action_id", "import_id", "entity_id", "entity_type", "error_message", "mapped_data", "row_number", "source_data", "status", "created_at", "updated_at", "action" ] }, "ImportDetail": { "allOf": [ { "$ref": "#/components/schemas/ImportWithRelations" }, { "type": "object", "properties": { "import_items": { "type": "array", "items": { "$ref": "#/components/schemas/ImportItemWithAction" } } }, "required": [ "import_items" ] } ] }, "BirthBundle": { "type": "object", "properties": { "dam_id": { "type": "string", "format": "uuid" }, "birth_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "time_precision": { "type": "string", "enum": [ "date_only", "morning", "afternoon", "evening", "night" ], "default": "date_only" }, "dam_update": { "type": "object", "properties": { "kind": { "type": "string", "minLength": 1, "maxLength": 80 }, "notes": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false }, "maternal_observations": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "text": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "date", "text" ], "additionalProperties": false }, "maxItems": 20, "default": [] }, "lactation_observations": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "text": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "date", "text" ], "additionalProperties": false }, "maxItems": 20, "default": [] }, "offspring": { "type": "array", "items": { "type": "object", "properties": { "review_label": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Temporary review label only; never an invented identifier." }, "sex": { "type": "string", "enum": [ "male", "female", "unknown" ] }, "birth_weight": { "type": "object", "properties": { "value": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "unit": { "type": "string", "enum": [ "kg", "lb" ] } }, "required": [ "value", "unit" ], "additionalProperties": false }, "vigor": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "text": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "date", "text" ], "additionalProperties": false }, "maxItems": 20, "default": [] }, "supplementation": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "substance": { "type": "string", "minLength": 1, "maxLength": 80 }, "amount": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, "unit": { "type": "string", "minLength": 1, "maxLength": 80 }, "source": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Producer-stated source, e.g. own dam. Never prescribe care." } }, "required": [ "date", "substance", "amount", "unit", "source" ], "additionalProperties": false }, "maxItems": 20, "default": [] } }, "required": [ "review_label", "sex" ], "additionalProperties": false }, "minItems": 1, "maxItems": 20 }, "sire": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unknown", "presumed", "confirmed" ] }, "animal_id": { "type": "string", "format": "uuid" }, "provenance": { "type": "string", "minLength": 1, "maxLength": 1000 }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "status" ], "additionalProperties": false, "default": { "status": "unknown" } }, "protocol": { "type": "object", "properties": { "claimed_name": { "type": "string", "minLength": 1, "maxLength": 80 }, "completed_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "version_id": { "type": "string", "format": "uuid" }, "offspring_labels": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "minItems": 1, "maxItems": 20 } }, "required": [ "claimed_name", "completed_date", "offspring_labels" ], "additionalProperties": false }, "follow_up": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 1000 }, "due_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "offspring_labels": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "minItems": 1, "maxItems": 20 } }, "required": [ "name", "offspring_labels" ], "additionalProperties": false }, "maxItems": 20, "default": [] }, "group_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20, "default": [], "description": "Explicitly reviewed current group memberships. Does not record movement." }, "current_location": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Explicitly reviewed current location only; does not create movement history." }, "source_sms_id": { "type": "string", "format": "uuid" }, "source_message_id": { "type": "string", "format": "uuid" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "file_id": { "type": "string", "format": "uuid" }, "media_id": { "type": "string", "format": "uuid" }, "link_to_dam": { "type": "boolean", "default": false }, "offspring_label": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "file_id" ], "additionalProperties": false }, "maxItems": 20, "default": [] }, "unresolved": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1000 }, "maxItems": 30, "default": [] }, "additional_source_sms_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 20, "default": [] } }, "required": [ "dam_id", "birth_date", "offspring" ], "additionalProperties": false }, "BirthRequest": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "bundle": { "$ref": "#/components/schemas/BirthBundle" } }, "required": [ "request_id", "bundle" ], "additionalProperties": false }, "BirthConfirmation": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "bundle": { "$ref": "#/components/schemas/BirthBundle" }, "confirmation_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "request_id", "bundle", "confirmation_hash" ], "additionalProperties": false }, "BirthPreview": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "bundle": { "$ref": "#/components/schemas/BirthBundle" }, "confirmation_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "review": { "type": "object", "description": "Every resolved dam, group, protocol, evidence detail and unresolved fact must be shown alongside the complete bundle before obtaining producer approval." } }, "required": [ "request_id", "bundle", "confirmation_hash", "review" ] }, "BirthEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "farm_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "confirmation_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "created_by_user_id": { "type": "string", "format": "uuid" }, "dam_id": { "type": "string", "format": "uuid" }, "birth_date": { "type": "string", "format": "date-time" }, "time_precision": { "type": [ "string", "null" ] }, "bundle": { "type": "object", "properties": { "input": { "$ref": "#/components/schemas/BirthBundle" }, "review": { "type": "object", "description": "The resolved dam, groups, protocol, evidence and unresolved facts reviewed before confirmation." } }, "required": [ "input", "review" ] }, "record_id": { "type": "string", "format": "uuid" }, "source_sms_id": { "type": [ "string", "null" ], "format": "uuid" }, "source_message_id": { "type": [ "string", "null" ], "format": "uuid" }, "agent_action_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "offspring": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "birth_event_id": { "type": "string", "format": "uuid" }, "animal_id": { "type": "string", "format": "uuid" }, "review_label": { "type": "string" }, "position": { "type": "integer" }, "details": { "type": "object" } }, "required": [ "id", "birth_event_id", "animal_id", "review_label", "position", "details" ] } }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/FarmTask" } }, "record": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "mime_type": { "type": "string" } }, "required": [ "id", "name", "mime_type" ] } } }, "required": [ "id", "files" ] }, "care_records": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "record_items": { "type": "array", "items": { "type": "object" } } }, "required": [ "id", "name", "applied_at", "record_items" ] } } }, "required": [ "id", "farm_id", "request_id", "confirmation_hash", "created_by_user_id", "dam_id", "birth_date", "time_precision", "bundle", "record_id", "source_sms_id", "source_message_id", "agent_action_id", "created_at", "offspring", "tasks", "record", "care_records" ] }, "FarmTask": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "farm_id": { "type": "string", "format": "uuid" }, "birth_event_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "TODO", "DONE", "CANCELLED" ] }, "due_date": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "animals": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] } } }, "required": [ "id", "farm_id", "birth_event_id", "name", "status", "due_date", "created_at", "updated_at" ] }, "FarmProtocolVersion": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "farm_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "version": { "type": "string" }, "steps": { "type": "array", "items": { "type": "string" } }, "created_by_user_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "farm_id", "name", "version", "steps", "created_by_user_id", "created_at" ] }, "FarmProtocolVersionInput": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "version": { "type": "string", "minLength": 1, "maxLength": 80 }, "steps": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1000 }, "minItems": 1, "maxItems": 40 } }, "required": [ "name", "version", "steps" ], "additionalProperties": false } } }, "tags": [ { "name": "farms", "description": "Farms" }, { "name": "animals", "description": "Animals" }, { "name": "identifiers", "description": "Animal identifiers" }, { "name": "groups", "description": "Groups" }, { "name": "records", "description": "Records" }, { "name": "record-items", "description": "Record items" }, { "name": "memory", "description": "Farm memory" }, { "name": "chute-sessions", "description": "Chute sessions" }, { "name": "feedings", "description": "Feedings" }, { "name": "feeding-plans", "description": "Feeding plans" }, { "name": "rations", "description": "Rations" }, { "name": "reports", "description": "Farm reports" }, { "name": "recurring-events", "description": "Recurring events" }, { "name": "scheduled-events", "description": "Scheduled events" }, { "name": "notifications", "description": "Notifications" }, { "name": "files", "description": "Files" }, { "name": "imports", "description": "Legacy imports" }, { "name": "import-requests", "description": "Import requests" }, { "name": "default-farm", "description": "Default farm" }, { "name": "oauth", "description": "OAuth" }, { "name": "exports", "description": "Farm archives" } ] }