Crops API: Unified text and image retrieval for maize and rice

What is the Crops API?

The Crops API exposes FildraAI's two crop experts, maize and rice, through a single per-crop namespace. Each crop has four operations: text chat (passages from the knowledge base), text diagnose (multi-turn funnel over the KB), media search (reference images), and media diagnose (multi-turn funnel over the image library). Both diagnose funnels accept everyday descriptive language rather than agronomy terminology; when a query is too ambiguous to retrieve confidently the API asks one short clarifying question at a time.

The Crops API supersedes the legacy /api/v1/chat/message and /api/v1/media/{plant}/* routes. Those routes remain live during the migration window but return deprecation headers (see Deprecated routes below). New integrations should target /api/v1/crops/{plant}/* exclusively.

Authentication

All Crops API endpoints require a valid API key. Use the X-Api-Key header (Bearer tokens are also accepted):

X-Api-Key: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY

Text operations require the crop:search scope. Media operations require the media:search scope. Keys are issued per application from the FildraAI developer dashboard and can be scoped to a single crop (e.g. crop:maize) for tiered billing. Requests without a valid key return 401 Unauthorized; missing scope returns 403 Forbidden.

Endpoints

{plant} is currently one of maize or rice. Both crops use the same request and response envelopes; the underlying KB and image catalogue are crop-specific.

Acceptable use

Text chat, passage retrieval

POST /api/v1/crops/{plant}/chat retrieves the top-k most relevant knowledge-base passages for a natural-language query, scoped to the crop in the URL path. This is the right endpoint when you want curated reference content to display alongside a user question.

curl -X POST "https://api.fildraai.com/api/v1/crops/maize/chat" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "maize leaf blight",
    "locale": "en-us",
    "k": 6
  }'

Response includes ok, reply (short summary), docs[] (ranked passages with id, title, section, content, score), and a public meta block (plant, locale, k, build_id). Internal facet routing and oversample debug fields are stripped from the response.

Text diagnose, multi-turn funnel

POST /api/v1/crops/{plant}/diagnose runs a staged disambiguation flow. The first turn classifies the query into a symptom frame; if confidence is too low to commit to a diagnosis, the API returns one short clarifying question. Echo the returned session on the next turn with the farmer's answer added, and the funnel narrows. After three answers it commits regardless.

curl -X POST "https://api.fildraai.com/api/v1/crops/maize/diagnose" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "leaves turned brown and dried up",
    "locale": "en-us"
  }'

The MVP funnel asks at most three questions, in priority order:

1. Growth stage, seedling / vegetative / tillering or jointing / heading or flowering / grain fill / mature
2. Plant part, leaves / stalk or stem / sheath / panicle or tassel / roots / whole plant
3. Colour, yellow / orange rust / brown-tan / grey-white / black / purple-red

Media search, image retrieval

POST /api/v1/crops/{plant}/media/search retrieves annotated crop disease reference images by natural-language description. Useful for surfacing visual examples alongside text guidance, or for image-led browsing UIs.

curl -X POST "https://api.fildraai.com/api/v1/media/rice/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "yellowing leaves with brown spots near the base",
    "locale": "en-us",
    "k": 5,
    "include_scores": true
  }'

Media search, response schema

The intended successful search response returns a job-style result with matched image items. Production currently returns a 500 job creation error for search and diagnose routes, so treat this schema as the contract to use once the media queue path is healthy again.

{
  "ok": true,
  "count": 5,
  "items": [
    {
      "id": "img_abc123",
      "title": "Rice leaf blight reference image",
      "file": "rice_leaf_blight_001.jpg",
      "plant": "rice",
      "class": "bacterial_leaf_blight",
      "topic": "disease",
      "locale": "en-us",
      "score": 0.91,
      "media_download_url": "https://...",
      "tags": ["leaf", "lesion", "blight"],
      "category": "field",
      "image_group": "rice_blight_set_a"
    }
  ],
  "meta": {
    "query": "yellowing leaves with brown spots",
    "plant": "rice",
    "locale": "en-us",
    "took_ms": 124
  }
}

Each item in items represents a matched reference image. The score field is only present if include_scores was set to true in the request. Internal storage URLs are stripped from the response for security, use media_download_url to access the image.

Media diagnose, staged image funnel

The /diagnose endpoint runs a multi-turn disambiguation flow. Rather than immediately returning images, it may first ask one or more clarifying questions to narrow the search. This is useful when a description could match multiple disease classes.

Farmer language coverage

The funnel does not require a farmer to know plant-pathology vocabulary like lesion, whorl, or chlorotic. It maps everyday descriptive words to symptom groups, then uses those groups to score candidate diseases. The complete keyword table is below, use it to set client-side hints and example prompts.

What works today verified

These phrases were all correctly parsed into useful symptom frames during integration testing:

• "looks brown" → browning
• "starting to look yellow" → yellowing
• "I see brown spots" → spots + browning
• "the spots look like burn" → spots + burnt
• "powdery orange stuff on leaves" → powder + orange (low-ambiguity, retrieves immediately without follow-up questions)
• "lower leaves are wilting" → wilt + leaf_position=lower
• "tiny dots all over" → spots

Known gaps to plan around limitation

The current normaliser does whitespace tokenisation and exact keyword match, no stemming, no punctuation stripping. The following inputs return no symptom frame today and fall straight to action: "ask_question" with ambiguity: "very_high":

• Punctuation attached to a keyword: "brown." or "spots," are tokenised as "brown." / "spots," and miss the table.
• Inflected forms: "yellowish", "browner" are not in the synonym table. "yellowing" and "brown" do work.
• Disease names as keywords: "rust", "blight", "smut" are class names the funnel predicts, not inputs it recognises. Farmers using these are usually right, but the funnel will still ask a clarifying question.
• Vague distress phrases: "looks bad", "my plants are dying", "diseased" carry no physical detail. The funnel will ask the highest-value physical question first (raised vs flat).
• Hyphenated terms: "green-yellow" is one token and does not match yellow.

Client tip: lowercase the input and strip trailing punctuation before sending. For multi-sentence descriptions, send the most physical sentence (the one with colour/shape/texture words) for the best frame match.

Locale and language support

The locale parameter controls both the language of metadata returned and the search index used. If the requested locale is not available for the given crop, the API falls back to the closest available locale (usually en-us) and sets fallback_used: true in the response.

Deprecated routes

The three routes below are the legacy ancestors of the unified Crops API. They remain functional during the migration window but every successful response carries three RFC 8594 headers: Deprecation: true, Sunset: Mon, 31 Aug 2026 00:00:00 GMT, and Link: </api/v1/crops/{plant}/...>; rel="successor-version". After the Sunset date the legacy routes will return 410 Gone.

Error codes

The Media Search API returns standard HTTP status codes. Common error cases: