openapi: 3.1.0
info:
  title: Umay Ana Institutional API
  version: 1.0.0-draft
  summary: Reference API contract for permissioned agricultural field intelligence.
  description: PROPOSED REFERENCE SPECIFICATION — NOT A LIVE PRODUCTION API. Defines B2B contracts for banks, insurers,
    reinsurers, MRV and green-finance partners.
  contact:
    email: enk@umay-ai.com
  license:
    name: Reference specification — commercial integration terms required
    url: https://umay-ai.com/en/institutional-api-specification
servers:
- url: https://api.umay-ai.com
  description: Proposed production hostname — illustrative until formally launched
components:
  securitySchemes:
    OAuth2ClientCredentials:
      type: oauth2
      description: Proposed B2B client-credentials model.
      flows:
        clientCredentials:
          tokenUrl: https://api.umay-ai.com/oauth2/token
          scopes:
            subject-map:write: Create/update partner pseudonymous subject mappings.
            farmer-context:read: Read permissioned farmer/farm agricultural context.
            field-signals:read: Read permissioned field signals.
            portfolio-risk:read: Read aggregated portfolio intelligence.
            insurance-triage:read: Read non-decisional claim-triage context.
            sustainability:read: Read permissioned sustainability evidence.
            mrv:read: Read MRV readiness and methodology-mapping status.
            metadata:read: Read dictionary, taxonomy and API metadata.
  parameters:
    RequestId:
      name: X-Request-Id
      in: header
      required: false
      schema:
        type: string
    AsOf:
      name: asOf
      in: query
      required: false
      schema:
        type: string
        format: date-time
    Cursor:
      name: cursor
      in: query
      required: false
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 100
  schemas:
    ResponseMeta:
      type: object
      required:
      - requestId
      - generatedAt
      - apiVersion
      - decisionBoundary
      properties:
        requestId:
          type: string
        generatedAt:
          type: string
          format: date-time
        apiVersion:
          type: string
          example: 1.0.0-draft
        dataAsOf:
          type:
          - string
          - 'null'
          format: date-time
        dataCoverage:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 1
        qualityStatus:
          type:
          - string
          - 'null'
          enum:
          - high
          - medium
          - low
          - insufficient
          - null
        decisionBoundary:
          type: string
          example: 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.
    Error:
      type: object
      required:
      - code
      - message
      - requestId
      properties:
        code:
          type: string
        message:
          type: string
        requestId:
          type: string
        details:
          type:
          - object
          - 'null'
          additionalProperties: true
    EvidenceDescriptor:
      type: object
      properties:
        status:
          type: string
          enum:
          - recommended
          - self_recorded
          - evidence_attached
          - digitally_corroborated
          - externally_validated
          - quantified
          - certified
        sourceType:
          type: string
          enum:
          - farmer_entered
          - system
          - ai_derived
          - weather_provider
          - remote_sensing
          - laboratory
          - partner
          - verifier
          - certification_scheme
        sourceVersion:
          type:
          - string
          - 'null'
        confidence:
          type:
          - number
          - 'null'
          minimum: 0
          maximum: 1
        verificationRef:
          type:
          - string
          - 'null'
    LocationContext:
      type: object
      properties:
        countryCode:
          type:
          - string
          - 'null'
        region:
          type:
          - string
          - 'null'
        district:
          type:
          - string
          - 'null'
        locationPrecision:
          type:
          - string
          - 'null'
        parcelRef:
          type:
          - string
          - 'null'
    CropContext:
      type: object
      properties:
        crop:
          type:
          - string
          - 'null'
        cropType:
          type:
          - string
          - 'null'
        seasonStage:
          type:
          - string
          - 'null'
        plantingWindow:
          type:
          - string
          - 'null'
        harvestEstimate:
          type:
          - string
          - 'null'
    SubjectMappingRequest:
      type: object
      required:
      - partnerSubjectRef
      - purpose
      - consentRef
      properties:
        partnerSubjectRef:
          type: string
          description: Pseudonymous partner reference; do not send raw PII.
        purpose:
          type: string
          enum:
          - credit_origination
          - credit_monitoring
          - insurance_monitoring
          - claim_triage
          - mrv
          - green_finance
          - program_monitoring
        consentRef:
          type: string
        expiresAt:
          type:
          - string
          - 'null'
          format: date-time
    SubjectMappingResponse:
      type: object
      properties:
        mappingId:
          type: string
        partnerSubjectRef:
          type: string
        status:
          type: string
          enum:
          - active
          - pending
          - revoked
          - expired
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    FarmerContextResponse:
      type: object
      properties:
        subjectRef:
          type: string
        context:
          type: object
          properties:
            location:
              $ref: '#/components/schemas/LocationContext'
            crop:
              $ref: '#/components/schemas/CropContext'
            weatherExposure:
              type:
              - string
              - 'null'
            fieldRiskTrend:
              type:
              - string
              - 'null'
            sustainabilityEvidenceCompleteness:
              type:
              - number
              - 'null'
              minimum: 0
              maximum: 1
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    FieldSignal:
      type: object
      properties:
        signalId:
          type: string
        subjectRef:
          type:
          - string
          - 'null'
        signalType:
          type: string
        crop:
          type:
          - string
          - 'null'
        region:
          type:
          - string
          - 'null'
        observedAt:
          type: string
          format: date-time
        severity:
          type:
          - string
          - 'null'
        payload:
          type: object
          additionalProperties: true
        evidence:
          $ref: '#/components/schemas/EvidenceDescriptor'
    FieldSignalsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FieldSignal'
        nextCursor:
          type:
          - string
          - 'null'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    PortfolioRiskResponse:
      type: object
      properties:
        portfolioRef:
          type: string
        summary:
          type: object
          additionalProperties: true
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    ClaimTriageContextResponse:
      type: object
      properties:
        claimRef:
          type: string
        triageContext:
          type: object
          properties:
            recommendedAction:
              type: string
            weatherContext:
              type:
              - string
              - 'null'
            fieldObservationCount:
              type: integer
            evidenceCoverage:
              type: number
              minimum: 0
              maximum: 1
            automaticDecision:
              type: boolean
              const: false
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    SustainabilityEvidenceResponse:
      type: object
      properties:
        subjectRef:
          type: string
        records:
          type: array
          items:
            type: object
            additionalProperties: true
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    MRVReadinessResponse:
      type: object
      properties:
        subjectRef:
          type: string
        readiness:
          type: object
          properties:
            status:
              type: string
              enum:
              - not_started
              - partial
              - ready_for_partner_review
              - externally_validated
              - certified
            completeness:
              type: number
              minimum: 0
              maximum: 1
            methodologyId:
              type:
              - string
              - 'null'
            methodologyVersion:
              type:
              - string
              - 'null'
            missingFields:
              type: array
              items:
                type: string
            externalValidationRequired:
              type: boolean
              const: true
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    DictionaryMetadataResponse:
      type: object
      properties:
        version:
          type: string
        fieldCount:
          type: integer
        downloadUrls:
          type: object
          additionalProperties: true
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    TaxonomyResponse:
      type: object
      properties:
        taxonomy:
          type: string
        version:
          type: string
        items:
          type: array
          items:
            type: object
            additionalProperties: true
        meta:
          $ref: '#/components/schemas/ResponseMeta'
security:
- OAuth2ClientCredentials: []
paths:
  /v1/partner-subject-mappings:
    post:
      tags:
      - Identity & Consent
      summary: Create pseudonymous partner subject mapping
      operationId: createPartnerSubjectMapping
      security:
      - OAuth2ClientCredentials:
        - subject-map:write
      parameters:
      - $ref: '#/components/parameters/RequestId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubjectMappingRequest'
      responses:
        '200':
          description: Mapping created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubjectMappingResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Purpose/scope not permitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/farmer-context/{subjectRef}:
    get:
      tags:
      - Farmer Context
      summary: Get normalized agricultural context
      operationId: getFarmerContext
      security:
      - OAuth2ClientCredentials:
        - farmer-context:read
      parameters:
      - name: subjectRef
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/RequestId'
      - $ref: '#/components/parameters/AsOf'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FarmerContextResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Purpose/scope not permitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/field-signals:
    get:
      tags:
      - Field Signals
      summary: List permissioned field signals
      operationId: listFieldSignals
      security:
      - OAuth2ClientCredentials:
        - field-signals:read
      parameters:
      - name: subjectRef
        in: query
        required: false
        schema:
          type: string
      - name: signalType
        in: query
        required: false
        schema:
          type: string
      - name: crop
        in: query
        required: false
        schema:
          type: string
      - name: region
        in: query
        required: false
        schema:
          type: string
      - name: from
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        required: false
        schema:
          type: string
          format: date-time
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldSignalsResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Purpose/scope not permitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/portfolios/{portfolioRef}/risk-context:
    get:
      tags:
      - Portfolio Intelligence
      summary: Get aggregated agricultural portfolio risk context
      operationId: getPortfolioRiskContext
      security:
      - OAuth2ClientCredentials:
        - portfolio-risk:read
      parameters:
      - name: portfolioRef
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/AsOf'
      - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortfolioRiskResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Purpose/scope not permitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/insurance/claims/{claimRef}/triage-context:
    get:
      tags:
      - Insurance
      summary: Get non-decisional agricultural claim-triage context
      operationId: getClaimTriageContext
      security:
      - OAuth2ClientCredentials:
        - insurance-triage:read
      parameters:
      - name: claimRef
        in: path
        required: true
        schema:
          type: string
      - name: subjectRef
        in: query
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimTriageContextResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Purpose/scope not permitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/sustainability/{subjectRef}/evidence:
    get:
      tags:
      - Sustainability & MRV
      summary: Get sustainability practice evidence
      operationId: getSustainabilityEvidence
      security:
      - OAuth2ClientCredentials:
        - sustainability:read
      parameters:
      - name: subjectRef
        in: path
        required: true
        schema:
          type: string
      - name: practiceCategory
        in: query
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SustainabilityEvidenceResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Purpose/scope not permitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/mrv/{subjectRef}/readiness:
    get:
      tags:
      - Sustainability & MRV
      summary: Get methodology-specific MRV readiness
      operationId: getMRVReadiness
      security:
      - OAuth2ClientCredentials:
        - mrv:read
      parameters:
      - name: subjectRef
        in: path
        required: true
        schema:
          type: string
      - name: methodologyId
        in: query
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MRVReadinessResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Purpose/scope not permitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/metadata/data-dictionary:
    get:
      tags:
      - Metadata
      summary: Get Agricultural Data Dictionary metadata
      operationId: getDataDictionaryMetadata
      security:
      - OAuth2ClientCredentials:
        - metadata:read
      parameters:
      - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DictionaryMetadataResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Purpose/scope not permitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/metadata/taxonomies/{taxonomy}:
    get:
      tags:
      - Metadata
      summary: Get versioned institutional taxonomy
      operationId: getTaxonomy
      security:
      - OAuth2ClientCredentials:
        - metadata:read
      parameters:
      - name: taxonomy
        in: path
        required: true
        schema:
          type: string
      - name: version
        in: query
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/RequestId'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxonomyResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Purpose/scope not permitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
x-umay-proposed-webhooks:
  description: Illustrative future events; not active.
  events:
  - field_signal.created
  - field_signal.updated
  - risk_cluster.changed
  - sustainability_evidence.updated
  - mrv_readiness.changed
  delivery:
    signature: HMAC-SHA256 proposed
    idempotency: eventId
    retry: controlled retries proposed
x-umay-data-governance:
  pii_default: No raw PII in institutional payloads by default.
  subject_identity: Partner-specific pseudonymous references.
  purpose_limitation: Scopes + partner permissions.
  location_policy: Least precise location necessary.
  decision_boundary: 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.
  auditability: Request IDs, provenance and source versions should be retained.