This is Umay Ana's proposed Institutional API Specification v1: a technical reference for how banks, insurers, reinsurers, MRV providers and green-finance partners could consume permissioned agricultural context without unrestricted access to the underlying farmer database.
The institution receives only fields required for an agreed purpose. Raw identifiers are replaced with partner-specific pseudonymous references wherever practical. Precise farm location can be reduced to region or district when exact coordinates are unnecessary. AI-derived values carry source/version metadata and remain distinguishable from farmer-entered observations or independently verified evidence.
POST/v1/partner-subject-mappingsPseudonymous partner subject mapping with purpose + consent reference.
GET/v1/farmer-context/{subjectRef}Normalized crop, geography, season and field context.
GET/v1/field-signalsCrop, weather, plant-health, weekly-plan and sustainability signals.
GET/v1/portfolios/{portfolioRef}/risk-contextAggregated portfolio crop, region, coverage and field-risk context.
GET/v1/insurance/claims/{claimRef}/triage-contextNon-decisional claim-prioritization context.
GET/v1/sustainability/{subjectRef}/evidenceRegenerative / Carbon Diary evidence.
GET/v1/mrv/{subjectRef}/readinessMethodology completeness and missing-field status; not certification.
GET/v1/metadata/data-dictionaryDictionary version and download metadata.
GET/v1/metadata/taxonomies/{taxonomy}Versioned crop, practice, evidence and signal taxonomies.
The draft uses OAuth 2.0 Client Credentials as the proposed B2B authentication model. Each institutional client receives only the scopes required for its integration.
The primary external identifier is partnerSubjectRef. It should be pseudonymous. The reference specification instructs partners not to transmit email, phone, national ID or other raw PII through the mapping request.
{
"partnerSubjectRef": "bank_farmer_123",
"purpose": "credit_monitoring",
"consentRef": "consent_contract_ref_001",
"expiresAt": "2027-08-29T00:00:00Z"
}{
"requestId": "req_01J...",
"generatedAt": "2026-08-29T16:30:00Z",
"apiVersion": "1.0.0-draft",
"dataAsOf": "2026-08-29T16:00:00Z",
"dataCoverage": 0.72,
"qualityStatus": "medium",
"decisionBoundary": "Contextual decision support only. This response must not be used as the sole basis for automatic credit approval/rejection, claim approval/rejection, underwriting, carbon certification or another high-impact institutional decision."
}GET/v1/farmer-context/{subjectRef} returns purpose-specific agricultural context. It does not return a credit score.
{
"subjectRef": "bank_farmer_123",
"context": {
"location": {
"countryCode": "TR",
"region": "Konya",
"district": "Cihanbeyli",
"locationPrecision": "district",
"parcelRef": null
},
"crop": {
"crop": "wheat",
"cropType": "annual_field_crop",
"seasonStage": "planting",
"plantingWindow": "2026-10-15/2026-11-15",
"harvestEstimate": "2027-07"
},
"weatherExposure": "normal",
"fieldRiskTrend": "stable",
"sustainabilityEvidenceCompleteness": 0.75
},
"meta": {
"requestId": "req_01J...",
"generatedAt": "2026-08-29T16:30:00Z",
"apiVersion": "1.0.0-draft",
"dataAsOf": "2026-08-29T16:00:00Z",
"dataCoverage": 0.72,
"qualityStatus": "medium",
"decisionBoundary": "Context only \u2014 not an automated credit decision."
}
}The portfolio endpoint is aggregated. It answers where crop concentration is high, what proportion has field-data coverage and where field-risk signals are changing rather than exposing raw app conversations.
{
"portfolioRef": "bank_agri_portfolio_01",
"summary": {
"subjects": 50000,
"dataCoverage": 0.64,
"cropConcentration": [
{
"crop": "wheat",
"share": 0.31
},
{
"crop": "cotton",
"share": 0.18
}
],
"regionalSignals": [
{
"region": "region_A",
"signal": "heat_watch",
"trend": "rising",
"coverage": 0.71
}
]
},
"decisionBoundary": "Descriptive portfolio context; not a regulated credit rating."
}Claim triage is deliberately non-decisional. The reference schema fixes automaticDecision to false.
{
"claimRef": "claim_abc123",
"triageContext": {
"recommendedAction": "additional_evidence_needed",
"weatherContext": "heat event in claim window",
"fieldObservationCount": 3,
"evidenceCoverage": 0.68,
"automaticDecision": false
},
"meta": {
"requestId": "req_01J...",
"generatedAt": "2026-08-29T16:30:00Z",
"apiVersion": "1.0.0-draft",
"dataCoverage": 0.68,
"qualityStatus": "medium",
"decisionBoundary": "Triage support only; policy wording and formal claims process remain authoritative."
}
}The MRV endpoint measures data readiness against a selected methodology. It can identify missing evidence; it cannot declare a carbon outcome certified.
{
"subjectRef": "green_farm_456",
"readiness": {
"status": "partial",
"completeness": 0.78,
"methodologyId": "partner_methodology_example",
"methodologyVersion": "v1",
"missingFields": [
"baseline_reference",
"soil_measurement_reference"
],
"externalValidationRequired": true
},
"meta": {
"requestId": "req_01J...",
"generatedAt": "2026-08-29T16:30:00Z",
"apiVersion": "1.0.0-draft",
"dataCoverage": 0.81,
"qualityStatus": "medium",
"decisionBoundary": "MRV readiness only; not carbon quantification or certification."
}
}/v1/field-signals can filter by subject, crop, region, signal type and time. Each signal carries evidence metadata distinguishing farmer-entered, AI-derived, external and verified sources.
| Element | V1 approach | Purpose |
|---|---|---|
| Pagination | Opaque cursor; max 500 records/page. | Stable large-portfolio iteration. |
| Trace ID | X-Request-Id + returned requestId. | Audit/support/reproducibility. |
| As-of time | Optional asOf. | Historical snapshots where retention permits. |
| Source version | Model/taxonomy version retained. | Historical interpretability. |
| 429 | Explicit rate-limit response. | Protect shared B2B infrastructure. |
| Purpose enforcement | OAuth scope + partner purpose + consent reference. | Purpose limitation. |
{
"code": "purpose_not_permitted",
"message": "Requested data is not permitted for this partner purpose.",
"requestId": "req_01J...",
"details": {
"requiredScope": "mrv:read"
}
}The draft proposes HMAC-SHA256 signing, idempotent event IDs and controlled retries. These are architecture targets, not active webhooks.
The proposed contract is path-versioned at /v1. Additive fields may remain in v1; breaking semantic changes should require a new API version or documented compatibility period.
The Agricultural Data Dictionary defines field meaning, source, status, sensitivity and use boundaries. The API defines who may receive which subset, under which purpose, through which endpoint.
Institutional API = who may receive which fields, through which endpoint, under which purpose, with which quality and decision boundaries.
The specification turns Umay Ana's institutional vision into a reviewable interface for pilot discussions.