openapi: 3.0.3
info:
  title: Trimble Agriculture Data Boundaries Imagery API
  description: The Trimble Agriculture Data API (PTxAg FarmENGAGE API) provides REST endpoints for managing farms, fields, crop zones, boundaries, equipment activities, work orders, prescriptions, materials, and imagery. Enables third-party integrators to exchange precision agriculture data between field devices and farm management platforms. Serves over 180 million customer acres globally. Access requires registration at the Trimble Ag Developer Network.
  version: 3.0.0
  contact:
    url: https://agdeveloper.trimble.com/
    email: ag_api@trimble.com
servers:
- url: https://cloud.api.trimble.com/Trimble-Ag-Software/externalApi/3.0
  description: Trimble Agriculture Cloud API
security:
- bearerAuth: []
tags:
- name: Imagery
paths:
  /organizations/{organizationId}/imagery:
    get:
      operationId: listImagery
      summary: List Imagery
      description: Returns uploaded GeoTIFF imagery processed for crop zones.
      tags:
      - Imagery
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: cropZoneId
        in: query
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: List of imagery records
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ImageryRecord'
    post:
      operationId: uploadImagery
      summary: Upload Imagery
      description: Upload a GeoTIFF image. It will be processed and clipped to any crop zones whose boundaries overlap the imagery area.
      tags:
      - Imagery
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: GeoTIFF image file
                name:
                  type: string
                  description: Image name
                date:
                  type: string
                  format: date
                  description: Date the imagery was captured
      responses:
        '200':
          description: Imagery uploaded and queued for processing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageryRecord'
components:
  schemas:
    ImageryRecord:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        date:
          type: string
          format: date
          description: Date imagery was captured
        status:
          type: string
          enum:
          - Processing
          - Processed
          - Failed
        cropZones:
          type: array
          items:
            type: string
            format: uuid
          description: Crop zones that overlap this imagery
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 bearer token. Register at agdeveloper.trimble.com to obtain API credentials.