openapi: 3.0.3
info:
  title: Trimble Agriculture Data Boundaries Equipment Activities 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: Equipment Activities
paths:
  /organizations/{organizationId}/equipmentactivities:
    get:
      operationId: listEquipmentActivities
      summary: List Equipment Activities
      description: Returns equipment activity records (in-field jobs such as planting, fertilizing, spraying, or harvesting) created from precision ag displays.
      tags:
      - Equipment Activities
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: startDate
        in: query
        schema:
          type: string
          format: date-time
        description: Filter activities starting after this time
      - name: endDate
        in: query
        schema:
          type: string
          format: date-time
        description: Filter activities ending before this time
      - name: cropZoneId
        in: query
        schema:
          type: string
          format: uuid
        description: Filter by crop zone
      - name: activityType
        in: query
        schema:
          type: string
          enum:
          - Planting
          - Fertilizing
          - Spraying
          - Harvesting
          - Tillage
          - Irrigation
        description: Filter by activity type
      responses:
        '200':
          description: List of equipment activities
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EquipmentActivity'
  /organizations/{organizationId}/equipmentactivities/{activityId}:
    get:
      operationId: getEquipmentActivityById
      summary: Get Equipment Activity
      description: Retrieve details and as-applied data for a specific equipment activity.
      tags:
      - Equipment Activities
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: activityId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Equipment activity details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EquipmentActivity'
  /organizations/{organizationId}/equipmentactivities/{activityId}/asapplied:
    get:
      operationId: getAsAppliedData
      summary: Get As-Applied Data
      description: Download as-applied data for a specific equipment activity in a format suitable for third-party analysis or regulatory compliance.
      tags:
      - Equipment Activities
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: activityId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - geojson
          - shapefile
        description: Download format
      responses:
        '200':
          description: As-applied data download
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsAppliedData'
components:
  schemas:
    EquipmentActivity:
      type: object
      required:
      - id
      - activityType
      properties:
        id:
          type: string
          format: uuid
        activityType:
          type: string
          enum:
          - Planting
          - Fertilizing
          - Spraying
          - Harvesting
          - Tillage
          - Irrigation
          description: Type of in-field operation
        cropZoneId:
          type: string
          format: uuid
        operatorId:
          type: string
          format: uuid
        equipmentId:
          type: string
          format: uuid
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
        area:
          type: number
          format: float
          description: Area covered in hectares
        materials:
          type: array
          items:
            type: object
            properties:
              materialId:
                type: string
                format: uuid
              applicationRate:
                type: number
                description: Application rate per unit area
              unit:
                type: string
        status:
          type: string
          enum:
          - InProgress
          - Completed
          - Cancelled
    AsAppliedData:
      type: object
      properties:
        activityId:
          type: string
          format: uuid
        format:
          type: string
        data:
          description: GeoJSON or other format data for as-applied records
        downloadUrl:
          type: string
          format: uri
          description: Presigned URL to download the full dataset
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 bearer token. Register at agdeveloper.trimble.com to obtain API credentials.