openapi: 3.0.3
info:
  title: Trimble Agriculture Data Boundaries Prescriptions 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: Prescriptions
paths:
  /organizations/{organizationId}/prescriptions:
    get:
      operationId: listPrescriptions
      summary: List Prescriptions
      description: Returns prescription files for an organization.
      tags:
      - Prescriptions
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: cropZoneId
        in: query
        schema:
          type: string
          format: uuid
        description: Filter by crop zone
      responses:
        '200':
          description: List of prescriptions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Prescription'
    post:
      operationId: createPrescription
      summary: Create Prescription
      description: Upload a prescription file to be sent to Trimble displays for variable-rate application in the field.
      tags:
      - Prescriptions
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PrescriptionInput'
      responses:
        '200':
          description: Prescription created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prescription'
  /organizations/{organizationId}/prescriptions/{prescriptionId}:
    get:
      operationId: getPrescriptionById
      summary: Get Prescription
      description: Retrieve a specific prescription file.
      tags:
      - Prescriptions
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: prescriptionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Prescription details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prescription'
    delete:
      operationId: deletePrescription
      summary: Delete Prescription
      description: Delete a prescription file.
      tags:
      - Prescriptions
      parameters:
      - name: organizationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: prescriptionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Prescription deleted
components:
  schemas:
    Prescription:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
          description: Prescription file name
        cropZoneId:
          type: string
          format: uuid
        materialType:
          type: string
          enum:
          - Seed
          - Fertilizer
          - Chemical
        fileUrl:
          type: string
          format: uri
        createdAt:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - Active
          - Sent
          - Archived
    PrescriptionInput:
      type: object
      required:
      - name
      - cropZoneId
      - materialType
      properties:
        name:
          type: string
        cropZoneId:
          type: string
          format: uuid
        materialType:
          type: string
          enum:
          - Seed
          - Fertilizer
          - Chemical
        prescription:
          description: GeoJSON variable-rate prescription data
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 bearer token. Register at agdeveloper.trimble.com to obtain API credentials.