# Generated from openapi.json by scripts/openapi-yaml.mjs. Edit openapi.json, then run npm run openapi:yaml.
openapi: 3.1.0
info:
  title: PlantLab Public API
  version: 4.2.0
  summary: Public HTTP API for plant diagnosis and feedback submission.
  description: Canonical machine-readable contract for external PlantLab integrations. Third-party agents should integrate directly with https://api.plantlab.ai using X-API-Key.
servers:
  - url: https://api.plantlab.ai
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /health:
    get:
      summary: Health check
      security: []
      responses:
        "200":
          description: Service health
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                required:
                  - status
              examples:
                healthy:
                  value:
                    status: healthy
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "429":
          description: Rate limit exceeded (RATE_LIMIT_EXCEEDED)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
            Retry-After:
              $ref: "#/components/headers/RetryAfter"
            X-RateLimit-Limit:
              $ref: "#/components/headers/XRateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/XRateLimitRemaining"
  /info:
    get:
      summary: API metadata and capabilities
      responses:
        "200":
          description: API info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InfoResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "401":
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "429":
          description: Rate limit exceeded (RATE_LIMIT_EXCEEDED)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
            Retry-After:
              $ref: "#/components/headers/RetryAfter"
            X-RateLimit-Limit:
              $ref: "#/components/headers/XRateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/XRateLimitRemaining"
        "503":
          description: Authentication service unavailable (SERVICE_UNAVAILABLE).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
  /diagnose:
    post:
      summary: Diagnose plant health from an uploaded image
      description: Returns plant-health results for the primary photo. The optional secondary photo does not change the diagnosis. The service is currently free. Images are not retained. Diagnosis history is optional and does not include photos.
      x-codeSamples:
        - lang: Shell
          label: One photo
          source: 'curl https://api.plantlab.ai/diagnose -H "X-API-Key: $PLANTLAB_API_KEY" -F "image=@primary.jpg"'
        - lang: Shell
          label: Two photos
          source: 'curl https://api.plantlab.ai/diagnose -H "X-API-Key: $PLANTLAB_API_KEY" -F "image=@primary.jpg" -F "image_secondary=@secondary.jpg"'
      parameters: []
      requestBody:
        required: true
        description: Send exactly one image file and at most one image_secondary file. Files must be JPEG or PNG and have different content when two are supplied. Both files share the configured request body limit (32 MB by default, including multipart overhead). The API downscales a photo larger than 8192 pixels on a side or 50 million pixels to fit, and downscales both photos when together they exceed 50 million pixels. It rejects a photo larger than 32768 pixels on a side or 200 million pixels. Invalid or repeated image fields are rejected before diagnosis quota is consumed.
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                  description: Primary photo used for the returned diagnosis.
                image_secondary:
                  type: string
                  format: binary
                  description: Optional second photo of the same plant. It does not change the returned diagnosis. Images are not retained.
                installation_id:
                  type: string
                  maxLength: 256
                  description: Optional identifier for the installation or device submitting this request. Availability and limits depend on account access.
              required:
                - image
      responses:
        "200":
          description: Diagnosis result (schema_version 4.2.0). Image-level fields (species, species_name, species_confidence, in_scope, routed_reason, engine_version) are top-level. Cannabis and tomato diagnoses are returned in results[]. An unknown species, or a photo too blurry to read (routed_reason blurry_photo), has no diagnosed plants. results[] can still list plants that were left out for blur, shape, or size, each with a bbox, a routed_reason, and no diagnosis, so read every entry that has a routed_reason. See openapi.json for the full DiagnoseResponse schema.
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DiagnoseResponse"
              examples:
                cannabis:
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    schema_version: 4.2.0
                    engine_version:
                      api: 1.0.179
                    success: true
                    species: cannabis
                    species_name: Cannabis sativa
                    species_confidence: 0.95
                    in_scope: true
                    routed_reason: null
                    results:
                      - bbox:
                          x0: 0
                          y0: 0
                          x1: 1
                          y1: 1
                          normalized: true
                        is_healthy: false
                        health_confidence: 0.85
                        growth_stage: flowering
                        growth_stage_confidence: 0.9
                        conditions:
                          - class_id: nitrogen_deficiency
                            confidence: 0.85
                            coarse_group: mobile_nutrient
                            display_name: Nitrogen Deficiency
                        reliability_score: 0.87
                  summary: Cannabis diagnosis (illustrative values)
                tomato:
                  summary: Tomato diagnosis (illustrative values)
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    schema_version: 4.2.0
                    success: true
                    species: tomato
                    species_name: Solanum lycopersicum
                    species_confidence: 0.95
                    in_scope: true
                    routed_reason: null
                    results:
                      - bbox:
                          x0: 0
                          y0: 0
                          x1: 1
                          y1: 1
                          normalized: true
                        is_healthy: false
                        health_confidence: 0.2
                        conditions:
                          - class_id: early_blight
                            display_name: Early blight
                            confidence: 0.7
                unknown:
                  summary: Unrecognized species
                  value:
                    request_id: 550e8400-e29b-41d4-a716-446655440000
                    schema_version: 4.2.0
                    success: true
                    species: null
                    species_name: null
                    species_confidence: null
                    in_scope: false
                    routed_reason: unknown_species
                    results: []
        "400":
          description: Invalid upload or image. Codes include FILE_UPLOAD_ERROR, FILE_TOO_LARGE, INVALID_FORMAT, INSTALLATION_ID_TOO_LONG and DUPLICATE_CAPTURE_IMAGE.
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "403":
          description: installation_id is not available for this account (INSTALLATION_ID_TIER_REQUIRED), or the account reached its installation limit (INSTALLATION_ID_CAP_REACHED).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "408":
          description: Inference timeout (INFERENCE_TIMEOUT)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "413":
          description: Request body larger than the configured limit (FILE_TOO_LARGE)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Rate limit exceeded (RATE_LIMIT_EXCEEDED), or the daily or monthly diagnosis limit is used up (DAILY_LIMIT_EXCEEDED, MONTHLY_LIMIT_EXCEEDED).
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
            Retry-After:
              $ref: "#/components/headers/RetryAfter"
            X-RateLimit-Limit:
              $ref: "#/components/headers/XRateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/XRateLimitRemaining"
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: "#/components/schemas/UsageRateLimitErrorResponse"
                  - $ref: "#/components/schemas/ErrorResponse"
              examples:
                daily_limit:
                  summary: Daily diagnosis limit used up
                  value:
                    success: false
                    error: Daily limit of 3 requests exceeded
                    code: DAILY_LIMIT_EXCEEDED
                    retryAfter: 43200
                    limitType: daily
                    limit: 3
                    used: 3
        "500":
          description: Server error. Codes include INFERENCE_ERROR, PREPROCESSING_ERROR and INTERNAL_ERROR.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "503":
          description: "Service unavailable. SERVICE_UNAVAILABLE: authentication is unavailable, or the service is at capacity. USAGE_CHECK_UNAVAILABLE: the usage check failed. Retry later."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
  /usage:
    get:
      summary: Get current API usage for the authenticated user
      description: Returns daily and monthly diagnosis usage for the API key owner, including counts used, configured limits, remaining quota, and period boundaries. This endpoint is read-only and does not consume quota.
      responses:
        "200":
          description: Daily and monthly usage with limits and period info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsageResponse"
              examples:
                usage:
                  value:
                    success: true
                    tier: free
                    usage:
                      daily:
                        used: 2
                        limit: 3
                        remaining: 1
                        period_start: 2026-04-20
                        period_end: 2026-04-20
                        resets_at: 2026-04-21T00:00:00Z
                      monthly:
                        used: 12
                        limit: 90
                        remaining: 78
                        period_start: 2026-04-01
                        period_end: 2026-04-30
                        resets_at: 2026-05-01T00:00:00Z
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "401":
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "429":
          description: Rate limit exceeded (RATE_LIMIT_EXCEEDED)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
            Retry-After:
              $ref: "#/components/headers/RetryAfter"
            X-RateLimit-Limit:
              $ref: "#/components/headers/XRateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/XRateLimitRemaining"
        "503":
          description: Usage service unavailable (USAGE_CHECK_UNAVAILABLE), or authentication unavailable (SERVICE_UNAVAILABLE).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
  /history:
    get:
      summary: Retrieve paginated diagnosis history
      description: Returns stored diagnosis results when diagnosis history is enabled for the account. The service is currently free. History does not include photos. History availability and result limits depend on account access.
      parameters:
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Opaque pagination cursor. Pass back the previous response's next_cursor value to fetch the next page. When cursor is present, the since parameter is ignored.
        - name: since
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: RFC3339 timestamp. Only records created after this time are returned. If omitted or earlier than the tier window start, the full retention window is used. Ignored when cursor is also present.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 100
          description: Maximum number of records to return. Clamped to the tier maximum (bounded by account access). Defaults to 100.
        - name: installation_id
          in: query
          required: false
          schema:
            type: string
          description: Filter results to records tagged with this installation identifier. If omitted, all records within the window are returned.
      responses:
        "200":
          description: Paginated history records
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HistoryResponse"
              examples:
                history_page:
                  value:
                    items:
                      - id: 1042
                        request_id: 550e8400-e29b-41d4-a716-446655440000
                        installation_id: ha-instance-001
                        class_id: nitrogen_deficiency
                        confidence: 0.85
                        species: cannabis
                        species_confidence: 0.95
                        in_scope: true
                        routed_reason: null
                        is_healthy: false
                        growth_stage: flowering
                        growth_stage_confidence: 0.9
                        conditions:
                          - class_id: nitrogen_deficiency
                            confidence: 0.85
                        pests: []
                        engine_version: 1.0.179
                        created_at: 2026-05-08T12:00:00Z
                    count: 1
                    next_cursor: eyJ0IjoiMjAyNi0wNS0wOFQxMjowMDowMFoiLCJpZCI6MTA0Mn0
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "400":
          description: Invalid cursor value. The body holds only the error field.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CursorErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "401":
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "403":
          description: History is not available for this account (HISTORY_NOT_AVAILABLE).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "429":
          description: History rate limit exceeded (RATE_LIMIT_EXCEEDED)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
            Retry-After:
              $ref: "#/components/headers/RetryAfter"
            X-RateLimit-Limit:
              $ref: "#/components/headers/XRateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/XRateLimitRemaining"
        "500":
          description: Server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "503":
          description: History service unavailable (CRYPTO_NOT_CONFIGURED), or authentication unavailable (SERVICE_UNAVAILABLE).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
  /feedback:
    post:
      summary: Submit feedback for a prior diagnose response
      description: Submits accuracy feedback for a previously issued request_id. The request_id MUST belong to the authenticated caller; feedback for another user's request_id is rejected with 404 REQUEST_NOT_FOUND. The same response is returned whether the request_id was never issued, was issued to a different user, or has aged out of the 30-day retention window — clients cannot use this endpoint to enumerate request IDs.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FeedbackRequest"
      responses:
        "201":
          description: Feedback stored
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FeedbackResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "400":
          description: Invalid request body or request_id, or an oversized diagnosis_result. Codes include INVALID_REQUEST, MISSING_FIELD, INVALID_REQUEST_ID and PAYLOAD_TOO_LARGE.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "401":
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "404":
          description: request_id not found for the authenticated caller (REQUEST_NOT_FOUND). Same response when the id was never issued, was issued to a different user, or aged out.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "429":
          description: Rate limit exceeded (RATE_LIMIT_EXCEEDED)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
            Retry-After:
              $ref: "#/components/headers/RetryAfter"
            X-RateLimit-Limit:
              $ref: "#/components/headers/XRateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/XRateLimitRemaining"
        "500":
          description: Feedback was not saved. Codes include DATABASE_ERROR and MARSHAL_ERROR.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
        "503":
          description: Feedback service or authentication unavailable (SERVICE_UNAVAILABLE).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          headers:
            X-Request-ID:
              $ref: "#/components/headers/XRequestId"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  headers:
    XRequestId:
      description: Request correlation identifier. Every response has it except a 413, which the server rejects before it assigns one. On /diagnose it is the request_id in the response body. On other routes it repeats the X-Request-ID request header when the client sends one of at most 64 characters from A-Za-z0-9._-, and is generated otherwise.
      schema:
        type: string
    RetryAfter:
      description: Number of seconds the client should wait before retrying.
      schema:
        type: integer
    XRateLimitLimit:
      description: Requests per minute allowed on this route. Sent with RATE_LIMIT_EXCEEDED.
      schema:
        type: integer
    XRateLimitRemaining:
      description: Requests left in the current minute. Always 0 when sent with RATE_LIMIT_EXCEEDED.
      schema:
        type: integer
  schemas:
    ErrorResponse:
      type: object
      properties:
        request_id:
          type: string
          description: Present on /diagnose errors.
        success:
          type: boolean
        error:
          type: string
        code:
          type: string
      required:
        - success
        - error
    HistoryItem:
      type: object
      required:
        - id
        - request_id
        - class_id
        - confidence
        - species
        - species_confidence
        - in_scope
        - routed_reason
        - conditions
        - pests
        - engine_version
        - created_at
      properties:
        id:
          type: integer
          format: int64
        request_id:
          type: string
        installation_id:
          type: string
        class_id:
          type: string
        confidence:
          type: number
          format: double
        species:
          type:
            - string
            - "null"
          description: Detected species ID. Known values are cannabis and tomato. Any other ID that matches ^[a-z][a-z0-9_]*$ is a valid species.
        species_confidence:
          type:
            - number
            - "null"
        in_scope:
          type: boolean
        routed_reason:
          type:
            - string
            - "null"
          enum:
            - unknown_species
            - blurry_photo
            - null
        is_healthy:
          type: boolean
        growth_stage:
          type: string
        growth_stage_confidence:
          type: number
          format: double
        conditions:
          type: array
          items:
            $ref: "#/components/schemas/HistoryCondition"
        pests:
          type: array
          items:
            $ref: "#/components/schemas/HistoryCondition"
        nutrient_analysis:
          type: object
          additionalProperties: true
          description: Absent when no analysis is stored.
        engine_version:
          type: string
        created_at:
          type: string
          format: date-time
    HistoryResponse:
      type: object
      required:
        - items
        - count
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/HistoryItem"
        count:
          type: integer
        next_cursor:
          type: string
          description: Opaque cursor; absent on the last page. Pass as ?cursor= to fetch the next page.
    UsageRateLimitErrorResponse:
      allOf:
        - $ref: "#/components/schemas/ErrorResponse"
        - type: object
          properties:
            retryAfter:
              type: integer
            limitType:
              type: string
              enum:
                - daily
                - monthly
            limit:
              type: integer
            used:
              type: integer
          required:
            - retryAfter
            - limitType
            - limit
            - used
    ClassPrediction:
      type: object
      properties:
        class_id:
          type: string
        display_name:
          type: string
          description: Readable name of the predicted condition or pest.
        confidence:
          type: number
        suspected:
          type: boolean
          description: True when the prediction is a weak or early signal. Treat it as low confidence and monitor the plant, whatever the confidence value says.
        coarse_group:
          type: string
          description: Clinical coarse group of class_id (mobile_nutrient, immobile_newgrowth, water, light, fungal_disease, pest). Additive hedging signal for confusable fine classes; omitted for an unmapped class.
          enum:
            - mobile_nutrient
            - immobile_newgrowth
            - water
            - light
            - fungal_disease
            - pest
      required:
        - class_id
        - display_name
        - confidence
    MuldersHypothesis:
      type: object
      properties:
        excess:
          type: string
        explains:
          type: array
          items:
            type: string
        evidence:
          type: number
        evidence_count:
          type: integer
      required:
        - excess
        - explains
        - evidence
        - evidence_count
    DiagnoseResponse:
      type: object
      properties:
        request_id:
          type: string
          format: uuid
        schema_version:
          type: string
        engine_version:
          type: object
          description: Version of the service that produced this diagnosis. Compare it for equality to detect a change, for example to invalidate a cache. Optional; absent on older builds.
          properties:
            api:
              type: string
              description: Deployed API build version (matches GET /info).
          required:
            - api
        success:
          type: boolean
        species:
          type:
            - string
            - "null"
          description: Detected species ID. Known values are cannabis and tomato. Treat any other ID that matches ^[a-z][a-z0-9_]*$ as a valid species. Null when no supported species is detected.
        species_name:
          type:
            - string
            - "null"
          description: Scientific name of the detected species, for example Solanum lycopersicum. Null when no species is detected.
        species_confidence:
          type:
            - number
            - "null"
          description: Confidence in the detected species. Null when species is null. Quantized to 5% steps.
        in_scope:
          type: boolean
          description: True when the API detects a supported species.
        routed_reason:
          type:
            - string
            - "null"
          enum:
            - unknown_species
            - blurry_photo
            - null
          description: "Reason the photo got no diagnosis. unknown_species: no supported plant was found. blurry_photo: the photo is too blurry to read, so no plant was diagnosed (no plant is diagnosed; ask the user for a sharper photo). Null when a species is detected."
        results:
          type: array
          description: One diagnosis per diagnosed plant. Cannabis and tomato diagnoses appear here. Has no diagnosed plants when species is null. Can still list skipped plants, each with a bbox, a routed_reason, and no diagnosis. Iterate this array and read each entry.
          items:
            $ref: "#/components/schemas/PlantDiagnosis"
      required:
        - request_id
        - schema_version
        - success
        - species
        - species_name
        - species_confidence
        - in_scope
        - routed_reason
        - results
    BBoxNormalized:
      type: object
      description: The region of the image occupied by this plant, in normalized [0,1] coordinates (x0,y0 = top-left; x1,y1 = bottom-right). A whole-image / single-plant result is {0,0,1,1}. Multiply by the image width/height to draw the box.
      properties:
        x0:
          type: number
          minimum: 0
          maximum: 1
        y0:
          type: number
          minimum: 0
          maximum: 1
        x1:
          type: number
          minimum: 0
          maximum: 1
        y1:
          type: number
          minimum: 0
          maximum: 1
        normalized:
          type: boolean
          description: Always true; documents that the coordinates are normalized to [0,1].
      required:
        - x0
        - y0
        - x1
        - y1
        - normalized
    PlantDiagnosis:
      type: object
      description: Diagnosis for one detected plant. Cannabis results have health, growth stage, conditions, pests, reasoning layers and reliability_score; conditions, pests, reasoning layers and reliability_score appear only for an unhealthy plant. A tomato result has a health verdict, and no growth stage. An unhealthy tomato result names one cause in conditions or pests (spider mites and leaf miners are pests). Absent and empty conditions and pests arrays both mean none. health_confidence is present whenever is_healthy is present, including the value 0. It is the probability that the plant is healthy, so for an unhealthy verdict a low value means more confidence in the verdict. species repeats the species of the photo. The API does not identify a separate species for each plant, and mixed-species diagnosis in one photo is not supported. A plant of a species the API does not diagnose is listed with routed_reason and no diagnosis fields.
      properties:
        bbox:
          $ref: "#/components/schemas/BBoxNormalized"
        species:
          type: string
          description: Species of the photo, repeated on each plant, for example cannabis or tomato.
        routed_reason:
          type: string
          enum:
            - unknown_species
            - blurry_photo
            - extreme_aspect_ratio
            - plant_too_small
          description: "Present when the plant has no diagnosis. unknown_species: the plant is not one the API diagnoses. blurry_photo: the plant is too blurry to read. extreme_aspect_ratio: the plant shows as a long, thin strip. plant_too_small: the plant fills too little of the photo. A plant that is left out of a multi-plant photo keeps its bbox and this reason, and the other plants are still diagnosed. Count them to tell the user how many plants were skipped. The plant has no diagnosis fields."
        is_healthy:
          type: boolean
        health_confidence:
          type: number
        growth_stage:
          type: string
        growth_stage_confidence:
          type: number
        conditions:
          type: array
          items:
            $ref: "#/components/schemas/ClassPrediction"
        pests:
          type: array
          items:
            $ref: "#/components/schemas/ClassPrediction"
        mulders_hypotheses:
          type: array
          items:
            $ref: "#/components/schemas/MuldersHypothesis"
        reliability_score:
          type: number
          format: float
          minimum: 0
          maximum: 1
          description: Estimate of the reliability of this plant result. Available for some unhealthy cannabis results. Use it to route results for closer review. It differs from per-condition confidence and does not guarantee correctness.
        coarse_fallback:
          type: string
          enum:
            - mobile_nutrient
            - immobile_newgrowth
            - water
            - light
            - fungal_disease
            - pest
          description: "Abstention hedge: the clinical coarse group of this plant's top-1 condition/pest, emitted ONLY when that top-1 confidence is below the server's coarse-fallback threshold. Present means the fine class is uncertain and the coarse group is the more reliable read. Absent when the top-1 is confident. Prefer surfacing this group over asserting the exact fine class when it is present."
        uncertainty_factors:
          type: array
          items:
            type: string
        environmental_patterns:
          type: array
          items:
            $ref: "#/components/schemas/EnvironmentalPattern"
        progression_risks:
          type: array
          items:
            $ref: "#/components/schemas/ProgressionRisk"
        stage_advisories:
          type: array
          description: Guidance that ties a confirmed condition or pest to the plant's growth stage. Present only for an unhealthy cannabis plant, and only when the growth stage is certain.
          items:
            $ref: "#/components/schemas/StageAdvisory"
      required:
        - bbox
    FeedbackRequest:
      type: object
      properties:
        request_id:
          type: string
          format: uuid
        is_accurate:
          type: boolean
        diagnosis_result:
          type: object
          additionalProperties: true
          description: Optional copy of the diagnosis. At most 10240 bytes when serialized.
      required:
        - request_id
        - is_accurate
    FeedbackResponse:
      type: object
      properties:
        success:
          type: boolean
        feedback_id:
          type: string
          format: uuid
      required:
        - success
        - feedback_id
    InfoResponse:
      type: object
      properties:
        api:
          type: object
          properties:
            name:
              type: string
            version:
              type: string
          required:
            - name
            - version
        capabilities:
          type: object
          properties:
            image_formats:
              type: array
              items:
                type: string
            max_file_size_mb:
              type: integer
            species:
              type: array
              description: Species the API serves, with the condition class ids it can report for each. The ids include pests and exclude healthy.
              items:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  condition_class_ids:
                    type: array
                    items:
                      type: string
                required:
                  - id
                  - name
                  - condition_class_ids
          required:
            - image_formats
            - max_file_size_mb
            - species
      required:
        - api
        - capabilities
    CursorErrorResponse:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    EnvironmentalPattern:
      type: object
      properties:
        pattern:
          type: string
        trigger:
          type: array
          items:
            type: string
        hypothesis:
          type: string
      required:
        - pattern
        - trigger
        - hypothesis
    ProgressionRisk:
      type: object
      properties:
        confirmed:
          type: string
        risk:
          type: string
        mechanism:
          type: string
      required:
        - confirmed
        - risk
        - mechanism
    StageAdvisory:
      type: object
      properties:
        class_id:
          type: string
        stage:
          type: string
        advisory:
          type: string
      required:
        - class_id
        - stage
        - advisory
    HistoryCondition:
      type: object
      properties:
        class_id:
          type: string
        confidence:
          type: number
      required:
        - class_id
        - confidence
    UsagePeriodInfo:
      type: object
      properties:
        used:
          type: integer
        limit:
          type: integer
        remaining:
          type: integer
          description: Never below 0.
        period_start:
          type: string
          description: UTC date, YYYY-MM-DD.
        period_end:
          type: string
          description: UTC date, YYYY-MM-DD.
        resets_at:
          type: string
          format: date-time
      required:
        - used
        - limit
        - remaining
        - period_start
        - period_end
        - resets_at
    UsagePeriodsInfo:
      type: object
      properties:
        daily:
          $ref: "#/components/schemas/UsagePeriodInfo"
        monthly:
          $ref: "#/components/schemas/UsagePeriodInfo"
      required:
        - daily
        - monthly
    UsageResponse:
      type: object
      properties:
        success:
          type: boolean
        tier:
          type: string
        usage:
          $ref: "#/components/schemas/UsagePeriodsInfo"
      required:
        - success
        - tier
        - usage
