Crops API: One namespace for text knowledge, diagnostic funnels, and reference images
The Crops API is FildraAI's curated maize and rice expertise, exposed as four operations under a single per-crop URL. Send a natural-language question and get ranked KB passages. Send a vague farmer description and get a multi-turn disambiguation funnel that lands on a likely disease. Show users reference images by description. All four operations share one auth surface and one billing meter.
Four operations, one surface
Pick the operation that matches your user's need. All four are versioned under the same per-crop URL, return the same envelope shape, and share auth + billing.
Text chat
POST /api/v1/crops/{plant}/chat, send a natural-language question, receive top-k curated KB passages with source attribution. Right when the user knows what they want to read about.
Text diagnose
POST /api/v1/crops/{plant}/diagnose, send a vague farmer description, get a 1–3 question funnel that narrows toward a likely disease, then passages. Right when the user knows what they see but not what it is.
Media search
POST /api/v1/crops/{plant}/media/search, search the annotated reference image library by description. Right when the user wants to compare what they see in the field with documented examples.
Media diagnose
POST /api/v1/crops/{plant}/media/diagnose, the same disambiguation funnel as text diagnose, but it asks physical questions (raised vs flat, powder vs no powder, halo vs no halo) and returns matched reference images instead of passages.
Use cases beyond the obvious
The Crops API was built to power farmer-facing diagnostic flows, but the underlying surface, curated passages + image library + a funnel that asks plain-language questions, has reach beyond that. A few applications we have seen or expect:
Farmer-facing mobile apps
Embed text-diagnose and media-diagnose in your own UI. Echo the session object across turns; render the question card the API returns; show passages when it commits. Same surface our own apps use.
Agricultural education
Build courseware that pulls passages on demand for an extension student looking at a real plant. The funnel is itself a teaching loop, the questions it asks ("raised or flat?", "halo present?") are exactly the questions a trainee diagnostician needs to internalise.
Extension and advisory services
Give field extension officers a quick reference they can pull on a phone while standing in a farmer's field. Media search returns annotated images; text chat returns the management section without scrolling through a 200-page handbook.
Research datasets
Use the curated chunk metadata (disease, symptom tags, growth stage) to seed your own annotation work. The KB is a structured pivot from natural-language descriptions to disease ontology.
Co-branded chatbots
Wrap the Crops API in a partner-branded chatbot for an NGO, cooperative, or input supplier. Attribution is required (Powered by FildraAI) but the look and feel is yours.
Field-CRM integrations
When a field agent logs a visit in your CRM, automatically pull the relevant disease management passage based on what they recorded. The Crops API becomes the just-in-time reference layer.
What you get and what you don't
What's in the response
The answer or the next clarifying question, the same surface our own apps render. Plus opaque session IDs you echo back to thread multi-turn state. That's it. The contract is documented in the developer reference and pinned by tests.
What's never in the response
The funnel's candidate ranking weights, the question-bank boost/penalty matrices, internal session state (fields-progress, turn count), raw retrieval scores, or the planner's tool-selection logic. These stay server-side because they encode the curation and validation work that makes the experts useful, they are not part of the public contract.
Terms of use (summary)
Use Crops API output to render guidance to your own end users. Do NOT use the responses to train a derivative classifier, knowledge base, or diagnostic system that competes with FildraAI. Attribution required on user-visible surfaces (Powered by FildraAI). Treat results as advisory, they do not replace agronomic judgement, local extension, or laboratory diagnosis. Full terms live in the developer reference.
Migrating from the legacy routes
The Crops API replaces POST /api/v1/chat/message and POST /api/v1/media/{plant}/*. Those routes remain live but stamp deprecation headers (Deprecation: true, Sunset: Mon, 31 Aug 2026 00:00:00 GMT, Link: ...; rel="successor-version") on every response. After the sunset date they return 410 Gone with a JSON body pointing at the successor. Migration is a URL change, request and response shapes are functionally equivalent, with the plant moving from the request body to the URL path.
Ready to integrate?
The developer reference covers every request parameter, response field, and error code. Partnership enquiries and API access requests go through our contact form.