openapi: 3.0.3
info:
  title: Trimble Agriculture Data Boundaries Work Orders 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: Work Orders
paths:
  /organizations/{organizationId}/workorders:
    get:
      operationId: listWorkOrders
      summary: List Work Orders
      description: Returns work orders for an organization.
      tags:
      - Work Orders
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: status
        in: query
        schema:
          type: string
          enum:
          - Planned
          - Assigned
          - InProgress
          - Completed
          - Cancelled
        description: Filter by work order status
      responses:
        '200':
          description: List of work orders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkOrder'
    post:
      operationId: createWorkOrder
      summary: Create Work Order
      description: Create a work order to plan, assign, and communicate a job to farm equipment operators. Work orders can remotely preconfigure Precision-IQ Display tasks.
      tags:
      - Work Orders
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkOrderInput'
      responses:
        '200':
          description: Work order created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkOrder'
  /organizations/{organizationId}/workorders/{workOrderId}:
    get:
      operationId: getWorkOrderById
      summary: Get Work Order
      description: Retrieve details for a specific work order.
      tags:
      - Work Orders
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: workOrderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Work order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkOrder'
    put:
      operationId: updateWorkOrder
      summary: Update Work Order
      description: Update a work order's status or details.
      tags:
      - Work Orders
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: workOrderId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkOrderInput'
      responses:
        '200':
          description: Work order updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkOrder'
components:
  schemas:
    WorkOrderInput:
      type: object
      required:
      - title
      - cropZoneId
      - activityType
      properties:
        title:
          type: string
        description:
          type: string
        cropZoneId:
          type: string
          format: uuid
        assignedOperatorId:
          type: string
          format: uuid
        activityType:
          type: string
        scheduledDate:
          type: string
          format: date
        materials:
          type: array
          items:
            type: object
    WorkOrder:
      type: object
      required:
      - id
      - title
      - status
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
          description: Work order title or name
        description:
          type: string
        status:
          type: string
          enum:
          - Planned
          - Assigned
          - InProgress
          - Completed
          - Cancelled
        cropZoneId:
          type: string
          format: uuid
        assignedOperatorId:
          type: string
          format: uuid
        activityType:
          type: string
          description: Type of operation to perform
        scheduledDate:
          type: string
          format: date
        materials:
          type: array
          items:
            type: object
            properties:
              materialId:
                type: string
                format: uuid
              targetRate:
                type: number
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 bearer token. Register at agdeveloper.trimble.com to obtain API credentials.