{"openapi":"3.1.0","info":{"title":"Mela API","description":"Farmer intelligence layer. Conventions: docs/api/conventions.md","version":"0.1.0"},"paths":{"/health/live":{"get":{"tags":["operations"],"summary":"The process is up. Checks no dependencies.","operationId":"health_live","responses":{"200":{"description":"Process is running","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Live"}}}}}}},"/health/ready":{"get":{"tags":["operations"],"summary":"Ready to serve traffic: the database answers within 2 seconds.","operationId":"health_ready","responses":{"200":{"description":"Ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ready"}}}},"503":{"description":"A dependency is unavailable","headers":{"Retry-After":{"schema":{"type":"integer","format":"int64","minimum":0},"description":"Seconds to wait before retrying"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/admin/api-clients":{"get":{"tags":["api-clients"],"operationId":"list_api_clients","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiClientPage"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["api_clients:read"]}]},"post":{"tags":["api-clients"],"summary":"Creates a client. The secret is in this response only.","operationId":"create_api_client","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewApiClient"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiClientSecret"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing permission, or granting a scope you do not hold","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["api_clients:write"]}]}},"/v1/admin/api-clients/{client_id}":{"get":{"tags":["api-clients"],"operationId":"get_api_client","parameters":[{"name":"client_id","in":"path","description":"The client's `id` (not its public `client_id`)","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiClientView"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["api_clients:read"]}]},"patch":{"tags":["api-clients"],"summary":"Updates name, description, scopes or status. Scope and status changes apply to existing\ntokens immediately.","operationId":"update_api_client","parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiClientUpdate"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiClientView"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["api_clients:write"]}]}},"/v1/admin/api-clients/{client_id}/rotate-secret":{"post":{"tags":["api-clients"],"summary":"Issues a new secret. The old one keeps working for the configured grace period\n(`auth.client_secret_grace_secs`) so the client can switch without downtime.","operationId":"rotate_api_client_secret","parameters":[{"name":"client_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiClientSecret"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["api_clients:write"]}]}},"/v1/admin/audit-events":{"get":{"tags":["audit"],"summary":"Audit events, newest first.","operationId":"list_events","parameters":[{"name":"actor_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"action","in":"query","description":"Exact action (`auth.login.failed`) or a prefix ending in `.` (`auth.`).","required":false,"schema":{"type":"string"}},{"name":"resource_type","in":"query","required":false,"schema":{"type":"string"}},{"name":"resource_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"outcome","in":"query","description":"`success`, `failure` or `denied`.","required":false,"schema":{"type":"string"}},{"name":"from","in":"query","description":"Inclusive lower bound (RFC 3339).","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","description":"Exclusive upper bound (RFC 3339).","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","description":"1–200, default 50.","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventPage"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing `audit:read`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["audit:read"]}]}},"/v1/admin/roles":{"get":{"tags":["users"],"summary":"Roles and the permissions each grants.","operationId":"list_roles","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleCatalog"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["roles:read"]}]}},"/v1/admin/users":{"get":{"tags":["users"],"summary":"Lists user accounts, newest first.","operationId":"list_users","parameters":[{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/AccountStatus"}},{"name":"kind","in":"query","required":false,"schema":{"$ref":"#/components/schemas/UserKind"}},{"name":"role","in":"query","description":"Users holding this role.","required":false,"schema":{"type":"string"}},{"name":"email","in":"query","description":"Email prefix, case-insensitive.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"1–200, default 50.","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserPage"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["users:read"]}]},"post":{"tags":["users"],"summary":"Creates an account without a password. The response carries a one-time token for\n`POST /v1/auth/password/reset`; deliver it to the user securely.","operationId":"create_user","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewUser"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatedUser"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing permission, or granting a role beyond your own","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Email already in use","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["users:write"]}]}},"/v1/admin/users/{user_id}":{"get":{"tags":["users"],"operationId":"get_user","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserView"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["users:read"]}]},"patch":{"tags":["users"],"summary":"Updates name, phone or status. Disabling ends the user's sessions.","operationId":"update_user","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserUpdate"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserView"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Disabling yourself or the last super admin","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["users:write"]}]}},"/v1/admin/users/{user_id}/mfa":{"delete":{"tags":["users"],"summary":"Removes the user's MFA (lost device) and ends their sessions; they set it up again at\ntheir next login.","operationId":"reset_mfa","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"MFA removed"},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Resetting your own MFA","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["users:write"]}]}},"/v1/admin/users/{user_id}/password-reset":{"post":{"tags":["users"],"summary":"Issues a one-time password reset token for the user (the previous one stops working).","operationId":"issue_password_reset","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordSetup"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["users:write"]}]}},"/v1/admin/users/{user_id}/roles":{"put":{"tags":["users"],"summary":"Replaces the user's roles. You can grant or remove only roles whose permissions you hold\nover the same areas.","operationId":"set_roles","parameters":[{"name":"user_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RolesRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserView"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Removing the last super admin","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid input","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["users:write"]}]}},"/v1/auth/login":{"post":{"tags":["auth"],"summary":"Step 1 of a login: email and password.","operationId":"login","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}},"required":true},"responses":{"200":{"description":"Authenticated, or MFA needed (see `status`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginResponse"}}}},"401":{"description":"Invalid credentials or locked account (indistinguishable)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/logout":{"post":{"tags":["auth"],"summary":"Ends the current session (its access and refresh tokens stop working).","operationId":"logout","responses":{"204":{"description":"Logged out"},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"API client tokens have no session","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":[]}]}},"/v1/auth/mfa/enroll":{"post":{"tags":["auth"],"summary":"Starts authenticator setup (after a login that returned `mfa_enrollment_required`).","operationId":"mfa_enroll","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MfaTokenRequest"}}},"required":true},"responses":{"200":{"description":"A new TOTP secret","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MfaEnrollmentResponse"}}}},"401":{"description":"Invalid MFA token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"MFA is already set up","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/mfa/enroll/confirm":{"post":{"tags":["auth"],"summary":"Confirms authenticator setup with a first code; completes the login.","operationId":"mfa_enroll_confirm","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MfaConfirmRequest"}}},"required":true},"responses":{"200":{"description":"MFA enabled and authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MfaEnabledResponse"}}}},"401":{"description":"Invalid code or MFA token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/mfa/verify":{"post":{"tags":["auth"],"summary":"Step 2 of a login for accounts with MFA.","operationId":"mfa_verify","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MfaVerifyRequest"}}},"required":true},"responses":{"200":{"description":"Authenticated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"401":{"description":"Invalid code or MFA token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/password/reset":{"post":{"tags":["auth"],"summary":"Sets a password with a one-time token. Ends every session of the account.","operationId":"password_reset","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordResetRequest"}}},"required":true},"responses":{"204":{"description":"Password set"},"422":{"description":"Invalid token or password policy","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/refresh":{"post":{"tags":["auth"],"summary":"Exchanges a refresh token for new tokens. Reusing a refresh token ends the session.","operationId":"refresh","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefreshRequest"}}},"required":true},"responses":{"200":{"description":"New tokens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"401":{"description":"Invalid, expired, revoked or reused refresh token","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/auth/token":{"post":{"tags":["auth"],"summary":"OAuth2 client-credentials grant for API clients. Accepts form or JSON bodies. Errors carry\nthe OAuth2 `error` code as an extension member.","operationId":"token","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}},"required":true},"responses":{"200":{"description":"Access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientTokenResponse"}}}},"400":{"description":"invalid_request, invalid_scope or unsupported_grant_type","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"invalid_client","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/buyers":{"get":{"tags":["finance"],"summary":"Buyers, by name.","operationId":"list_buyers","parameters":[{"name":"q","in":"query","description":"Part of the name.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32","minimum":0}}],"responses":{"200":{"description":"Buyers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerList"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["finance:read"]}]},"post":{"tags":["finance"],"summary":"Record a buyer (or get the existing one with the same name, type and district).","operationId":"create_buyer","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewBuyer"}}},"required":true},"responses":{"201":{"description":"The buyer's ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Created"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["finance:write"]}]}},"/v1/claims/{claim_id}":{"get":{"tags":["provenance"],"summary":"One claim with its source, evidence (detached links included) and status history.","operationId":"get_claim","parameters":[{"name":"claim_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The claim","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimDetail"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["claims:read"]}]}},"/v1/claims/{claim_id}/evidence":{"post":{"tags":["provenance"],"summary":"Links evidence to a claim. Rejected, expired and superseded claims take no new evidence.","operationId":"attach_evidence","parameters":[{"name":"claim_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewEvidence"}}},"required":true},"responses":{"201":{"description":"Linked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceLink"}}}},"400":{"description":"Invalid body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Claim not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Already linked, or the claim is final","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid evidence ID","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["claims:write"]}]}},"/v1/claims/{claim_id}/evidence/{link_id}":{"delete":{"tags":["provenance"],"summary":"Detaches evidence. The link is kept with who detached it, when and why.","operationId":"detach_evidence","parameters":[{"name":"claim_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"link_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"reason","in":"query","description":"Why the evidence no longer supports the claim (kept on the link).","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Detached"},"400":{"description":"Missing reason","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such active link","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Empty reason","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["claims:write"]}]}},"/v1/claims/{claim_id}/status":{"post":{"tags":["provenance"],"summary":"Moves a claim through its lifecycle (e.g. `pending_verification`, `disputed`). Final\nstatuses never change; a correction is a new claim that supersedes the old one.","operationId":"change_status","parameters":[{"name":"claim_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusUpdate"}}},"required":true},"responses":{"204":{"description":"Changed"},"400":{"description":"Invalid body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Claim not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Transition not allowed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["claims:write"]}]}},"/v1/consents/{consent_id}":{"get":{"tags":["consent"],"summary":"A consent.","operationId":"get_consent","parameters":[{"name":"consent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The consent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentView"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["consent:read"]}]}},"/v1/consents/{consent_id}/revoke":{"post":{"tags":["consent"],"summary":"Revoke a consent, immediately: no new data is accepted under it.","operationId":"revoke_consent","parameters":[{"name":"consent_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeRequest"}}},"required":true},"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentView"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Already revoked","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["consent:write"]}]}},"/v1/crop-cycles/{cycle_id}":{"get":{"tags":["agriculture"],"summary":"A crop cycle with its inputs, harvests, losses and current plausibility flags.","operationId":"get_crop_cycle","parameters":[{"name":"cycle_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The crop cycle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CropCycleDetail"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["agriculture:read"]}]}},"/v1/crop-cycles/{cycle_id}/harvests":{"post":{"tags":["agriculture"],"summary":"Record a harvest (and its losses). A final harvest closes the cycle and fixes its yield; a\nharvest before planting is refused.","operationId":"record_harvest","parameters":[{"name":"cycle_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewHarvest"}}},"required":true},"responses":{"201":{"description":"Recorded; the cycle with its yield and flags","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CropCycleDetail"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The cycle is planned or abandoned","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields (before planting, unknown unit…)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["agriculture:write"]}]}},"/v1/crop-cycles/{cycle_id}/inputs":{"post":{"tags":["agriculture"],"summary":"Record an input used on a crop cycle (fertilizer, seed, agrochemical), in the farmer's\nunits: 2 `gunia_50kg` of DAP is stored as 100 kg.","operationId":"apply_input","parameters":[{"name":"cycle_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewInput"}}},"required":true},"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InputView"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The cycle was abandoned","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields (unknown input or unit…)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["agriculture:write"]}]}},"/v1/crop-cycles/{cycle_id}/status":{"post":{"tags":["agriculture"],"summary":"Move a crop cycle along its lifecycle: planned → planted → growing → harvested, failed or\nabandoned.","operationId":"change_crop_cycle_status","parameters":[{"name":"cycle_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusChange"}}},"required":true},"responses":{"200":{"description":"Changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CropCycleDetail"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Transition not allowed, or the cycle changed (version)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields (missing date or reason…)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["agriculture:write"]}]}},"/v1/farmers":{"get":{"tags":["farmers"],"summary":"Search farmers by name (typo-tolerant, any order) and area.","operationId":"search","parameters":[{"name":"q","in":"query","description":"Name, typo-tolerant (trigram word similarity), any order.","required":false,"schema":{"type":"string"}},{"name":"region_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"district_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"ward_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/FarmerStatus"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of farmers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FarmerPage"}}}},"400":{"description":"Invalid query","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid filter","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farmers:read"]}]},"post":{"tags":["farmers"],"summary":"Register a farmer. Duplicates found are returned for review, never merged.","operationId":"register","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewFarmer"}}},"required":true},"responses":{"200":{"description":"Already registered with this `id` (a retry)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Registered"}}}},"201":{"description":"Registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Registered"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the permission, or the home area is outside your areas","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The `id` belongs to another registration","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farmers:write"]}]}},"/v1/farmers/duplicates":{"get":{"tags":["farmers"],"summary":"The duplicate review queue.","operationId":"list_duplicates","parameters":[{"name":"status","in":"query","description":"`open` (default), `dismissed` or `merged`.","required":false,"schema":{"type":"string"}},{"name":"outcome","in":"query","description":"`possible_duplicate` or `likely_duplicate`.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of candidate pairs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DuplicatePage"}}}},"400":{"description":"Invalid query","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid filter","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farmers:merge"]}]}},"/v1/farmers/duplicates/{candidate_id}/dismiss":{"post":{"tags":["farmers"],"summary":"Not a duplicate. The pair reopens only if new shared evidence appears.","operationId":"dismiss_duplicate","parameters":[{"name":"candidate_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dismissal"}}},"required":true},"responses":{"200":{"description":"Dismissed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DuplicateCandidate"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such open candidate","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farmers:merge"]}]}},"/v1/farmers/lookup":{"post":{"tags":["farmers"],"summary":"Find farmers by exactly one of Mela ID, ID number or phone.","operationId":"lookup","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lookup"}}},"required":true},"responses":{"200":{"description":"Matches in your areas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupResult"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Not exactly one key, or an invalid number","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farmers:read"]}]}},"/v1/farmers/merge":{"post":{"tags":["farmers"],"summary":"Merge a confirmed duplicate into the surviving record (lineage kept, reversible).","operationId":"merge","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MergeRequest"}}},"required":true},"responses":{"201":{"description":"Merged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MergeView"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"A farmer was not found (or is outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"A farmer cannot be merged (already merged, deceased, withdrawn)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farmers:merge"]}]}},"/v1/farmers/merges/{merge_id}/unmerge":{"post":{"tags":["farmers"],"summary":"Undo a merge: the merged record gets its previous status back.","operationId":"unmerge","parameters":[{"name":"merge_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Unmerge"}}},"required":true},"responses":{"200":{"description":"Unmerged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MergeView"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"No such active merge","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Missing reason","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farmers:merge"]}]}},"/v1/farmers/{farmer_id}":{"get":{"tags":["farmers"],"summary":"One farmer: identity, area, household, masked identifiers and phones, registrations.","operationId":"get_farmer","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The farmer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FarmerDetail"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farmers:read"]}]},"patch":{"tags":["farmers"],"summary":"Change names, sex, birth, languages or education. Changed attributes get new claims.","operationId":"update_identity","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentityUpdate"}}},"required":true},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FarmerDetail"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Changed since `expected_version`, or not editable (merged, deceased, withdrawn)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farmers:write"]}]}},"/v1/farmers/{farmer_id}/consents":{"get":{"tags":["consent"],"summary":"A farmer's consents, newest first.","operationId":"list_consents","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Consents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentList"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Farmer not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["consent:read"]}]},"post":{"tags":["consent"],"summary":"Record a farmer's consent.","operationId":"record_consent","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewConsent"}}},"required":true},"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentView"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Farmer not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["consent:write"]}]}},"/v1/farmers/{farmer_id}/expenses":{"get":{"tags":["finance"],"summary":"A farmer's expenses, newest first.","operationId":"list_expenses","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Expenses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseList"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Farmer not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["finance:read"]}]},"post":{"tags":["finance"],"summary":"Record an agricultural expense, tied to a season (through a crop cycle, or given).","operationId":"record_expense","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewExpense"}}},"required":true},"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpenseView"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Farmer not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["finance:write"]}]}},"/v1/farmers/{farmer_id}/farms":{"get":{"tags":["farms"],"summary":"A farmer's farms.","operationId":"list_farmer_farms","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Farms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FarmList"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Farmer not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farms:read"]}]},"post":{"tags":["farms"],"summary":"Register a farm for a farmer.","operationId":"register_farm","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewFarm"}}},"required":true},"responses":{"201":{"description":"Registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FarmSummary"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Farmer not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The farmer is merged, deceased or withdrawn","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farms:write"]}]}},"/v1/farmers/{farmer_id}/financial-history":{"get":{"tags":["finance"],"summary":"Financing, repayments, savings, mobile money and the indicators (Restricted-PII: the read\nis audited and the indicators are kept as a snapshot).","operationId":"financial_history","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Financial history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialHistory"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Farmer not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["finance:restricted_read"]}]}},"/v1/farmers/{farmer_id}/financing":{"post":{"tags":["finance"],"summary":"Record a loan, advance or input credit with its schedule and payments so far.","operationId":"record_financing","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewFinancing"}}},"required":true},"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoanView"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Farmer not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["finance:write"]}]}},"/v1/farmers/{farmer_id}/household":{"put":{"tags":["farmers"],"summary":"Set the household composition.","operationId":"set_household","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetHousehold"}}},"required":true},"responses":{"200":{"description":"Set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HouseholdView"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Not editable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farmers:write"]}]}},"/v1/farmers/{farmer_id}/identifiers":{"post":{"tags":["farmers"],"summary":"Add an ID number (encrypted; one per kind).","operationId":"add_identifier","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewIdentifier"}}},"required":true},"responses":{"201":{"description":"Added (masked)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentifierView"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Already has one of this kind, or not editable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid number","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farmers:write"]}]}},"/v1/farmers/{farmer_id}/income-summary":{"get":{"tags":["finance"],"summary":"Agricultural income per agricultural year, season and crop (TZS).","operationId":"income_summary","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"seasons","in":"query","description":"How many recent seasons to break down (default 10, at most 40).","required":false,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Income summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncomeSummary"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Farmer not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["finance:read"]}]}},"/v1/farmers/{farmer_id}/location":{"put":{"tags":["farmers"],"summary":"Set the home ward (district and region follow), village and optional home point.","operationId":"set_location","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetLocation"}}},"required":true},"responses":{"200":{"description":"Set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FarmerDetail"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the permission, or the new area is outside your areas","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Not editable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Unknown ward or a point outside Tanzania","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farmers:write"]}]}},"/v1/farmers/{farmer_id}/merges":{"get":{"tags":["farmers"],"summary":"Merges this farmer took part in, newest first (lineage).","operationId":"list_merges","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Merges","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MergeList"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farmers:read"]}]}},"/v1/farmers/{farmer_id}/mobile-money-summaries":{"post":{"tags":["finance"],"summary":"Record one month of mobile-money aggregates (inflow, outflow, counts). Needs the farmer's\nconsent (scope `financial_history`); the same month and wallet replaces the earlier one.","operationId":"record_mobile_money","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewMobileMoneySummary"}}},"required":true},"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MobileMoneyView"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Farmer not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"No active consent","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["finance:write"]}]}},"/v1/farmers/{farmer_id}/phones":{"post":{"tags":["farmers"],"summary":"Add a phone (encrypted). A number already on another farmer is flagged `is_shared`.","operationId":"add_phone","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewPhone"}}},"required":true},"responses":{"201":{"description":"Added (masked)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneView"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Already on this farmer, or not editable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid number, or too many phones","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farmers:write"]}]}},"/v1/farmers/{farmer_id}/production-history":{"get":{"tags":["agriculture"],"summary":"A farmer's production history: per season and crop, per crop, and a summary (seasons\nactive, crops, mean yield index, trend, consistency).","operationId":"production_history","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Production history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductionHistory"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Farmer not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["agriculture:read"]}]}},"/v1/farmers/{farmer_id}/sales":{"get":{"tags":["finance"],"summary":"A farmer's sales, newest first.","operationId":"list_sales","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Sales","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaleList"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Farmer not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["finance:read"]}]},"post":{"tags":["finance"],"summary":"Record a sale: quantity in the farmer's units (stored in kg), amount or price per unit,\nbuyer and payment. Linked to the crop cycle and harvest when known; prices far outside\nthe market band are flagged.","operationId":"record_sale","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewSale"}}},"required":true},"responses":{"201":{"description":"Recorded, with any flags","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaleView"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Farmer not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["finance:write"]}]}},"/v1/farmers/{farmer_id}/savings-groups":{"post":{"tags":["finance"],"summary":"Record a savings-group membership. Needs the farmer's consent (scope `financial_history`).","operationId":"record_savings","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewSavingsMembership"}}},"required":true},"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavingsView"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Farmer not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"No active consent","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["finance:write"]}]}},"/v1/farmers/{farmer_id}/status":{"post":{"tags":["farmers"],"summary":"Move a farmer along the lifecycle (register, activate, deactivate, deceased, withdrawn).","operationId":"change_farmer_status","parameters":[{"name":"farmer_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusChange"}}},"required":true},"responses":{"200":{"description":"Changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FarmerDetail"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Transition not allowed","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farmers:write"]}]}},"/v1/farms":{"get":{"tags":["farms"],"summary":"Farms by bounding box and admin area.","operationId":"search_farms","parameters":[{"name":"bbox","in":"query","description":"`west,south,east,north` (WGS84): farms with a plot intersecting the box.","required":false,"schema":{"type":"string"}},{"name":"region_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"district_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"ward_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"farmer_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of farms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FarmPage"}}}},"400":{"description":"Invalid query","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid bbox","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farms:read"]}]}},"/v1/farms/{farm_id}":{"get":{"tags":["farms"],"summary":"A farm and its plots as a GeoJSON FeatureCollection.","operationId":"get_farm","parameters":[{"name":"farm_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"FeatureCollection with a `farm` member","content":{"application/geo+json":{"schema":{"$ref":"#/components/schemas/FarmCollection"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farms:read"]}]}},"/v1/farms/{farm_id}/plots":{"post":{"tags":["farms"],"summary":"Add a plot. Malformed geometry is refused (422, one error per problem); anything suspicious\n(overlap, water, protected area, area mismatch, repaired boundary) is stored and flagged.","operationId":"add_plot","parameters":[{"name":"farm_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewPlot"}}},"required":true},"responses":{"201":{"description":"Added (GeoJSON Feature; see `flag_count`)","content":{"application/geo+json":{"schema":{"$ref":"#/components/schemas/PlotFeature"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the permission, or the plot is outside your areas","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Farm not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The farm is inactive","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid geometry or fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farms:write"]}]}},"/v1/farms/{farm_id}/visits":{"get":{"tags":["farms"],"summary":"A farm's visits, newest first.","operationId":"list_visits","parameters":[{"name":"farm_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Visits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisitList"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farms:read"]}]},"post":{"tags":["farms"],"summary":"Check in at a farm. Within the geofence, the visit becomes evidence for the plot's\nlocation; outside, it is kept and flagged.","operationId":"record_visit","parameters":[{"name":"farm_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewVisit"}}},"required":true},"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisitRecorded"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Farm or plot not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The farm has no plot yet","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farms:write"]}]}},"/v1/financing/{financing_id}":{"get":{"tags":["finance"],"summary":"A financing record with its repayments (Restricted-PII; the read is audited).","operationId":"get_financing","parameters":[{"name":"financing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The financing record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoanView"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["finance:restricted_read"]}]}},"/v1/financing/{financing_id}/repayments":{"post":{"tags":["finance"],"summary":"Record a repayment: the payment goes to the unpaid instalment due that day, or a new\ninstalment is recorded. Days late = paid − due. A loan fully settled becomes `repaid`.","operationId":"record_repayment","parameters":[{"name":"financing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewRepayment"}}},"required":true},"responses":{"201":{"description":"Recorded; the loan with its repayments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoanView"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["finance:write"]}]}},"/v1/financing/{financing_id}/status":{"post":{"tags":["finance"],"summary":"Change a financing record's status (defaulted, written off, restructured, repaid).","operationId":"change_financing_status","parameters":[{"name":"financing_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancingStatusChange"}}},"required":true},"responses":{"200":{"description":"Changed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoanView"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Changed since (version)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["finance:write"]}]}},"/v1/me":{"get":{"tags":["auth"],"summary":"The caller: account, roles and effective permissions (with their areas).","operationId":"me","responses":{"200":{"description":"The authenticated actor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":[]}]}},"/v1/perennial-stands/{stand_id}":{"get":{"tags":["agriculture"],"summary":"A perennial stand with its yearly counts and its seasons, read per tree.","operationId":"get_stand","parameters":[{"name":"stand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The stand","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandDetail"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["agriculture:read"]}]}},"/v1/perennial-stands/{stand_id}/observations":{"post":{"tags":["agriculture"],"summary":"Record a yearly tree count (or the stand's removal).","operationId":"observe_stand","parameters":[{"name":"stand_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewObservation"}}},"required":true},"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandDetail"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The stand was removed, or changed (version)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["agriculture:write"]}]}},"/v1/plots/{plot_id}":{"get":{"tags":["farms"],"summary":"A plot as a GeoJSON Feature.","operationId":"get_plot","parameters":[{"name":"plot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Feature","content":{"application/geo+json":{"schema":{"$ref":"#/components/schemas/PlotFeature"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farms:read"]}]}},"/v1/plots/{plot_id}/checks":{"get":{"tags":["farms"],"summary":"A plot's check results (overlaps, water, protected area, area discrepancy, repairs).","operationId":"plot_checks","parameters":[{"name":"plot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"history","in":"query","description":"Include superseded results.","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Checks","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckList"}}}},"400":{"description":"Invalid query","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farms:read"]}]}},"/v1/plots/{plot_id}/crop-cycles":{"get":{"tags":["agriculture"],"summary":"A plot's crop cycles, newest season first.","operationId":"list_plot_crop_cycles","parameters":[{"name":"plot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Crop cycles","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CropCycleList"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Plot not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["agriculture:read"]}]},"post":{"tags":["agriculture"],"summary":"Start a crop cycle on a plot: crop, season, planted area and practices.","operationId":"start_crop_cycle","parameters":[{"name":"plot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewCropCycle"}}},"required":true},"responses":{"201":{"description":"Started, with any plausibility flags","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CropCycleDetail"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Plot not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The plot is retired or already has this crop this season","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields (unknown crop, season of another zone…)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["agriculture:write"]}]}},"/v1/plots/{plot_id}/geometry":{"put":{"tags":["farms"],"summary":"Replace a plot's geometry (e.g. a walked boundary after a drawn one); checks are re-run.","operationId":"change_geometry","parameters":[{"name":"plot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeometryChange"}}},"required":true},"responses":{"200":{"description":"Changed","content":{"application/geo+json":{"schema":{"$ref":"#/components/schemas/PlotFeature"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the permission, or the new geometry is outside your areas","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Changed since `expected_version`, or retired","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid geometry","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farms:write"]}]}},"/v1/plots/{plot_id}/perennial-stands":{"get":{"tags":["agriculture"],"summary":"A plot's perennial stands.","operationId":"list_plot_stands","parameters":[{"name":"plot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Stands","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandList"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Plot not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["agriculture:read"]}]},"post":{"tags":["agriculture"],"summary":"Record a perennial stand (coffee, cashew, avocado…) on a plot, with its first tree count.\nThe crop's cycles on the plot join it.","operationId":"record_stand","parameters":[{"name":"plot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewStand"}}},"required":true},"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandDetail"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Plot not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"The plot is retired or already has this stand","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields (annual crop, future year…)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["agriculture:write"]}]}},"/v1/plots/{plot_id}/tenure":{"put":{"tags":["farms"],"summary":"Change a plot's tenure and/or land use.","operationId":"change_tenure","parameters":[{"name":"plot_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenureChange"}}},"required":true},"responses":{"200":{"description":"Changed","content":{"application/geo+json":{"schema":{"$ref":"#/components/schemas/PlotFeature"}}}},"400":{"description":"Malformed body","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Retired plot","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Invalid fields","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farms:write"]}]}},"/v1/reference/admin-areas":{"get":{"tags":["reference"],"summary":"Administrative areas (no geometry), ordered by code.","operationId":"list_admin_areas","parameters":[{"name":"level","in":"query","description":"1 region, 2 district, 3 ward.","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"parent_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of areas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdminAreaPage"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["reference:read"]}]}},"/v1/reference/admin-areas/{area_id}":{"get":{"tags":["reference"],"summary":"One area as a GeoJSON Feature (RFC 7946).","operationId":"get_admin_area","parameters":[{"name":"area_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"detail","in":"query","description":"`simplified` (default, ~100 m) or `full`.","required":false,"schema":{"$ref":"#/components/schemas/Detail"}}],"responses":{"200":{"description":"GeoJSON Feature","content":{"application/geo+json":{"schema":{"type":"object"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["reference:read"]}]}},"/v1/reference/calendars":{"get":{"tags":["reference"],"summary":"Planting and harvest windows by zone, crop and season (indicative).","operationId":"list_calendars","parameters":[{"name":"zone","in":"query","required":false,"schema":{"type":"string"}},{"name":"crop","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of calendar entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalendarPage"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["reference:read"]}]}},"/v1/reference/crops":{"get":{"tags":["reference"],"summary":"Crops with their variety classes.","operationId":"list_crops","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of crops","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CropPage"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["reference:read"]}]}},"/v1/reference/inputs":{"get":{"tags":["reference"],"summary":"Farm inputs: fertilizers, seed types, agrochemicals.","operationId":"list_inputs","parameters":[{"name":"category","in":"query","description":"`fertilizer`, `organic_fertilizer`, `seed` or `agrochemical`.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of inputs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InputPage"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["reference:read"]}]}},"/v1/reference/resolve":{"get":{"tags":["reference"],"summary":"The ward, district, region and agro-ecological zone of a point, with crop calendars.","operationId":"resolve","parameters":[{"name":"lon","in":"query","description":"Longitude (WGS84).","required":true,"schema":{"type":"number","format":"double"}},{"name":"lat","in":"query","description":"Latitude (WGS84).","required":true,"schema":{"type":"number","format":"double"}},{"name":"crop","in":"query","description":"Limit the calendars to one crop.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Where the point is","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PointZone"}}}},"400":{"description":"Missing or invalid lon/lat","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not in any Tanzanian ward","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["reference:read"]}]}},"/v1/reference/seasons":{"get":{"tags":["reference"],"summary":"Agricultural seasons by zone, e.g. 2025/26 Masika and 2025 Vuli in bimodal zones, 2025/26\nUnimodal elsewhere, plus the irrigated dry season.","operationId":"list_seasons","parameters":[{"name":"zone","in":"query","description":"Agro-ecological zone code, e.g. `lake_victoria_bimodal`.","required":false,"schema":{"type":"string"}},{"name":"agricultural_year","in":"query","description":"e.g. `2025/26`.","required":false,"schema":{"type":"string"}},{"name":"season_code","in":"query","description":"`unimodal`, `masika`, `vuli` or `dry_irrigated`.","required":false,"schema":{"type":"string"}},{"name":"on","in":"query","description":"Seasons whose window contains this date (YYYY-MM-DD).","required":false,"schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of seasons in time order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeasonPage"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["reference:read"]}]}},"/v1/reference/units":{"get":{"tags":["reference"],"summary":"Units, local units and their conversion factors.","operationId":"list_units","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of units","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnitPage"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["reference:read"]}]}},"/v1/reference/zones":{"get":{"tags":["reference"],"summary":"Agro-ecological zones.","operationId":"list_zones","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of zones","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ZonePage"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["reference:read"]}]}},"/v1/sales/{sale_id}":{"get":{"tags":["finance"],"summary":"A sale with its flags.","operationId":"get_sale","parameters":[{"name":"sale_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The sale","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaleView"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not found (or outside your areas)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["finance:read"]}]}},"/v1/tiles/farms/{z}/{x}/{y}.mvt":{"get":{"tags":["maps"],"summary":"Plots as a Mapbox vector tile (layer `farms`): centres below zoom 12, boundaries from 12.\nOnly plots in your areas.","operationId":"farms_tile","parameters":[{"name":"z","in":"path","required":true,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"x","in":"path","required":true,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"y","in":"path","required":true,"schema":{"type":"integer","format":"int32","minimum":0}}],"responses":{"200":{"description":"Tile","content":{"application/vnd.mapbox-vector-tile":{"schema":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}}}}},"204":{"description":"No plots in the tile"},"400":{"description":"Invalid tile address","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Outside the zoom level's grid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["farms:read"]}]}},"/v1/tiles/{layer}/{z}/{x}/{y}.mvt":{"get":{"tags":["maps"],"summary":"A Mapbox Vector Tile. Layer `admin_areas`: regions below zoom 6, districts 6–8, wards from 9;\nproperties `id`, `code`, `name`, `level`. Empty (204) where there is nothing.","operationId":"tile","parameters":[{"name":"layer","in":"path","description":"`admin_areas`","required":true,"schema":{"type":"string"}},{"name":"z","in":"path","required":true,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"x","in":"path","required":true,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"y","in":"path","required":true,"schema":{"type":"integer","format":"int32","minimum":0}}],"responses":{"200":{"description":"The tile","content":{"application/vnd.mapbox-vector-tile":{"schema":{"type":"array","items":{"type":"integer","format":"int32","minimum":0}}}}},"204":{"description":"Nothing in this tile"},"400":{"description":"Invalid z/x/y","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Unknown layer","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["reference:read"]}]}},"/v1/{subject}/{subject_id}/claims":{"get":{"tags":["provenance"],"summary":"Every claim about a subject, including superseded and rejected ones.","operationId":"list_claims","parameters":[{"name":"subject","in":"path","description":"farmers, households, farms, plots, crop-cycles, perennial-stands, sales, expenses, loans or documents","required":true,"schema":{"type":"string"}},{"name":"subject_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"attribute","in":"query","description":"Only this attribute, e.g. `farm.area_ha`.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The claims","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimList"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Unknown subject type","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["claims:read"]}]}},"/v1/{subject}/{subject_id}/history":{"get":{"tags":["provenance"],"summary":"What Mela knew about a subject at a moment: each attribute's selected claim, using the\nclaims recorded by then and the status each had then.","operationId":"history","parameters":[{"name":"subject","in":"path","description":"farmers, households, farms, plots, crop-cycles, perennial-stands, sales, expenses, loans or documents","required":true,"schema":{"type":"string"}},{"name":"subject_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"at","in":"query","description":"The moment to reconstruct (RFC 3339). Defaults to now.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"attribute","in":"query","description":"Only this attribute.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Values at the moment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/History"}}}},"400":{"description":"Invalid `at`","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"401":{"description":"Not authenticated","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"403":{"description":"Missing the required permission","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Unknown subject type","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearer":["claims:read"]}]}}},"components":{"schemas":{"AccountStatus":{"type":"string","enum":["active","disabled"]},"AdminAreaPage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AdminAreaSummary"}},"next_cursor":{"type":["string","null"]}}},"AdminAreaSummary":{"type":"object","required":["id","code","name","level","label_point","area_ha"],"properties":{"area_ha":{"type":"string"},"code":{"type":"string"},"district_id":{"type":["string","null"],"format":"uuid"},"id":{"type":"string","format":"uuid"},"label_point":{"type":"array","items":{"type":"number","format":"double"},"description":"`[longitude, latitude]` of a point inside the area."},"level":{"type":"integer","format":"int32","description":"1 region, 2 district/council, 3 ward."},"name":{"type":"string"},"parent_id":{"type":["string","null"],"format":"uuid"},"region_id":{"type":["string","null"],"format":"uuid"}}},"ApiClientPage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ApiClientView"}},"next_cursor":{"type":["string","null"]}}},"ApiClientSecret":{"type":"object","description":"A client with its secret. The secret is shown only in this response.","required":["client","client_secret"],"properties":{"client":{"$ref":"#/components/schemas/ApiClientView"},"client_secret":{"type":"string"}}},"ApiClientUpdate":{"type":"object","properties":{"description":{"type":["string","null"]},"name":{"type":["string","null"]},"scopes":{"type":["array","null"],"items":{"type":"string"}},"status":{"oneOf":[{"$ref":"#/components/schemas/AccountStatus"},{"type":"null"}]}}},"ApiClientView":{"type":"object","required":["id","client_id","name","scopes","status","created_at","updated_at"],"properties":{"client_id":{"type":"string","description":"Public identifier used at the token endpoint."},"created_at":{"type":"string","format":"date-time"},"description":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"last_used_at":{"type":["string","null"],"format":"date-time"},"name":{"type":"string"},"previous_secret_expires_at":{"type":["string","null"],"format":"date-time","description":"Until then the secret before the last rotation still works."},"scopes":{"type":"array","items":{"type":"string"}},"secret_rotated_at":{"type":["string","null"],"format":"date-time"},"status":{"$ref":"#/components/schemas/AccountStatus"},"updated_at":{"type":"string","format":"date-time"}}},"AreaRef":{"type":"object","description":"A named area, as returned with a resolution.","required":["id","code","name"],"properties":{"code":{"type":"string"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"AreaUnit":{"type":"string","enum":["ha","acre","m2"]},"AreaView":{"type":"object","description":"An admin area with its code and name.","required":["id","code","name"],"properties":{"code":{"type":"string"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"AttributeValue":{"type":"object","description":"The value of one attribute as known at a moment.","required":["attribute","value","claim_id","status","confidence_level","observed_at","selection"],"properties":{"attribute":{"type":"string"},"claim_id":{"type":"string","format":"uuid"},"confidence_level":{"type":"integer","format":"int32"},"observed_at":{"type":"string","format":"date-time"},"selection":{"type":"string","description":"How the claim was chosen among competing ones."},"status":{"$ref":"#/components/schemas/ClaimStatus","description":"The claim's status at that moment."},"value":{"type":"object"}}},"Birth":{"oneOf":[{"type":"object","required":["date","kind"],"properties":{"date":{"type":"string","format":"date"},"kind":{"type":"string","enum":["date"]}}},{"type":"object","required":["year","kind"],"properties":{"kind":{"type":"string","enum":["estimated_year"]},"year":{"type":"integer","format":"int32"}}}],"description":"Date of birth, or only an estimated birth year (common: many farmers know their age, not\nthe date)."},"Buyer":{"type":"object","required":["id","name","buyer_type"],"properties":{"buyer_type":{"$ref":"#/components/schemas/BuyerType"},"district_id":{"type":["string","null"],"format":"uuid"},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"region_id":{"type":["string","null"],"format":"uuid"}}},"BuyerList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Buyer"}}}},"BuyerType":{"type":"string","enum":["amcos_cooperative","local_trader","offtaker_company","warehouse_receipt_system","processor","market","exporter","other"]},"CalendarEntry":{"type":"object","required":["zone_code","crop_code","season_code","season_name","plant_start_month","plant_end_month","harvest_start_month","harvest_end_month","status","source_id"],"properties":{"crop_code":{"type":"string"},"harvest_end_month":{"type":"integer","format":"int32"},"harvest_start_month":{"type":"integer","format":"int32"},"plant_end_month":{"type":"integer","format":"int32"},"plant_start_month":{"type":"integer","format":"int32","description":"Months 1–12; a window may wrap past December (11 → 1)."},"season_code":{"type":"string","description":"`unimodal`, `masika`, `vuli` or `dry_irrigated`."},"season_name":{"type":"string"},"source_id":{"type":"string"},"status":{"type":"string","description":"`indicative` until reviewed by the agronomy team."},"zone_code":{"type":"string"}}},"CalendarPage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CalendarEntry"}},"next_cursor":{"type":["string","null"]}}},"Capture":{"type":"object","description":"How the data was captured; becomes the provenance source.","properties":{"accuracy_m":{"type":["number","null"],"format":"double"},"captured_at":{"type":["string","null"],"format":"date-time","description":"Device time of capture (offline work syncs later)."},"device_id":{"type":["string","null"]},"form_version":{"type":["string","null"]},"has_photo":{"type":"boolean","description":"A photo was taken with the capture (e.g. of the farmer or the ID card)."},"lat":{"type":["number","null"],"format":"double"},"lon":{"type":["number","null"],"format":"double","description":"Where the capture happened (WGS84)."}}},"CaptureMethod":{"type":"string","description":"How the plot geometry was captured.","enum":["point","walked","drawn","imported"]},"Channel":{"type":"string","description":"How a registration reached Mela.","enum":["field_app","admin_ui","partner_api","import","ussd"]},"CheckCode":{"type":"string","description":"Codes of the plot checks (`farms.plot_checks`).","enum":["geometry_repaired","too_small","too_large","overlap","water","protected_area","area_discrepancy","outside_admin_area"]},"CheckList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CheckView"}}}},"CheckView":{"type":"object","description":"One current or past check result.","required":["id","plot_id","geometry_version","code","outcome","message","details","checked_at"],"properties":{"checked_at":{"type":"string","format":"date-time"},"code":{"$ref":"#/components/schemas/CheckCode"},"details":{"type":"object"},"geometry_version":{"type":"integer","format":"int32"},"id":{"type":"string","format":"uuid"},"message":{"type":"string"},"other_plot_id":{"type":["string","null"],"format":"uuid"},"outcome":{"type":"string","description":"`warn` (review) or `fail`."},"plot_id":{"type":"string","format":"uuid"},"superseded_at":{"type":["string","null"],"format":"date-time"},"zone_id":{"type":["string","null"],"format":"uuid"}}},"ClaimDetail":{"allOf":[{"type":"object","required":["id","subject_type","subject_id","attribute","value","status","confidence_level","observed_at","recorded_at","source_id","source_kind","source_channel","data_origin"],"properties":{"attribute":{"type":"string"},"confidence":{"type":["number","null"],"format":"double"},"confidence_level":{"type":"integer","format":"int32","description":"0–3 (C0–C3)."},"data_origin":{"type":"string","description":"`real` or `synthetic`."},"id":{"type":"string","format":"uuid"},"observed_at":{"type":"string","format":"date-time"},"recorded_at":{"type":"string","format":"date-time"},"source_channel":{"type":"string"},"source_id":{"type":"string","format":"uuid"},"source_kind":{"$ref":"#/components/schemas/SourceKind"},"status":{"$ref":"#/components/schemas/ClaimStatus"},"subject_id":{"type":"string","format":"uuid"},"subject_type":{"type":"string"},"supersedes_claim_id":{"type":["string","null"],"format":"uuid"},"value":{"type":"object"}}},{"type":"object","required":["source","evidence","status_history"],"properties":{"evidence":{"type":"array","items":{"$ref":"#/components/schemas/EvidenceLink"}},"source":{"$ref":"#/components/schemas/SourceView"},"status_history":{"type":"array","items":{"$ref":"#/components/schemas/StatusChange"}}}}],"description":"One claim with its source, evidence (current and detached) and status history."},"ClaimList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ClaimView"},"description":"Grouped by attribute, newest first."}}},"ClaimStatus":{"type":"string","description":"Where a claim stands.","enum":["reported","pending_verification","verified","partially_verified","disputed","rejected","expired","superseded"]},"ClaimView":{"type":"object","required":["id","subject_type","subject_id","attribute","value","status","confidence_level","observed_at","recorded_at","source_id","source_kind","source_channel","data_origin"],"properties":{"attribute":{"type":"string"},"confidence":{"type":["number","null"],"format":"double"},"confidence_level":{"type":"integer","format":"int32","description":"0–3 (C0–C3)."},"data_origin":{"type":"string","description":"`real` or `synthetic`."},"id":{"type":"string","format":"uuid"},"observed_at":{"type":"string","format":"date-time"},"recorded_at":{"type":"string","format":"date-time"},"source_channel":{"type":"string"},"source_id":{"type":"string","format":"uuid"},"source_kind":{"$ref":"#/components/schemas/SourceKind"},"status":{"$ref":"#/components/schemas/ClaimStatus"},"subject_id":{"type":"string","format":"uuid"},"subject_type":{"type":"string"},"supersedes_claim_id":{"type":["string","null"],"format":"uuid"},"value":{"type":"object"}}},"ClientTokenResponse":{"type":"object","required":["access_token","token_type","expires_in","scope"],"properties":{"access_token":{"type":"string"},"expires_in":{"type":"integer","format":"int64","minimum":0},"scope":{"type":"string","example":"farmers:read"},"token_type":{"type":"string","example":"Bearer"}}},"Collateral":{"type":"string","enum":["none","land_title","ccro","group_guarantee","crop_lien","warehouse_receipt","asset","salary","other"]},"ConfidenceLevel":{"type":"string","description":"Confidence levels (docs/domains/provenance.md has examples per attribute type).","enum":["C0","C1","C2","C3"]},"ConsentList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ConsentView"}}}},"ConsentStatus":{"type":"string","enum":["active","expired","revoked"]},"ConsentView":{"type":"object","required":["id","farmer_id","grantee_type","purposes","scopes","channel","language","text_version","valid_from","status","created_at"],"properties":{"channel":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"evidence_document_id":{"type":["string","null"],"format":"uuid"},"farmer_id":{"type":"string","format":"uuid"},"grantee_category":{"type":["string","null"]},"grantee_id":{"type":["string","null"],"format":"uuid"},"grantee_type":{"$ref":"#/components/schemas/GranteeType"},"id":{"type":"string","format":"uuid"},"language":{"type":"string"},"purposes":{"type":"array","items":{"type":"string"}},"revoked_at":{"type":["string","null"],"format":"date-time"},"revoked_reason":{"type":["string","null"]},"scopes":{"type":"array","items":{"type":"string"}},"status":{"$ref":"#/components/schemas/ConsentStatus"},"text_version":{"type":"string"},"valid_from":{"type":"string","format":"date-time"},"valid_to":{"type":["string","null"],"format":"date-time"},"witness_id":{"type":["string","null"],"format":"uuid"}}},"CostInput":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number","format":"double"},"currency":{"type":["string","null"],"description":"ISO 4217; defaults to TZS."}}},"Created":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid"}}},"CreatedUser":{"type":"object","required":["user","password_setup"],"properties":{"password_setup":{"$ref":"#/components/schemas/PasswordSetup"},"user":{"$ref":"#/components/schemas/UserView"}}},"Crop":{"allOf":[{"type":"object","description":"A name in the caller's language, with both kept.","required":["name","name_en","name_sw"],"properties":{"name":{"type":"string","description":"In the request's language (`Accept-Language: sw|en`)."},"name_en":{"type":"string"},"name_sw":{"type":"string"}}},{"type":"object","required":["code","category","lifecycle","scientific_name","varieties","source_id"],"properties":{"category":{"type":"string"},"code":{"type":"string"},"lifecycle":{"type":"string","description":"`annual` or `perennial`."},"scientific_name":{"type":"string"},"source_id":{"type":"string"},"varieties":{"type":"array","items":{"$ref":"#/components/schemas/Variety"}}}}]},"CropCycleDetail":{"allOf":[{"$ref":"#/components/schemas/CropCycleView"},{"type":"object","required":["inputs","harvests","losses","flags"],"properties":{"flags":{"type":"array","items":{"$ref":"#/components/schemas/FlagView"}},"harvests":{"type":"array","items":{"$ref":"#/components/schemas/HarvestView"}},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/InputView"}},"losses":{"type":"array","items":{"$ref":"#/components/schemas/LossView"}}}}],"description":"A crop cycle with everything recorded on it."},"CropCycleList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CropCycleView"}}}},"CropCycleView":{"type":"object","required":["id","plot_id","farm_id","farmer_id","season","zone_code","crop_code","status","irrigation","mechanized","conservation_agriculture","harvested_kg","loss_kg","input_cost_tzs","fertilizer_kg","flag_count","data_origin","version","created_at","updated_at"],"properties":{"conservation_agriculture":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"crop_code":{"type":"string"},"data_origin":{"type":"string"},"end_reason":{"type":["string","null"]},"ended_on":{"type":["string","null"],"format":"date"},"farm_id":{"type":"string","format":"uuid"},"farmer_id":{"type":"string","format":"uuid"},"fertilizer_kg":{"type":"number","format":"double"},"flag_count":{"type":"integer","format":"int32"},"harvested_kg":{"type":"number","format":"double"},"id":{"type":"string","format":"uuid"},"input_cost_tzs":{"type":"number","format":"double"},"intercrop_group":{"type":["string","null"],"format":"uuid","description":"Shared by the cycles intercropped on the plot this season."},"irrigation":{"$ref":"#/components/schemas/Irrigation"},"loss_kg":{"type":"number","format":"double"},"mechanized":{"type":"boolean"},"planted_area_ha":{"type":["number","null"],"format":"double"},"planted_area_source":{"type":["string","null"],"description":"`reported`, `plot_measured` or `plot_reported`."},"planted_area_unit":{"type":["string","null"]},"planted_area_value":{"type":["number","null"],"format":"double"},"planting_date":{"type":["string","null"],"format":"date"},"plot_area_ha":{"type":["number","null"],"format":"double"},"plot_id":{"type":"string","format":"uuid"},"season":{"$ref":"#/components/schemas/SeasonRef"},"stand_id":{"type":["string","null"],"format":"uuid","description":"The perennial stand this cycle's harvest comes from."},"status":{"$ref":"#/components/schemas/CycleStatus"},"updated_at":{"type":"string","format":"date-time"},"variety_code":{"type":["string","null"]},"version":{"type":"integer","format":"int32","description":"Send it back as `expected_version` to change the status safely."},"yield_kg_ha":{"type":["number","null"],"format":"double"},"zone_code":{"type":"string"}}},"CropFactor":{"type":"object","required":["crop_code","factor","status"],"properties":{"crop_code":{"type":"string"},"factor":{"type":"string"},"status":{"type":"string"}}},"CropHistory":{"type":"object","description":"One crop across all seasons.","required":["crop_code","seasons","harvested_kg","failed_cycles"],"properties":{"crop_code":{"type":"string"},"failed_cycles":{"type":"integer","format":"int32"},"harvested_kg":{"type":"number","format":"double"},"mean_yield_index":{"type":["number","null"],"format":"double"},"mean_yield_kg_ha":{"type":["number","null"],"format":"double"},"seasons":{"type":"integer","minimum":0}}},"CropPage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Crop"}},"next_cursor":{"type":["string","null"]}}},"CropRevenue":{"type":"object","required":["crop_code","sold_kg","revenue_tzs","mean_price_per_kg"],"properties":{"crop_code":{"type":"string"},"mean_price_per_kg":{"type":"number","format":"double","description":"Revenue over quantity, TZS per kg."},"revenue_tzs":{"type":"number","format":"double"},"sold_kg":{"type":"number","format":"double"}}},"CycleStatus":{"type":"string","description":"`planned → planted → growing → harvested | failed | abandoned`.","enum":["planned","planted","growing","harvested","failed","abandoned"]},"DataScope":{"type":"string","description":"What data the consent covers.","enum":["identity_basic","identity_documents","contact","farm_location","farm_boundary","production_history","market_income","financial_history","risk_environmental","intelligence_scores","verification_status","documents"]},"Detail":{"type":"string","enum":["simplified","full"]},"Dismissal":{"type":"object","properties":{"note":{"type":["string","null"]}}},"DuplicateCandidate":{"type":"object","description":"A pair in the review queue.","required":["id","outcome","score","name_score","reasons","status","detected_at","farmer_a","farmer_b"],"properties":{"detected_at":{"type":"string","format":"date-time"},"farmer_a":{"$ref":"#/components/schemas/FarmerSummary"},"farmer_b":{"$ref":"#/components/schemas/FarmerSummary"},"id":{"type":"string","format":"uuid"},"name_score":{"type":"number","format":"double","description":"Name similarity, 0–1."},"outcome":{"$ref":"#/components/schemas/Outcome"},"reasons":{"type":"array","items":{"type":"string"},"description":"`same_identifier`, `same_phone`, `similar_name`, `same_birth_year`, `same_ward`."},"review_note":{"type":["string","null"]},"reviewed_at":{"type":["string","null"],"format":"date-time"},"reviewed_by":{"type":["string","null"],"format":"uuid"},"score":{"type":"number","format":"double","description":"0–1."},"status":{"type":"string","description":"`open`, `dismissed` or `merged`."}}},"DuplicatePage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DuplicateCandidate"}},"next_cursor":{"type":["string","null"]}}},"Education":{"type":"string","enum":["none","primary","secondary","vocational","tertiary"]},"EventPage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/EventView"}},"next_cursor":{"type":["string","null"]}}},"EventView":{"type":"object","description":"An event as returned to readers of the log.","required":["id","occurred_at","action","outcome","details"],"properties":{"action":{"type":"string"},"actor_id":{"type":["string","null"],"format":"uuid"},"actor_kind":{"type":["string","null"]},"after_hash":{"type":["string","null"]},"before_hash":{"type":["string","null"],"description":"Hex SHA-256 of the resource state before the change."},"details":{"type":"object"},"id":{"type":"string","format":"uuid"},"ip":{"type":["string","null"]},"occurred_at":{"type":"string","format":"date-time"},"outcome":{"type":"string"},"reason":{"type":["string","null"]},"request_id":{"type":["string","null"]},"resource_id":{"type":["string","null"]},"resource_type":{"type":["string","null"]},"user_agent":{"type":["string","null"]}}},"EvidenceLink":{"type":"object","required":["id","evidence_type","evidence_id","linked_at"],"properties":{"evidence_id":{"type":"string"},"evidence_type":{"$ref":"#/components/schemas/EvidenceType"},"id":{"type":"string","format":"uuid"},"linked_at":{"type":"string","format":"date-time"},"linked_by":{"type":["string","null"],"format":"uuid"},"note":{"type":["string","null"]},"unlink_reason":{"type":["string","null"]},"unlinked_at":{"type":["string","null"],"format":"date-time"},"unlinked_by":{"type":["string","null"],"format":"uuid"}}},"EvidenceType":{"type":"string","enum":["document","photo","field_visit","external_observation","partner_record","claim"]},"ExpenseCategory":{"type":"string","enum":["labour","land_rent","transport","storage","inputs","mechanization","irrigation","processing","market_fees","other"]},"ExpenseList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ExpenseView"}}}},"ExpenseView":{"type":"object","required":["id","farmer_id","season_id","category","amount","currency","incurred_on","created_at"],"properties":{"amount":{"type":"string"},"category":{"$ref":"#/components/schemas/ExpenseCategory"},"created_at":{"type":"string","format":"date-time"},"crop_cycle_id":{"type":["string","null"],"format":"uuid"},"currency":{"type":"string"},"description":{"type":["string","null"]},"farmer_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"incurred_on":{"type":"string","format":"date"},"input_application_id":{"type":["string","null"],"format":"uuid"},"season_id":{"type":"string","format":"uuid"}}},"FarmCollection":{"type":"object","description":"A farm and its plots as a GeoJSON FeatureCollection; `farm` is a foreign member.","required":["type","farm","features"],"properties":{"farm":{"$ref":"#/components/schemas/FarmSummary"},"features":{"type":"array","items":{"$ref":"#/components/schemas/PlotFeature"}},"type":{"type":"string","example":"FeatureCollection"}}},"FarmList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FarmSummary"}}}},"FarmPage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FarmSummary"}},"next_cursor":{"type":["string","null"]}}},"FarmSummary":{"type":"object","description":"A farm without its geometry.","required":["id","farmer_id","status","plot_count","data_origin","version","created_at","updated_at"],"properties":{"centroid":{"type":["array","null"],"items":{"type":"number","format":"double"},"description":"`[longitude, latitude]` of the plots' centre."},"created_at":{"type":"string","format":"date-time"},"data_origin":{"type":"string"},"district_id":{"type":["string","null"],"format":"uuid"},"farmer_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"measured_area_ha":{"type":["number","null"],"format":"double","description":"Sum of the plots' measured areas."},"name":{"type":["string","null"]},"plot_count":{"type":"integer","format":"int64"},"region_id":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","description":"`active` or `inactive`."},"updated_at":{"type":"string","format":"date-time"},"version":{"type":"integer","format":"int32"},"ward_id":{"type":["string","null"],"format":"uuid"}}},"FarmerDetail":{"type":"object","description":"The full farmer record.","required":["id","mela_id","given_name","full_name","languages","status","has_home_point","identifiers","phones","registrations","data_origin","version","created_at","updated_at"],"properties":{"birth_date":{"type":["string","null"],"format":"date"},"birth_year":{"type":["integer","null"],"format":"int32","description":"Exact (from `birth_date`) or estimated."},"created_at":{"type":"string","format":"date-time"},"data_origin":{"type":"string","description":"`real` or `synthetic`."},"district":{"oneOf":[{"$ref":"#/components/schemas/AreaView"},{"type":"null"}]},"education":{"type":["string","null"]},"family_name":{"type":["string","null"]},"full_name":{"type":"string"},"given_name":{"type":"string"},"has_home_point":{"type":"boolean","description":"A precise home point is on file (Restricted; not returned)."},"household":{"oneOf":[{"$ref":"#/components/schemas/HouseholdView"},{"type":"null"}]},"id":{"type":"string","format":"uuid"},"identifiers":{"type":"array","items":{"$ref":"#/components/schemas/IdentifierView"}},"known_as":{"type":["string","null"]},"languages":{"type":"array","items":{"type":"string"}},"mela_id":{"type":"string","example":"MLA-TZ-7K3F-9Q2D"},"merged_into_id":{"type":["string","null"],"format":"uuid","description":"Set when merged: read that record instead."},"middle_name":{"type":["string","null"]},"phones":{"type":"array","items":{"$ref":"#/components/schemas/PhoneView"}},"region":{"oneOf":[{"$ref":"#/components/schemas/AreaView"},{"type":"null"}]},"registrations":{"type":"array","items":{"$ref":"#/components/schemas/RegistrationView"}},"sex":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/FarmerStatus"},"updated_at":{"type":"string","format":"date-time"},"version":{"type":"integer","format":"int32","description":"Send it back as `expected_version` to update safely."},"village":{"type":["string","null"]},"ward":{"oneOf":[{"$ref":"#/components/schemas/AreaView"},{"type":"null"}]}}},"FarmerPage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FarmerSummary"}},"next_cursor":{"type":["string","null"]}}},"FarmerStatus":{"type":"string","description":"Where a farmer record stands.","enum":["draft","registered","active","inactive","deceased","merged","withdrawn"]},"FarmerSummary":{"type":"object","description":"One row of a list, search or lookup.","required":["id","mela_id","full_name","status"],"properties":{"birth_year":{"type":["integer","null"],"format":"int32"},"district_id":{"type":["string","null"],"format":"uuid"},"full_name":{"type":"string"},"id":{"type":"string","format":"uuid"},"mela_id":{"type":"string"},"merged_into_id":{"type":["string","null"],"format":"uuid"},"rank":{"type":["number","null"],"format":"double","description":"Name match strength (0–1) when searching by name."},"region_id":{"type":["string","null"],"format":"uuid"},"sex":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/FarmerStatus"},"village":{"type":["string","null"]},"ward_id":{"type":["string","null"],"format":"uuid"}}},"FinancialHistory":{"type":"object","description":"Restricted-PII: financing, repayments, savings, mobile money and indicators.","required":["farmer_id","loans","savings","mobile_money","indicators"],"properties":{"farmer_id":{"type":"string","format":"uuid"},"indicators":{"$ref":"#/components/schemas/Indicators"},"loans":{"type":"array","items":{"$ref":"#/components/schemas/LoanView"}},"mobile_money":{"type":"array","items":{"$ref":"#/components/schemas/MobileMoneyView"}},"savings":{"type":"array","items":{"$ref":"#/components/schemas/SavingsView"}}}},"FinancingStatusChange":{"type":"object","required":["status"],"properties":{"expected_version":{"type":["integer","null"],"format":"int32"},"on":{"type":["string","null"],"format":"date"},"status":{"$ref":"#/components/schemas/LoanStatus"}}},"FlagCode":{"type":"string","description":"Codes of the plausibility flags (`agriculture.cycle_flags`).","enum":["yield_above_p99","yield_below_p1","harvest_before_planting","planting_outside_window","harvest_outside_window","planted_area_exceeds_plot"]},"FlagView":{"type":"object","description":"A current flag, as the API shows it.","required":["code","outcome","message","details","checked_at"],"properties":{"checked_at":{"type":"string","format":"date-time"},"code":{"$ref":"#/components/schemas/FlagCode"},"details":{"type":"object"},"message":{"type":"string"},"outcome":{"type":"string","description":"`warn` or `fail`."}}},"GeometryChange":{"type":"object","required":["geometry","capture_method"],"properties":{"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]},"capture_method":{"$ref":"#/components/schemas/CaptureMethod"},"expected_version":{"type":["integer","null"],"format":"int32","description":"The plot `version` you read."},"geometry":{"type":"object"},"gps_accuracy_m":{"type":["number","null"],"format":"double"}}},"GranteeType":{"type":"string","enum":["mela","partner","partner_category"]},"GroupRole":{"type":"string","enum":["member","chair","secretary","treasurer","other"]},"GroupType":{"type":"string","enum":["vicoba","vsla","sacco","chama","other"]},"HarvestView":{"type":"object","required":["id","harvested_on","quantity_kg","original_value","original_unit","quality_grade","is_final","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"harvest_end_on":{"type":["string","null"],"format":"date"},"harvested_on":{"type":"string","format":"date"},"id":{"type":"string","format":"uuid"},"is_final":{"type":"boolean"},"original_unit":{"type":"string"},"original_value":{"type":"number","format":"double"},"quality_grade":{"$ref":"#/components/schemas/QualityGrade"},"quantity_kg":{"type":"number","format":"double"}}},"History":{"type":"object","required":["at","values"],"properties":{"at":{"type":"string","format":"date-time"},"values":{"type":"array","items":{"$ref":"#/components/schemas/AttributeValue"},"description":"The current value of each attribute as known at `at`."}}},"HouseholdInput":{"type":"object","required":["size","is_head","female_headed"],"properties":{"dependants":{"type":["integer","null"],"format":"int32"},"female_headed":{"type":"boolean"},"is_head":{"type":"boolean","description":"The farmer heads the household."},"size":{"type":"integer","format":"int32","description":"People living in the household, the farmer included."}}},"HouseholdView":{"type":"object","required":["id","size","is_head","female_headed","updated_at"],"properties":{"dependants":{"type":["integer","null"],"format":"int32"},"female_headed":{"type":"boolean"},"id":{"type":"string","format":"uuid"},"is_head":{"type":"boolean"},"size":{"type":"integer","format":"int32"},"updated_at":{"type":"string","format":"date-time"}}},"IdKind":{"type":"string","enum":["nin","zan_id","voter_id","driving_licence","passport"]},"IdentifierInput":{"type":"object","required":["kind","number"],"properties":{"kind":{"$ref":"#/components/schemas/IdKind"},"number":{"type":"string","description":"As written on the document; separators are ignored."}}},"IdentifierView":{"type":"object","required":["id","kind","issuing_country","verification_status","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"issuing_country":{"type":"string"},"kind":{"$ref":"#/components/schemas/IdKind"},"masked":{"type":"string","description":"Last three characters only, e.g. `•••••••••••••••••112`."},"verification_status":{"type":"string","description":"`unverified`, `verified` or `rejected`."}}},"IdentityUpdate":{"type":"object","description":"Fields present are changed; a blank middle name or `known_as` clears it.","properties":{"birth":{"oneOf":[{"$ref":"#/components/schemas/Birth"},{"type":"null"}]},"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]},"education":{"oneOf":[{"$ref":"#/components/schemas/Education"},{"type":"null"}]},"expected_version":{"type":["integer","null"],"format":"int32","description":"The `version` you read; the update is refused if the record changed since."},"family_name":{"type":["string","null"]},"given_name":{"type":["string","null"]},"known_as":{"type":["string","null"]},"languages":{"type":["array","null"],"items":{"type":"string"}},"middle_name":{"type":["string","null"]},"sex":{"oneOf":[{"$ref":"#/components/schemas/Sex"},{"type":"null"}]}}},"IncomeSummary":{"type":"object","description":"Agricultural income, newest season first (TZS).","required":["farmer_id","years","seasons","crops"],"properties":{"crops":{"type":"array","items":{"$ref":"#/components/schemas/CropRevenue"}},"farmer_id":{"type":"string","format":"uuid"},"seasons":{"type":"array","items":{"$ref":"#/components/schemas/SeasonIncome"},"description":"Per season, for sales and expenses tied to one; newest first."},"years":{"type":"array","items":{"$ref":"#/components/schemas/YearIncome"},"description":"Per agricultural year (October–September), oldest first: all sales and expenses."}}},"Indicators":{"type":"object","description":"Indicators at `as_of` (TZS).","required":["as_of","income","cash_flow","repayment","outstanding_tzs"],"properties":{"annual_income_tzs":{"type":["number","null"],"format":"double","description":"Net agricultural income of the latest full agricultural year."},"as_of":{"type":"string","format":"date-time"},"cash_flow":{"type":"array","items":{"$ref":"#/components/schemas/MonthFlow"},"description":"Average inflow (sales) and outflow (expenses, repayments) by calendar month."},"debt_to_income":{"type":["number","null"],"format":"double"},"income":{"type":"array","items":{"$ref":"#/components/schemas/YearIncome"}},"mobile_money_mean_inflow_tzs":{"type":["number","null"],"format":"double","description":"Mean monthly mobile-money inflow over the last 6 recorded months."},"outstanding_tzs":{"type":"number","format":"double"},"repayment":{"$ref":"#/components/schemas/RepaymentBehaviour"}}},"Input":{"allOf":[{"type":"object","description":"A name in the caller's language, with both kept.","required":["name","name_en","name_sw"],"properties":{"name":{"type":"string","description":"In the request's language (`Accept-Language: sw|en`)."},"name_en":{"type":"string"},"name_sw":{"type":"string"}}},{"type":"object","required":["code","category"],"properties":{"category":{"type":"string","description":"`fertilizer`, `organic_fertilizer`, `seed` or `agrochemical`."},"code":{"type":"string"},"notes":{"type":["string","null"]},"nutrients":{"type":["string","null"],"description":"N-P-K, e.g. `18-46-0`."}}}]},"InputPage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Input"}},"next_cursor":{"type":["string","null"]}}},"InputSource":{"type":"string","description":"How the farmer got an input.","enum":["purchase","subsidy","credit","own","gift","other"]},"InputView":{"type":"object","required":["id","input_code","input_category","quantity","quantity_unit","original_value","original_unit","applied_on","source","created_at"],"properties":{"applied_on":{"type":"string","format":"date"},"cost_amount":{"type":["string","null"]},"cost_currency":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"input_category":{"type":"string"},"input_code":{"type":"string"},"original_unit":{"type":"string"},"original_value":{"type":"number","format":"double","description":"As the farmer gave it, e.g. 2 `gunia_50kg`."},"product":{"type":["string","null"]},"quantity":{"type":"number","format":"double","description":"In `quantity_unit` (`kilogram`, `litre` or `count`)."},"quantity_unit":{"type":"string"},"receipt_document_id":{"type":["string","null"],"format":"uuid"},"source":{"$ref":"#/components/schemas/InputSource"}}},"InstalmentInput":{"type":"object","required":["due_on","due_amount"],"properties":{"due_amount":{"type":"number","format":"double"},"due_on":{"type":"string","format":"date"},"paid_amount":{"type":"number","format":"double"},"paid_on":{"type":["string","null"],"format":"date"}}},"Irrigation":{"type":"string","enum":["rainfed","supplementary","full"]},"LandUse":{"type":"string","enum":["cropland","pasture","fallow","perennial","mixed"]},"LenderType":{"type":"string","enum":["bank","mfi","sacco","vicoba_vsla","input_credit","offtaker_advance","informal_lender","family"]},"Live":{"type":"object","required":["status"],"properties":{"status":{"type":"string","example":"live"}}},"LoanPurpose":{"type":"string","enum":["inputs","equipment","land","livestock","labour","school_fees","health","household","business","other"]},"LoanStatus":{"type":"string","enum":["active","repaid","defaulted","written_off","restructured"]},"LoanView":{"type":"object","required":["id","farmer_id","lender_type","purpose","principal","currency","disbursed_on","collateral_type","status","repayments","version","created_at"],"properties":{"collateral_type":{"$ref":"#/components/schemas/Collateral"},"created_at":{"type":"string","format":"date-time"},"currency":{"type":"string"},"disbursed_on":{"type":"string","format":"date"},"farmer_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"interest_rate_pct":{"type":["number","null"],"format":"double"},"lender_name":{"type":["string","null"]},"lender_type":{"$ref":"#/components/schemas/LenderType"},"maturity_on":{"type":["string","null"],"format":"date"},"principal":{"type":"string"},"purpose":{"$ref":"#/components/schemas/LoanPurpose"},"repayments":{"type":"array","items":{"$ref":"#/components/schemas/RepaymentView"}},"status":{"$ref":"#/components/schemas/LoanStatus"},"status_on":{"type":["string","null"],"format":"date"},"tenor_months":{"type":["integer","null"],"format":"int32"},"version":{"type":"integer","format":"int32","description":"Send it back as `expected_version` to change the status safely."}}},"LocationInput":{"type":"object","properties":{"lat":{"type":["number","null"],"format":"double"},"lon":{"type":["number","null"],"format":"double","description":"Home GPS point (Restricted); resolves the ward when `ward_id` is absent."},"village":{"type":["string","null"]},"ward_id":{"type":["string","null"],"format":"uuid","description":"The home ward; district and region are filled in."}}},"LoginRequest":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","example":"asha@mela.africa"},"password":{"type":"string"}}},"LoginResponse":{"allOf":[{"oneOf":[{"type":"object","description":"Access and refresh tokens.","required":["access_token","token_type","expires_in","refresh_token","refresh_expires_at"],"properties":{"access_token":{"type":"string"},"expires_in":{"type":"integer","format":"int64","description":"Seconds until the access token expires.","minimum":0},"refresh_expires_at":{"type":"string","format":"date-time","description":"End of the session, whatever the refreshes."},"refresh_token":{"type":"string","description":"Exchange at `POST /v1/auth/refresh`. Single use: each refresh returns a new one."},"token_type":{"type":"string","example":"Bearer"}}},{"type":"null"}]},{"type":"object","required":["status"],"properties":{"mfa_token":{"type":["string","null"],"description":"Present when `status` asks for MFA."},"mfa_token_expires_in":{"type":["integer","null"],"format":"int64","minimum":0},"status":{"$ref":"#/components/schemas/LoginStatus"}}}]},"LoginStatus":{"type":"string","enum":["authenticated","mfa_required","mfa_enrollment_required"]},"Lookup":{"type":"object","description":"Exactly one key. Sent in a POST body so numbers stay out of URLs and access logs.","properties":{"identifier":{"oneOf":[{"$ref":"#/components/schemas/LookupIdentifier"},{"type":"null"}]},"mela_id":{"type":["string","null"]},"phone":{"type":["string","null"]}}},"LookupIdentifier":{"type":"object","required":["kind","number"],"properties":{"kind":{"$ref":"#/components/schemas/IdKind"},"number":{"type":"string"}}},"LookupResult":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FarmerSummary"},"description":"Usually zero or one; several when the same number is on duplicate records."}}},"LossCause":{"type":"string","description":"Why a crop was lost (whole or in part).","enum":["drought","flood","pests","disease","fire","theft","storage","wildlife","other"]},"LossInput":{"type":"object","required":["stage","cause"],"properties":{"agent":{"type":["string","null"],"description":"The pest or disease, e.g. `fall_armyworm`."},"cause":{"$ref":"#/components/schemas/LossCause"},"occurred_on":{"type":["string","null"],"format":"date"},"quantity":{"type":["number","null"],"format":"double","description":"Quantity lost, in `unit`; or give `share`."},"share":{"type":["number","null"],"format":"double","description":"Share of the crop lost, 0–1."},"stage":{"$ref":"#/components/schemas/LossStage"},"unit":{"type":["string","null"]}}},"LossStage":{"type":"string","enum":["pre_harvest","post_harvest"]},"LossView":{"type":"object","required":["id","stage","cause"],"properties":{"agent":{"type":["string","null"]},"cause":{"$ref":"#/components/schemas/LossCause"},"harvest_id":{"type":["string","null"],"format":"uuid"},"id":{"type":"string","format":"uuid"},"occurred_on":{"type":["string","null"],"format":"date"},"quantity_kg":{"type":["number","null"],"format":"double"},"share":{"type":["number","null"],"format":"double"},"stage":{"$ref":"#/components/schemas/LossStage"}}},"Me":{"type":"object","required":["actor_id","actor_kind","permissions"],"properties":{"actor_id":{"type":"string","format":"uuid"},"actor_kind":{"type":"string","example":"staff"},"api_client":{"oneOf":[{"$ref":"#/components/schemas/ApiClientView"},{"type":"null"}]},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/MePermission"}},"user":{"oneOf":[{"$ref":"#/components/schemas/UserView"},{"type":"null"}]}}},"MePermission":{"type":"object","required":["permission"],"properties":{"area_ids":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"description":"Absent: everywhere."},"permission":{"type":"string"}}},"MergeList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MergeView"}}}},"MergeRequest":{"type":"object","required":["survivor_id","merged_id","reason"],"properties":{"candidate_id":{"type":["string","null"],"format":"uuid","description":"The reviewed candidate pair, if the merge comes from the queue."},"merged_id":{"type":"string","format":"uuid","description":"The record that becomes `merged` and points to the survivor."},"reason":{"type":"string"},"survivor_id":{"type":"string","format":"uuid","description":"The record that stays."}}},"MergeView":{"type":"object","required":["id","survivor_id","merged_id","previous_status","reason","merged_at"],"properties":{"candidate_id":{"type":["string","null"],"format":"uuid"},"id":{"type":"string","format":"uuid"},"merged_at":{"type":"string","format":"date-time"},"merged_by":{"type":["string","null"],"format":"uuid"},"merged_id":{"type":"string","format":"uuid"},"previous_status":{"type":"string","description":"Restored by an unmerge."},"reason":{"type":"string"},"survivor_id":{"type":"string","format":"uuid"},"unmerge_reason":{"type":["string","null"]},"unmerged_at":{"type":["string","null"],"format":"date-time"},"unmerged_by":{"type":["string","null"],"format":"uuid"}}},"MfaConfirmRequest":{"type":"object","required":["mfa_token","code"],"properties":{"code":{"type":"string"},"mfa_token":{"type":"string"}}},"MfaEnabledResponse":{"allOf":[{"type":"object","description":"Access and refresh tokens.","required":["access_token","token_type","expires_in","refresh_token","refresh_expires_at"],"properties":{"access_token":{"type":"string"},"expires_in":{"type":"integer","format":"int64","description":"Seconds until the access token expires.","minimum":0},"refresh_expires_at":{"type":"string","format":"date-time","description":"End of the session, whatever the refreshes."},"refresh_token":{"type":"string","description":"Exchange at `POST /v1/auth/refresh`. Single use: each refresh returns a new one."},"token_type":{"type":"string","example":"Bearer"}}},{"type":"object","required":["recovery_codes"],"properties":{"recovery_codes":{"type":"array","items":{"type":"string"},"description":"Store these safely: each works once when the authenticator is lost. Shown only now."}}}]},"MfaEnrollmentResponse":{"type":"object","required":["secret","otpauth_uri"],"properties":{"otpauth_uri":{"type":"string","description":"Render as a QR code for the authenticator app."},"secret":{"type":"string","description":"Base32 secret for manual entry."}}},"MfaTokenRequest":{"type":"object","required":["mfa_token"],"properties":{"mfa_token":{"type":"string"}}},"MfaVerifyRequest":{"type":"object","required":["mfa_token"],"properties":{"code":{"type":["string","null"],"description":"6-digit code from the authenticator app."},"mfa_token":{"type":"string"},"recovery_code":{"type":["string","null"],"description":"One of the recovery codes, when the authenticator is not available."}}},"MobileMoneyView":{"type":"object","required":["id","provider","month","inflow_amount","outflow_amount","currency","origin","consent_id"],"properties":{"closing_balance":{"type":["string","null"]},"consent_id":{"type":"string","format":"uuid"},"currency":{"type":"string"},"id":{"type":"string","format":"uuid"},"inflow_amount":{"type":"string"},"inflow_count":{"type":["integer","null"],"format":"int32"},"month":{"type":"string","format":"date"},"origin":{"$ref":"#/components/schemas/SummaryOrigin"},"outflow_amount":{"type":"string"},"outflow_count":{"type":["integer","null"],"format":"int32"},"phone_id":{"type":["string","null"],"format":"uuid"},"provider":{"$ref":"#/components/schemas/MoneyProvider"}}},"MoneyProvider":{"type":"string","enum":["mpesa","airtel_money","mixx_by_yas","halopesa","tpesa","other"]},"MonthFlow":{"type":"object","required":["month","inflow_tzs","outflow_tzs"],"properties":{"inflow_tzs":{"type":"number","format":"double","description":"Average per year with any record."},"month":{"type":"integer","format":"int32","description":"1–12.","minimum":0},"outflow_tzs":{"type":"number","format":"double"}}},"NewApiClient":{"type":"object","required":["name"],"properties":{"description":{"type":["string","null"]},"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}}},"NewBuyer":{"type":"object","required":["name","buyer_type"],"properties":{"buyer_type":{"$ref":"#/components/schemas/BuyerType"},"district_id":{"type":["string","null"],"format":"uuid"},"name":{"type":"string"},"region_id":{"type":["string","null"],"format":"uuid"}}},"NewConsent":{"type":"object","required":["grantee_type","purposes","scopes","channel","text_version"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"evidence_document_id":{"type":["string","null"],"format":"uuid","description":"The signed form or recording, once documents exist (Phase 12)."},"grantee_category":{"type":["string","null"],"description":"The partner category, for `partner_category` (e.g. `mfi`)."},"grantee_id":{"type":["string","null"],"format":"uuid","description":"The partner, for `partner`."},"grantee_type":{"$ref":"#/components/schemas/GranteeType"},"language":{"type":["string","null"],"description":"ISO 639-1; defaults to `sw`."},"purposes":{"type":"array","items":{"$ref":"#/components/schemas/Purpose"}},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/DataScope"}},"text_version":{"type":"string","description":"The version of the consent text the farmer agreed to."},"valid_from":{"type":["string","null"],"format":"date-time"},"valid_to":{"type":["string","null"],"format":"date-time"}}},"NewCropCycle":{"type":"object","required":["season_id","crop_code"],"properties":{"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]},"conservation_agriculture":{"type":"boolean"},"crop_code":{"type":"string"},"id":{"type":["string","null"],"format":"uuid","description":"Client-generated UUIDv7; retrying with the same ID returns the first result."},"intercrop_with":{"type":["string","null"],"format":"uuid","description":"A cycle on the same plot and season this crop is intercropped with."},"irrigation":{"oneOf":[{"$ref":"#/components/schemas/Irrigation"},{"type":"null"}]},"mechanized":{"type":"boolean"},"planted_area":{"type":["number","null"],"format":"double","description":"Area under this crop, in `planted_area_unit`. Defaults to the plot's area."},"planted_area_unit":{"oneOf":[{"$ref":"#/components/schemas/AreaUnit"},{"type":"null"}]},"planting_date":{"type":["string","null"],"format":"date"},"season_id":{"type":"string","format":"uuid","description":"From `GET /v1/reference/seasons?zone=…`; must be a season of the plot's zone."},"status":{"oneOf":[{"$ref":"#/components/schemas/CycleStatus","description":"`planned`, `planted` or `growing`. Defaults to `planted` when `planting_date` is\ngiven, else `planned`."},{"type":"null"}]},"variety_code":{"type":["string","null"]}}},"NewEvidence":{"type":"object","required":["evidence_type","evidence_id"],"properties":{"evidence_id":{"type":"string","description":"The evidence's ID in its own domain (a document ID, a visit ID, a claim ID, …)."},"evidence_type":{"$ref":"#/components/schemas/EvidenceType"},"note":{"type":["string","null"]}}},"NewExpense":{"type":"object","required":["category","amount","incurred_on"],"properties":{"amount":{"type":"number","format":"double"},"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]},"category":{"$ref":"#/components/schemas/ExpenseCategory"},"crop_cycle_id":{"type":["string","null"],"format":"uuid","description":"The crop cycle the expense is for (sets the season), or give `season_id`."},"currency":{"type":["string","null"]},"description":{"type":["string","null"]},"id":{"type":["string","null"],"format":"uuid"},"incurred_on":{"type":"string","format":"date"},"input_application_id":{"type":["string","null"],"format":"uuid"},"season_id":{"type":["string","null"],"format":"uuid"}}},"NewFarm":{"type":"object","properties":{"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]},"id":{"type":["string","null"],"format":"uuid","description":"Client-generated UUIDv7; retrying with the same ID returns the first result."},"name":{"type":["string","null"]}}},"NewFarmer":{"type":"object","required":["given_name","registration"],"properties":{"birth":{"oneOf":[{"$ref":"#/components/schemas/Birth"},{"type":"null"}]},"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]},"draft":{"type":"boolean","description":"Save as `draft` (incomplete capture) instead of `registered`."},"education":{"oneOf":[{"$ref":"#/components/schemas/Education"},{"type":"null"}]},"family_name":{"type":["string","null"]},"given_name":{"type":"string"},"household":{"oneOf":[{"$ref":"#/components/schemas/HouseholdInput"},{"type":"null"}]},"id":{"type":["string","null"],"format":"uuid","description":"Client-generated UUIDv7. Retrying with the same ID returns the first result."},"identifiers":{"type":"array","items":{"$ref":"#/components/schemas/IdentifierInput"}},"known_as":{"type":["string","null"]},"languages":{"type":"array","items":{"type":"string"},"description":"ISO 639-1 codes; defaults to `[\"sw\"]`."},"location":{"oneOf":[{"$ref":"#/components/schemas/LocationInput"},{"type":"null"}]},"middle_name":{"type":["string","null"]},"phones":{"type":"array","items":{"$ref":"#/components/schemas/PhoneInput"}},"registration":{"$ref":"#/components/schemas/RegistrationInput"},"sex":{"oneOf":[{"$ref":"#/components/schemas/Sex"},{"type":"null"}]}}},"NewFinancing":{"type":"object","required":["lender_type","purpose","principal","disbursed_on"],"properties":{"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]},"collateral_type":{"oneOf":[{"$ref":"#/components/schemas/Collateral"},{"type":"null"}]},"currency":{"type":["string","null"]},"disbursed_on":{"type":"string","format":"date"},"id":{"type":["string","null"],"format":"uuid"},"instalments":{"type":"array","items":{"$ref":"#/components/schemas/InstalmentInput"},"description":"The repayment schedule, with payments made so far."},"interest_rate_pct":{"type":["number","null"],"format":"double","description":"Annual rate in percent, when known."},"lender_name":{"type":["string","null"]},"lender_type":{"$ref":"#/components/schemas/LenderType"},"maturity_on":{"type":["string","null"],"format":"date"},"principal":{"type":"number","format":"double"},"purpose":{"$ref":"#/components/schemas/LoanPurpose"},"status":{"oneOf":[{"$ref":"#/components/schemas/LoanStatus","description":"Defaults to `active`."},{"type":"null"}]},"tenor_months":{"type":["integer","null"],"format":"int32"}}},"NewHarvest":{"type":"object","required":["harvested_on","quantity","unit"],"properties":{"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]},"harvest_end_on":{"type":["string","null"],"format":"date","description":"Last day, when harvesting took several days."},"harvested_on":{"type":"string","format":"date"},"id":{"type":["string","null"],"format":"uuid","description":"Client-generated UUIDv7; retrying with the same ID returns the first result."},"is_final":{"type":["boolean","null"],"description":"The last harvest of the cycle (default): the cycle becomes `harvested`."},"losses":{"type":"array","items":{"$ref":"#/components/schemas/LossInput"}},"quality_grade":{"oneOf":[{"$ref":"#/components/schemas/QualityGrade"},{"type":"null"}]},"quantity":{"type":"number","format":"double","description":"In `unit`, e.g. 12 `gunia_100kg` or 30 `debe`."},"unit":{"type":"string"}}},"NewIdentifier":{"allOf":[{"$ref":"#/components/schemas/IdentifierInput"},{"type":"object","properties":{"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]}}}]},"NewInput":{"type":"object","required":["input_code","quantity","unit","applied_on","source"],"properties":{"applied_on":{"type":"string","format":"date"},"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]},"cost":{"oneOf":[{"$ref":"#/components/schemas/CostInput"},{"type":"null"}]},"id":{"type":["string","null"],"format":"uuid","description":"Client-generated UUIDv7; retrying with the same ID returns the first result."},"input_code":{"type":"string","description":"From `GET /v1/reference/inputs`, e.g. `dap`."},"product":{"type":["string","null"],"description":"Brand or grade, e.g. `17-17-17`."},"quantity":{"type":"number","format":"double","description":"In `unit`, e.g. 2 bags."},"receipt_document_id":{"type":["string","null"],"format":"uuid","description":"A receipt in the documents domain, when one exists."},"source":{"$ref":"#/components/schemas/InputSource"},"unit":{"type":"string","description":"From `GET /v1/reference/units`, e.g. `gunia_50kg`, `kilogram`, `litre`."}}},"NewMobileMoneySummary":{"type":"object","required":["provider","month","inflow_amount","outflow_amount","origin"],"properties":{"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]},"closing_balance":{"type":["number","null"],"format":"double"},"currency":{"type":["string","null"]},"inflow_amount":{"type":"number","format":"double"},"inflow_count":{"type":["integer","null"],"format":"int32"},"month":{"type":"string","format":"date","description":"Any day of the month; stored as the first."},"origin":{"$ref":"#/components/schemas/SummaryOrigin"},"outflow_amount":{"type":"number","format":"double"},"outflow_count":{"type":["integer","null"],"format":"int32"},"phone_id":{"type":["string","null"],"format":"uuid","description":"The farmer's phone (from the farmer record) the wallet is on."},"provider":{"$ref":"#/components/schemas/MoneyProvider"}}},"NewObservation":{"type":"object","required":["observed_on","tree_count"],"properties":{"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]},"expected_version":{"type":["integer","null"],"format":"int32","description":"The stand `version` you read."},"notes":{"type":["string","null"]},"observed_on":{"type":"string","format":"date"},"productive_trees":{"type":["integer","null"],"format":"int32"},"removed":{"type":"boolean","description":"The stand was uprooted or replaced."},"tree_count":{"type":"integer","format":"int32"}}},"NewPhone":{"allOf":[{"$ref":"#/components/schemas/PhoneInput"},{"type":"object","properties":{"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]}}}]},"NewPlot":{"type":"object","required":["geometry","capture_method"],"properties":{"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]},"capture_method":{"$ref":"#/components/schemas/CaptureMethod"},"geometry":{"type":"object","description":"GeoJSON geometry (RFC 7946, `[longitude, latitude]`): Point, Polygon or MultiPolygon."},"gps_accuracy_m":{"type":["number","null"],"format":"double"},"id":{"type":["string","null"],"format":"uuid","description":"Client-generated UUIDv7; retrying with the same ID returns the first result."},"land_use":{"oneOf":[{"$ref":"#/components/schemas/LandUse"},{"type":"null"}]},"name":{"type":["string","null"]},"reported_area":{"type":["number","null"],"format":"double","description":"Area as the farmer states it, in `reported_unit`."},"reported_unit":{"oneOf":[{"$ref":"#/components/schemas/AreaUnit"},{"type":"null"}]},"tenure":{"oneOf":[{"$ref":"#/components/schemas/TenureInput"},{"type":"null"}]}}},"NewRepayment":{"type":"object","required":["due_on"],"properties":{"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]},"due_amount":{"type":["number","null"],"format":"double"},"due_on":{"type":"string","format":"date","description":"The instalment's due date: an unpaid instalment due that day takes the payment;\notherwise a new instalment is recorded."},"paid_amount":{"type":"number","format":"double"},"paid_on":{"type":["string","null"],"format":"date"}}},"NewSale":{"type":"object","required":["sold_on","quantity","unit","payment_method"],"properties":{"amount":{"type":["number","null"],"format":"double","description":"The total paid; or give `price_per_unit` (per `unit`)."},"buyer":{"oneOf":[{"$ref":"#/components/schemas/NewBuyer"},{"type":"null"}]},"buyer_id":{"type":["string","null"],"format":"uuid","description":"A known buyer, or `buyer` to record a new one."},"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]},"crop_code":{"type":["string","null"],"description":"Required without a crop cycle."},"crop_cycle_id":{"type":["string","null"],"format":"uuid","description":"The crop cycle sold from, when known; sets the crop and season."},"currency":{"type":["string","null"],"description":"ISO 4217; defaults to TZS."},"harvest_id":{"type":["string","null"],"format":"uuid","description":"The harvest sold from (of that crop cycle)."},"id":{"type":["string","null"],"format":"uuid","description":"Client-generated UUIDv7; retrying with the same ID returns the first result."},"paid_on":{"type":["string","null"],"format":"date"},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"price_per_unit":{"type":["number","null"],"format":"double"},"quantity":{"type":"number","format":"double","description":"In `unit`, e.g. 10 `gunia_100kg`."},"sold_on":{"type":"string","format":"date"},"unit":{"type":"string"}}},"NewSavingsMembership":{"type":"object","required":["group_type","group_name"],"properties":{"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]},"currency":{"type":["string","null"]},"group_name":{"type":"string"},"group_type":{"$ref":"#/components/schemas/GroupType"},"joined_on":{"type":["string","null"],"format":"date"},"left_on":{"type":["string","null"],"format":"date"},"monthly_contribution":{"type":["number","null"],"format":"double"},"role":{"oneOf":[{"$ref":"#/components/schemas/GroupRole"},{"type":"null"}]}}},"NewStand":{"type":"object","required":["crop_code","planting_year","tree_count"],"properties":{"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]},"crop_code":{"type":"string","description":"A perennial crop, e.g. `coffee_arabica`, `cashew`, `avocado`."},"id":{"type":["string","null"],"format":"uuid","description":"Client-generated UUIDv7; retrying with the same ID returns the first result."},"observed_on":{"type":["string","null"],"format":"date","description":"When the trees were counted; defaults to today."},"planting_year":{"type":"integer","format":"int32"},"productive_trees":{"type":["integer","null"],"format":"int32","description":"Trees bearing fruit (young trees take years to come into bearing)."},"tree_count":{"type":"integer","format":"int32"},"variety_code":{"type":["string","null"]}}},"NewUser":{"type":"object","required":["kind","email","full_name"],"properties":{"email":{"type":"string"},"full_name":{"type":"string"},"kind":{"$ref":"#/components/schemas/UserKind"},"phone":{"type":["string","null"]},"roles":{"type":"array","items":{"$ref":"#/components/schemas/RoleGrant"}}}},"NewVisit":{"type":"object","required":["lon","lat","purpose"],"properties":{"accuracy_m":{"type":["number","null"],"format":"double"},"device_id":{"type":["string","null"]},"form_version":{"type":["string","null"]},"lat":{"type":"number","format":"double"},"lon":{"type":"number","format":"double","description":"Where the agent checked in (WGS84)."},"notes":{"type":["string","null"]},"photo_count":{"type":"integer","format":"int32"},"plot_id":{"type":["string","null"],"format":"uuid","description":"The plot visited; defaults to the farm's nearest plot."},"purpose":{"$ref":"#/components/schemas/VisitPurpose"},"visited_at":{"type":["string","null"],"format":"date-time","description":"Device time of the check-in; defaults to now."}}},"ObservationView":{"type":"object","required":["id","observed_on","tree_count","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"notes":{"type":["string","null"]},"observed_on":{"type":"string","format":"date"},"productive_trees":{"type":["integer","null"],"format":"int32"},"tree_count":{"type":"integer","format":"int32"}}},"Outcome":{"type":"string","enum":["no_match","possible_duplicate","likely_duplicate"]},"PasswordResetRequest":{"type":"object","required":["token","new_password"],"properties":{"new_password":{"type":"string"},"token":{"type":"string","description":"From account creation or an administrator's reset."}}},"PasswordSetup":{"type":"object","description":"A one-time token for setting a password at `POST /v1/auth/password/reset`. Shown once;\ndeliver it to the user over a trusted channel.","required":["reset_token","expires_at"],"properties":{"expires_at":{"type":"string","format":"date-time"},"reset_token":{"type":"string"}}},"PaymentMethod":{"type":"string","enum":["cash","mobile_money","bank","cooperative","in_kind","credit_offset"]},"PermissionView":{"type":"object","required":["code","description"],"properties":{"code":{"type":"string"},"description":{"type":"string"}}},"PhoneInput":{"type":"object","required":["number"],"properties":{"number":{"type":"string","description":"Any common form: `0754 123 456`, `+255754123456`, `255754123456`."},"primary":{"type":"boolean","description":"The number to call first. The first phone is primary unless another is marked."}}},"PhoneView":{"type":"object","required":["id","line_type","is_primary","is_shared","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"is_primary":{"type":"boolean"},"is_shared":{"type":"boolean","description":"The number is also on another farmer."},"line_type":{"type":"string","description":"`mobile` or `fixed`."},"masked":{"type":"string","description":"Country code and last three digits, e.g. `+255•••••••456`."},"operator":{"type":["string","null"],"description":"Network by prefix, a hint (numbers are portable)."}}},"PlotFeature":{"type":"object","description":"A plot as a GeoJSON Feature (RFC 7946).","required":["type","id","geometry","properties"],"properties":{"geometry":{"type":"object"},"id":{"type":"string","format":"uuid"},"properties":{"$ref":"#/components/schemas/PlotProperties"},"type":{"type":"string","example":"Feature"}}},"PlotProperties":{"type":"object","description":"Plot attributes carried as GeoJSON `properties`.","required":["id","farm_id","farmer_id","status","capture_method","vertex_count","repaired","centroid","h3_r7","h3_r9","geometry_version","version","flag_count","data_origin","created_at","updated_at"],"properties":{"capture_method":{"$ref":"#/components/schemas/CaptureMethod"},"centroid":{"type":"array","items":{"type":"number","format":"double"},"description":"`[longitude, latitude]` of a point inside the plot."},"co_owner_count":{"type":["integer","null"],"format":"int32"},"created_at":{"type":"string","format":"date-time"},"data_origin":{"type":"string"},"district_id":{"type":["string","null"],"format":"uuid"},"farm_id":{"type":"string","format":"uuid"},"farmer_id":{"type":"string","format":"uuid"},"flag_count":{"type":"integer","format":"int64","description":"Current check flags (overlaps, water, discrepancy…)."},"geometry_version":{"type":"integer","format":"int32"},"gps_accuracy_m":{"type":["number","null"],"format":"double"},"h3_r7":{"type":"string","description":"H3 cells (hex) at resolution 7 (weather) and 9 (field)."},"h3_r9":{"type":"string"},"id":{"type":"string","format":"uuid"},"land_use":{"oneOf":[{"$ref":"#/components/schemas/LandUse"},{"type":"null"}]},"measured_area_ha":{"type":["number","null"],"format":"double"},"name":{"type":["string","null"]},"ownership_share":{"type":["number","null"],"format":"double"},"region_id":{"type":["string","null"],"format":"uuid"},"repaired":{"type":"boolean"},"reported_area":{"type":["number","null"],"format":"double"},"reported_area_ha":{"type":["number","null"],"format":"double"},"reported_unit":{"type":["string","null"]},"status":{"type":"string"},"tenure":{"oneOf":[{"$ref":"#/components/schemas/Tenure"},{"type":"null"}]},"updated_at":{"type":"string","format":"date-time"},"version":{"type":"integer","format":"int32","description":"Send it back as `expected_version` to change the geometry safely."},"vertex_count":{"type":"integer","format":"int32"},"ward_id":{"type":["string","null"],"format":"uuid"}}},"PointZone":{"type":"object","description":"The zone of a point and its calendars (for `crop`, or all).","required":["area","zone","mixed_region","calendars"],"properties":{"area":{"$ref":"#/components/schemas/Resolved"},"calendars":{"type":"array","items":{"$ref":"#/components/schemas/CalendarEntry"}},"mixed_region":{"type":"boolean","description":"The region spans both rainfall regimes; the zone is its main one."},"zone":{"$ref":"#/components/schemas/Zone"}}},"Problem":{"type":"object","description":"An RFC 9457 problem document.","required":["type","title","status"],"properties":{"detail":{"type":["string","null"]},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ProblemFieldError"},"description":"Field errors; present only for `validation` problems."},"instance":{"type":["string","null"],"description":"The request path.","example":"/v1/farmers"},"request_id":{"type":["string","null"],"description":"Correlation ID; include it in support requests."},"status":{"type":"integer","format":"int32","example":422,"minimum":0},"title":{"type":"string","example":"Validation failed"},"type":{"type":"string","description":"Stable URN, e.g. `urn:mela:problem:validation`. Clients branch on this.","example":"urn:mela:problem:validation"}}},"ProblemFieldError":{"type":"object","required":["field","code","message"],"properties":{"code":{"type":"string","example":"invalid_format"},"field":{"type":"string","example":"phone"},"message":{"type":"string","example":"Phone must be in E.164 format"}}},"ProductionCrop":{"type":"object","description":"One crop in one season of a farmer's history.","required":["crop_code","cycles","plots","failed_cycles","intercropped","harvested_kg","loss_kg","input_cost_tzs","fertilizer_kg","flags"],"properties":{"benchmark_kg_ha":{"type":["number","null"],"format":"double","description":"Typical smallholder yield for the crop in the zone (indicative)."},"crop_code":{"type":"string"},"cycles":{"type":"integer","format":"int32"},"failed_cycles":{"type":"integer","format":"int32"},"fertilizer_kg":{"type":"number","format":"double"},"flags":{"type":"integer","format":"int32","description":"Current plausibility flags on these cycles."},"harvested_kg":{"type":"number","format":"double"},"input_cost_tzs":{"type":"number","format":"double"},"intercropped":{"type":"boolean"},"loss_kg":{"type":"number","format":"double"},"planted_area_ha":{"type":["number","null"],"format":"double"},"plots":{"type":"integer","format":"int32"},"yield_index":{"type":["number","null"],"format":"double","description":"`yield_kg_ha / benchmark_kg_ha`: 1 is a typical yield."},"yield_kg_ha":{"type":["number","null"],"format":"double"}}},"ProductionHistory":{"type":"object","description":"A farmer's production history: per season and crop, per crop, and a summary.","required":["farmer_id","seasons","crops"],"properties":{"crops":{"type":"array","items":{"$ref":"#/components/schemas/CropHistory"}},"farmer_id":{"type":"string","format":"uuid"},"seasons":{"type":"array","items":{"$ref":"#/components/schemas/ProductionSeason"},"description":"Newest first."},"summary":{"oneOf":[{"$ref":"#/components/schemas/ProductionSummary","description":"`None` until the farmer has a planted crop cycle."},{"type":"null"}]}}},"ProductionSeason":{"type":"object","required":["season_id","label","agricultural_year","season_code","starts_on","crops"],"properties":{"agricultural_year":{"type":"string"},"crops":{"type":"array","items":{"$ref":"#/components/schemas/ProductionCrop"}},"label":{"type":"string"},"season_code":{"type":"string"},"season_id":{"type":"string","format":"uuid"},"starts_on":{"type":"string","format":"date"}}},"ProductionSummary":{"type":"object","required":["seasons_active","first_season_on","last_season_on","crops","cycles","failed_cycles","harvested_kg","refreshed_at"],"properties":{"consistency":{"type":["number","null"],"format":"double","description":"0–1: 1 − coefficient of variation of the seasonal yield index (two seasons or more)."},"crops":{"type":"array","items":{"type":"string"}},"cycles":{"type":"integer","format":"int32"},"failed_cycles":{"type":"integer","format":"int32"},"first_season_on":{"type":"string","format":"date"},"harvested_kg":{"type":"number","format":"double"},"last_season_on":{"type":"string","format":"date"},"mean_yield_index":{"type":["number","null"],"format":"double","description":"Mean of the seasonal yield indexes (1 = typical)."},"refreshed_at":{"type":"string","format":"date-time"},"seasons_active":{"type":"integer","format":"int32"},"yield_trend":{"type":["number","null"],"format":"double","description":"Change of the seasonal yield index per year."}}},"Purpose":{"type":"string","description":"Why the data is held or shared.","enum":["record_keeping","credit_assessment","loan_monitoring","insurance_underwriting","insurance_claims","input_finance_eligibility","program_enrolment_monitoring","offtake_sourcing","research_aggregated"]},"QualityGrade":{"type":"string","enum":["a","b","c","ungraded"]},"Ready":{"type":"object","required":["status","checks"],"properties":{"checks":{"$ref":"#/components/schemas/ReadyChecks"},"status":{"type":"string","example":"ready"}}},"ReadyChecks":{"type":"object","required":["database"],"properties":{"database":{"type":"string","example":"up"}}},"RefreshRequest":{"type":"object","required":["refresh_token"],"properties":{"refresh_token":{"type":"string"}}},"Registered":{"type":"object","description":"Result of a registration.","required":["farmer","created","duplicates"],"properties":{"created":{"type":"boolean","description":"`false` when the request repeated an earlier registration (same `id`)."},"duplicates":{"type":"array","items":{"$ref":"#/components/schemas/DuplicateCandidate"},"description":"Possible and likely duplicates found, for review. Nothing is merged automatically."},"farmer":{"$ref":"#/components/schemas/FarmerDetail"}}},"RegistrationInput":{"type":"object","required":["channel"],"properties":{"channel":{"$ref":"#/components/schemas/Channel"},"consent_ref":{"type":["string","null"],"description":"Consent form or record reference."},"occurred_at":{"type":["string","null"],"format":"date-time","description":"When the registration happened (defaults to now)."},"partner_id":{"type":["string","null"],"format":"uuid"},"program":{"type":["string","null"]}}},"RegistrationView":{"type":"object","required":["id","channel","occurred_at","recorded_at"],"properties":{"actor_id":{"type":["string","null"],"format":"uuid"},"actor_kind":{"type":["string","null"]},"channel":{"type":"string"},"consent_ref":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"occurred_at":{"type":"string","format":"date-time"},"partner_id":{"type":["string","null"],"format":"uuid"},"program":{"type":["string","null"]},"recorded_at":{"type":"string","format":"date-time"},"source_id":{"type":["string","null"],"format":"uuid","description":"The provenance source of the registration's claims."},"ward_id":{"type":["string","null"],"format":"uuid"}}},"RepaymentBehaviour":{"type":"object","required":["instalments_due","paid_on_time","max_days_past_due","current_days_past_due","completed_loans","active_loans","defaulted_loans"],"properties":{"active_loans":{"type":"integer","minimum":0},"completed_loans":{"type":"integer","minimum":0},"current_days_past_due":{"type":"integer","format":"int64","description":"Days the oldest unpaid due instalment is overdue now (0 when current)."},"defaulted_loans":{"type":"integer","minimum":0},"instalments_due":{"type":"integer","description":"Instalments due by the as-of date.","minimum":0},"max_days_past_due":{"type":"integer","format":"int64","description":"Worst lateness ever: days late at payment, or days overdue for unpaid ones."},"on_time_rate":{"type":["number","null"],"format":"double","description":"`paid_on_time / instalments_due`; `None` with nothing due yet."},"paid_on_time":{"type":"integer","description":"Of those, settled on or before their due date.","minimum":0}}},"RepaymentView":{"type":"object","required":["id","due_on","due_amount","paid_amount"],"properties":{"days_late":{"type":["integer","null"],"format":"int32","description":"Days between due and paid (0 when on time); null while unpaid."},"due_amount":{"type":"string"},"due_on":{"type":"string","format":"date"},"id":{"type":"string","format":"uuid"},"paid_amount":{"type":"string"},"paid_on":{"type":["string","null"],"format":"date"}}},"Resolved":{"type":"object","description":"The ward, district and region containing a point.","required":["ward","district","region"],"properties":{"district":{"$ref":"#/components/schemas/AreaRef"},"region":{"$ref":"#/components/schemas/AreaRef"},"ward":{"$ref":"#/components/schemas/AreaRef"}}},"RevokeRequest":{"type":"object","properties":{"reason":{"type":["string","null"]}}},"RoleCatalog":{"type":"object","required":["roles","permissions"],"properties":{"permissions":{"type":"array","items":{"$ref":"#/components/schemas/PermissionView"}},"roles":{"type":"array","items":{"$ref":"#/components/schemas/RoleView"}}}},"RoleGrant":{"type":"object","description":"A role held by a user, optionally limited to admin areas.","required":["role"],"properties":{"area_ids":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"description":"Admin areas (reference, Phase 3) the role is limited to; absent means everywhere."},"role":{"type":"string","example":"field_supervisor"}}},"RoleView":{"type":"object","required":["code","name","description","actor_kind","mfa_required","permissions"],"properties":{"actor_kind":{"type":"string","description":"The kind of actor that may hold it: `staff`, `field_agent`, `partner_user`, `api_client`."},"code":{"type":"string"},"description":{"type":"string"},"mfa_required":{"type":"boolean"},"name":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}}},"RolesRequest":{"type":"object","required":["roles"],"properties":{"roles":{"type":"array","items":{"$ref":"#/components/schemas/RoleGrant"},"description":"The complete set of roles the user should hold."}}},"SaleFlagCode":{"type":"string","enum":["price_above_band","price_below_band","sold_more_than_harvested"]},"SaleFlagView":{"type":"object","required":["code","message","details"],"properties":{"code":{"$ref":"#/components/schemas/SaleFlagCode"},"details":{"type":"object"},"message":{"type":"string"}}},"SaleList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SaleView"}}}},"SaleView":{"type":"object","required":["id","farmer_id","crop_code","sold_on","quantity_kg","original_value","original_unit","amount","currency","price_per_kg","payment_method","flags","created_at"],"properties":{"amount":{"type":"string","description":"Decimal string."},"buyer":{"oneOf":[{"$ref":"#/components/schemas/Buyer"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"crop_code":{"type":"string"},"crop_cycle_id":{"type":["string","null"],"format":"uuid"},"currency":{"type":"string"},"farmer_id":{"type":"string","format":"uuid"},"flags":{"type":"array","items":{"$ref":"#/components/schemas/SaleFlagView"}},"harvest_id":{"type":["string","null"],"format":"uuid"},"id":{"type":"string","format":"uuid"},"original_unit":{"type":"string"},"original_value":{"type":"number","format":"double"},"paid_on":{"type":["string","null"],"format":"date"},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"price_per_kg":{"type":"number","format":"double"},"quantity_kg":{"type":"number","format":"double"},"season_id":{"type":["string","null"],"format":"uuid"},"sold_on":{"type":"string","format":"date"}}},"SavingsView":{"type":"object","required":["id","farmer_id","group_type","group_name","role","currency","consent_id","created_at"],"properties":{"consent_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"currency":{"type":"string"},"farmer_id":{"type":"string","format":"uuid"},"group_name":{"type":"string"},"group_type":{"$ref":"#/components/schemas/GroupType"},"id":{"type":"string","format":"uuid"},"joined_on":{"type":["string","null"],"format":"date"},"left_on":{"type":["string","null"],"format":"date"},"monthly_contribution":{"type":["string","null"]},"role":{"$ref":"#/components/schemas/GroupRole"}}},"Season":{"type":"object","description":"One season of one zone, e.g. \"2025/26 Masika\".","required":["id","zone_code","season_code","agricultural_year","label","label_en","label_sw","starts_on","ends_on"],"properties":{"agricultural_year":{"type":"string","description":"October–September, e.g. `2025/26`."},"ends_on":{"type":"string","format":"date"},"id":{"type":"string","format":"uuid"},"label":{"type":"string","description":"In the request's language."},"label_en":{"type":"string"},"label_sw":{"type":"string"},"season_code":{"type":"string","description":"`unimodal`, `masika`, `vuli` or `dry_irrigated`."},"starts_on":{"type":"string","format":"date","description":"Expected window (inclusive)."},"zone_code":{"type":"string"}}},"SeasonIncome":{"type":"object","description":"Income of one season (sales with a crop cycle, and expenses).","required":["season_id","label","agricultural_year","starts_on","revenue_tzs","expenses_tzs","net_tzs","sold_kg"],"properties":{"agricultural_year":{"type":"string"},"expenses_tzs":{"type":"number","format":"double"},"label":{"type":"string"},"net_tzs":{"type":"number","format":"double"},"revenue_tzs":{"type":"number","format":"double"},"season_id":{"type":"string","format":"uuid"},"sold_kg":{"type":"number","format":"double"},"starts_on":{"type":"string","format":"date"}}},"SeasonPage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Season"}},"next_cursor":{"type":["string","null"]}}},"SeasonRef":{"type":"object","description":"The season a cycle belongs to.","required":["id","label","agricultural_year","season_code","starts_on","ends_on"],"properties":{"agricultural_year":{"type":"string"},"ends_on":{"type":"string","format":"date"},"id":{"type":"string","format":"uuid"},"label":{"type":"string","description":"e.g. \"2025/26 Masika\", in the request's language."},"season_code":{"type":"string"},"starts_on":{"type":"string","format":"date"}}},"SetHousehold":{"allOf":[{"$ref":"#/components/schemas/HouseholdInput"},{"type":"object","properties":{"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]}}}]},"SetLocation":{"allOf":[{"$ref":"#/components/schemas/LocationInput"},{"type":"object","properties":{"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]}}}]},"Sex":{"type":"string","enum":["female","male"]},"SourceKind":{"type":"string","description":"How a piece of data reached Mela.","enum":["self_reported","field_agent_observed","document","partner_record","external_dataset","satellite","derived","system_import"]},"SourceView":{"type":"object","required":["id","kind","channel","has_photo","captured_at","recorded_at","data_origin"],"properties":{"actor_id":{"type":["string","null"],"format":"uuid"},"actor_kind":{"type":["string","null"]},"captured_at":{"type":"string","format":"date-time"},"channel":{"type":"string"},"data_origin":{"type":"string"},"device_id":{"type":["string","null"]},"external_ref":{"type":["string","null"]},"form_version":{"type":["string","null"]},"has_photo":{"type":"boolean"},"id":{"type":"string","format":"uuid"},"kind":{"$ref":"#/components/schemas/SourceKind"},"location":{"type":["array","null"],"items":{"type":"number","format":"double"},"description":"`[longitude, latitude]`."},"location_accuracy_m":{"type":["number","null"],"format":"double"},"recorded_at":{"type":"string","format":"date-time"}}},"StandDetail":{"allOf":[{"$ref":"#/components/schemas/StandView"},{"type":"object","required":["observations","seasons"],"properties":{"observations":{"type":"array","items":{"$ref":"#/components/schemas/ObservationView"}},"seasons":{"type":"array","items":{"$ref":"#/components/schemas/StandSeason"}}}}],"description":"A stand with its yearly counts and its seasons, newest first."},"StandList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StandView"}}}},"StandSeason":{"type":"object","description":"One season of the stand: its crop cycle, read per tree.","required":["crop_cycle_id","season_id","season_label","agricultural_year","status","harvested_kg","tree_age_years"],"properties":{"agricultural_year":{"type":"string"},"crop_cycle_id":{"type":"string","format":"uuid"},"harvested_kg":{"type":"number","format":"double"},"kg_per_tree":{"type":["number","null"],"format":"double"},"season_id":{"type":"string","format":"uuid"},"season_label":{"type":"string"},"status":{"type":"string"},"tree_age_years":{"type":"integer","format":"int32","description":"Age of the trees in that season."},"tree_count":{"type":["integer","null"],"format":"int32","description":"Trees counted on or before the season's end (else the first count)."},"yield_kg_ha":{"type":["number","null"],"format":"double"}}},"StandView":{"type":"object","required":["id","plot_id","farm_id","farmer_id","crop_code","planting_year","age_years","tree_count","observed_on","status","data_origin","version","created_at","updated_at"],"properties":{"age_years":{"type":"integer","format":"int32","description":"Years since planting, this year."},"created_at":{"type":"string","format":"date-time"},"crop_code":{"type":"string"},"data_origin":{"type":"string"},"farm_id":{"type":"string","format":"uuid"},"farmer_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"observed_on":{"type":"string","format":"date"},"planting_year":{"type":"integer","format":"int32"},"plot_id":{"type":"string","format":"uuid"},"productive_trees":{"type":["integer","null"],"format":"int32"},"removed_on":{"type":["string","null"],"format":"date"},"status":{"type":"string","description":"`active` or `removed`."},"tree_count":{"type":"integer","format":"int32","description":"As last observed."},"updated_at":{"type":"string","format":"date-time"},"variety_code":{"type":["string","null"]},"version":{"type":"integer","format":"int32","description":"Send it back as `expected_version` with an observation."}}},"StatusChange":{"type":"object","required":["status"],"properties":{"reason":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/FarmerStatus"}}},"StatusUpdate":{"type":"object","required":["status"],"properties":{"reason":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/ClaimStatus"}}},"SummaryOrigin":{"type":"string","enum":["statement_upload","provider_api","self_reported"]},"Tenure":{"type":"string","description":"How the farmer holds the land (Village Land Act 1999, Land Act 1999).","enum":["customary_unregistered","ccro","granted_right_of_occupancy","leased","family_or_inherited","communal","borrowed","other"]},"TenureChange":{"type":"object","properties":{"capture":{"oneOf":[{"$ref":"#/components/schemas/Capture"},{"type":"null"}]},"land_use":{"oneOf":[{"$ref":"#/components/schemas/LandUse"},{"type":"null"}]},"tenure":{"oneOf":[{"$ref":"#/components/schemas/TenureInput"},{"type":"null"}]}}},"TenureInput":{"type":"object","required":["tenure"],"properties":{"co_owner_count":{"type":["integer","null"],"format":"int32"},"ownership_share":{"type":["number","null"],"format":"double","description":"Share of the plot the farmer holds, (0, 1]. Defaults to 1."},"tenure":{"$ref":"#/components/schemas/Tenure"}}},"TokenRequest":{"type":"object","description":"OAuth2 token request (RFC 6749 §4.4). Client credentials may also come as HTTP Basic auth.","required":["grant_type"],"properties":{"client_id":{"type":["string","null"]},"client_secret":{"type":["string","null"]},"grant_type":{"type":"string","example":"client_credentials"},"scope":{"type":["string","null"],"description":"Space-separated subset of the client's scopes; default all of them."}}},"TokenResponse":{"type":"object","description":"Access and refresh tokens.","required":["access_token","token_type","expires_in","refresh_token","refresh_expires_at"],"properties":{"access_token":{"type":"string"},"expires_in":{"type":"integer","format":"int64","description":"Seconds until the access token expires.","minimum":0},"refresh_expires_at":{"type":"string","format":"date-time","description":"End of the session, whatever the refreshes."},"refresh_token":{"type":"string","description":"Exchange at `POST /v1/auth/refresh`. Single use: each refresh returns a new one."},"token_type":{"type":"string","example":"Bearer"}}},"UnitPage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/UnitView"}},"next_cursor":{"type":["string","null"]}}},"UnitView":{"allOf":[{"type":"object","description":"A name in the caller's language, with both kept.","required":["name","name_en","name_sw"],"properties":{"name":{"type":"string","description":"In the request's language (`Accept-Language: sw|en`)."},"name_en":{"type":"string"},"name_sw":{"type":"string"}}},{"type":"object","required":["code","dimension","si_unit","is_local","crop_factors"],"properties":{"code":{"type":"string"},"crop_factors":{"type":"array","items":{"$ref":"#/components/schemas/CropFactor"},"description":"Per-crop factors (e.g. debe)."},"dimension":{"type":"string"},"factor":{"type":["string","null"],"description":"Absent when it depends on the crop."},"is_local":{"type":"boolean"},"si_unit":{"type":"string","description":"The SI unit it converts to (kernel units: kilogram, hectare, litre, count)."}}}]},"Unmerge":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string"}}},"UserKind":{"type":"string","description":"Kinds of user account (API clients are a separate table).","enum":["staff","field_agent","partner_user"]},"UserPage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/UserView"}},"next_cursor":{"type":["string","null"]}}},"UserUpdate":{"type":"object","description":"Fields to change; absent fields stay as they are. An empty `phone` clears it.","properties":{"full_name":{"type":["string","null"]},"phone":{"type":["string","null"]},"status":{"oneOf":[{"$ref":"#/components/schemas/AccountStatus"},{"type":"null"}]}}},"UserView":{"type":"object","required":["id","kind","email","full_name","status","roles","mfa_enabled","locked","has_password","created_at","updated_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"email":{"type":"string"},"full_name":{"type":"string"},"has_password":{"type":"boolean"},"id":{"type":"string","format":"uuid"},"kind":{"$ref":"#/components/schemas/UserKind"},"last_login_at":{"type":["string","null"],"format":"date-time"},"locked":{"type":"boolean","description":"Temporarily locked after too many failed logins."},"mfa_enabled":{"type":"boolean"},"phone":{"type":["string","null"]},"roles":{"type":"array","items":{"$ref":"#/components/schemas/RoleGrant"}},"status":{"$ref":"#/components/schemas/AccountStatus"},"updated_at":{"type":"string","format":"date-time"}}},"Variety":{"allOf":[{"type":"object","description":"A name in the caller's language, with both kept.","required":["name","name_en","name_sw"],"properties":{"name":{"type":"string","description":"In the request's language (`Accept-Language: sw|en`)."},"name_en":{"type":"string"},"name_sw":{"type":"string"}}},{"type":"object","required":["code","seed_type"],"properties":{"code":{"type":"string"},"seed_type":{"type":"string","description":"`local`, `improved_opv`, `hybrid` or `clonal`."}}}]},"VisitList":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/VisitView"}}}},"VisitPurpose":{"type":"string","description":"Why a farm visit happened.","enum":["registration","boundary_walk","verification","monitoring","other"]},"VisitRecorded":{"type":"object","description":"Result of recording a visit.","required":["visit","flagged"],"properties":{"flagged":{"type":"boolean","description":"The check-in was too far from the plot: the visit is kept but not used as evidence."},"location_claim_id":{"type":["string","null"],"format":"uuid","description":"The location claim raised by an on-site visit with a photo (C1)."},"visit":{"$ref":"#/components/schemas/VisitView"}}},"VisitView":{"type":"object","required":["id","farm_id","location","distance_m","within_geofence","purpose","photo_count","visited_at","recorded_at"],"properties":{"accuracy_m":{"type":["number","null"],"format":"double"},"agent_id":{"type":["string","null"],"format":"uuid"},"distance_m":{"type":"number","format":"double","description":"Metres from the plot (0 inside it)."},"farm_id":{"type":"string","format":"uuid"},"id":{"type":"string","format":"uuid"},"location":{"type":"array","items":{"type":"number","format":"double"},"description":"`[longitude, latitude]` of the check-in."},"notes":{"type":["string","null"]},"photo_count":{"type":"integer","format":"int32"},"plot_id":{"type":["string","null"],"format":"uuid"},"purpose":{"$ref":"#/components/schemas/VisitPurpose"},"recorded_at":{"type":"string","format":"date-time"},"source_id":{"type":["string","null"],"format":"uuid"},"visited_at":{"type":"string","format":"date-time"},"within_geofence":{"type":"boolean"}}},"YearIncome":{"type":"object","required":["agricultural_year","revenue_tzs","expenses_tzs","net_tzs"],"properties":{"agricultural_year":{"type":"string"},"expenses_tzs":{"type":"number","format":"double"},"net_tzs":{"type":"number","format":"double"},"revenue_tzs":{"type":"number","format":"double"}}},"Zone":{"allOf":[{"type":"object","description":"A name in the caller's language, with both kept.","required":["name","name_en","name_sw"],"properties":{"name":{"type":"string","description":"In the request's language (`Accept-Language: sw|en`)."},"name_en":{"type":"string"},"name_sw":{"type":"string"}}},{"type":"object","required":["code","rainfall_regime"],"properties":{"code":{"type":"string"},"rainfall_regime":{"type":"string","description":"`unimodal` or `bimodal`."}}}]},"ZonePage":{"type":"object","required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Zone"}},"next_cursor":{"type":["string","null"]}}}},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Access token from POST /v1/auth/login, /v1/auth/mfa/verify or /v1/auth/token. Scopes list the permission an operation requires."}}},"tags":[{"name":"operations","description":"Liveness, readiness and service metadata"},{"name":"auth","description":"Login, sessions, MFA and client credentials"},{"name":"users","description":"Staff, field agent and partner user accounts"},{"name":"api-clients","description":"Machine clients (OAuth2 client credentials)"},{"name":"audit","description":"The append-only audit log"},{"name":"reference","description":"Admin areas, crops, zones, calendars, seasons, units and inputs"},{"name":"maps","description":"Vector tiles"},{"name":"farmers","description":"Farmer registry: identity, identifiers, phones, household, location, duplicates"},{"name":"farms","description":"Farms, plots, geometry checks and visits"},{"name":"agriculture","description":"Crop cycles, inputs, harvests, plausibility flags, perennial stands and production history"},{"name":"consent","description":"Farmers' consent records"},{"name":"finance","description":"Sales, expenses, financing, repayments, savings, mobile money and financial indicators"},{"name":"provenance","description":"Claims, their sources, evidence and history"}]}