A Plant Health Diagnosis API: One Image In, Structured JSON Out

PlantLab’s plant health diagnosis API accepts a plant photo and returns structured JSON. A garden app can display the result. A greenhouse system can attach it to an observation record. An AI agent can read the same contract before it sends a request.

Tomato and cannabis diagnosis are available, with different coverage and fields. This example uses tomato. Every response states its schema version in schema_version.

Send one tomato photo

Create an API key in your PlantLab dashboard. Keep the key on your server or in a local environment variable, outside browser code and source control. Set PLANTLAB_API_KEY in your shell before running this command. Replace tomato.jpg with your photo path.

curl --fail-with-body https://api.plantlab.ai/diagnose \
  -H "X-API-Key: ${PLANTLAB_API_KEY}" \
  -F "image=@tomato.jpg"

The request uses multipart form data with a file field named image. The direct API accepts JPEG and PNG, with a documented 10 MB upload limit. It uses X-API-Key, not bearer authentication.

Read the response before displaying a diagnosis

This illustrative response comes from the OpenAPI example. Its confidence values are examples, not measured performance or a live diagnosis. Your response can show a newer schema_version.

{
  "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",
          "confidence": 0.7
        }
      ],
      "pests": []
    }
  ]
}

Read schema_version, success, species, and in_scope before interpreting results. For an unrecognized species, the API returns species: null, in_scope: false, and an empty results array. That response is not a healthy verdict. Mixed-species diagnosis in one photo is not supported.

Each result includes a normalized bbox, a rectangle expressed as fractions of the image dimensions. An unhealthy tomato result names one cause in conditions or pests. This response format does not establish that the plant has only one problem.

Treat a missing health field as unknown. A suspected: true result describes a suspected condition, not a healthy plant. Read confidence with the diagnosis and compare the result with the plant before treatment.

Fields differ by species and can change between schema versions. Make your parser accept a missing optional field. Read the current API reference for the field list. Some unhealthy cannabis results include an optional reliability estimate in reliability_score. It differs from condition confidence and does not guarantee correctness.

Keep errors separate from plant health

Store request_id and the X-Request-ID response header with your application record. They identify the request for feedback and support.

Read the HTTP status before parsing a successful diagnosis. Authentication failures need a valid key. Invalid uploads need a corrected file. For 429, honor Retry-After before attempting another request. A server error does not describe the plant’s health.

Avoid blind retries after a connection timeout. The service can finish a request even when your client does not receive its response. A repeated diagnosis can consume another unit of allowance. An agent must keep that cost visible to its user.

Give agents a direct route to the contract

The agent quickstart explains authentication and response handling. The OpenAPI JSON describes endpoints and schemas. The Arazzo workflow describes API call sequences, and llms.txt points to the public references.

Read those resources before constructing a call. Do not infer endpoint names or request fields from a blog example. Extra fields can be added over time, so parse defensively and inspect the schema version.

For assistants that use MCP, an interface for calling external tools, the PlantLab MCP guide explains its separate authentication and photo-transfer requirements. Its photo limit differs from the direct API limit.

Build around an inspection decision

A useful first integration shows the photo, predicted condition, and confidence together, then asks a person to inspect the plant. Keep your own watering, weather, and sensor records beside that result. The photo endpoint does not accept those records as diagnosis inputs.

Start with the supported tomato diagnoses and the current API documentation. Submit a photo that the user selected, preserve an uncertain answer, and keep treatment decisions separate from the prediction.