openapi: 3.1.0
info:
  title: Granular Farm Management Activities Fields API
  description: Granular (Corteva Agriscience) Farm Management API provides access to farm operational data including fields, crops, planting records, harvest data, input applications, and financial analytics. The API enables integration with precision agriculture systems, input suppliers, and agricultural analytics platforms.
  version: 1.0.0
  contact:
    name: Granular Support
    url: https://granular.ag/
  license:
    name: Corteva Terms of Service
    url: https://www.corteva.com/
servers:
- url: https://api.granular.ag/v1
  description: Granular Production API
security:
- OAuth2:
  - read
  - write
tags:
- name: Fields
  description: Field boundary and attribute management
paths:
  /farms/{farmId}/fields:
    get:
      operationId: listFields
      summary: List fields for a farm
      description: Returns all fields associated with a farm including GeoJSON boundaries, soil data, and acreage.
      tags:
      - Fields
      parameters:
      - name: farmId
        in: path
        required: true
        schema:
          type: string
      - name: season
        in: query
        schema:
          type: integer
        description: Crop year/season to filter fields (e.g., 2024)
      responses:
        '200':
          description: Field list returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldList'
  /fields/{fieldId}:
    get:
      operationId: getField
      summary: Get field details
      description: Returns detailed information for a specific field including boundary geometry, soil type, FSA farm/tract/field numbers, and historical yield data.
      tags:
      - Fields
      parameters:
      - name: fieldId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Field details returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Field'
        '404':
          description: Field not found
components:
  schemas:
    FieldList:
      type: object
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/Field'
        total:
          type: integer
    Field:
      type: object
      properties:
        id:
          type: string
        farmId:
          type: string
        name:
          type: string
        acres:
          type: number
          description: Field acreage
        boundary:
          type: object
          description: GeoJSON polygon representing field boundary
          properties:
            type:
              type: string
              enum:
              - Feature
            geometry:
              type: object
              properties:
                type:
                  type: string
                  enum:
                  - Polygon
                  - MultiPolygon
                coordinates:
                  type: array
        fsaFarmNumber:
          type: string
          description: USDA FSA farm number
        fsaTractNumber:
          type: string
        fsaFieldNumber:
          type: string
        soilType:
          type: string
        predominantSoil:
          type: string
        irrigated:
          type: boolean
        createdAt:
          type: string
          format: date-time
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.granular.ag/oauth/authorize
          tokenUrl: https://auth.granular.ag/oauth/token
          scopes:
            read: Read farm data
            write: Write farm data
externalDocs:
  description: Granular Documentation
  url: https://granular.ag/