Machine Learning API

Machine Learning API: Crop recommendation and yield prediction

The Machine Learning API provides direct access to FildraAI's crop recommendation and yield analysis models. Submit soil, climate, and fertilizer data and receive predictions with transparent reasoning traces — so you understand not just what the model recommends, but why.

POST /api/v1/ml/... Scope: machine_learning:predict

What is the Machine Learning API?

The Machine Learning API gives you direct access to the prediction models that power FildraAI's agronomic intelligence. Rather than going through a conversational interface, you can call these models programmatically — submitting structured farm data and receiving structured predictions in return.

All endpoints support both a basic (result-only) mode and a with-trace mode that returns a step-by-step explanation of the model's reasoning. The trace is designed to help agronomists and extension officers verify model outputs and explain recommendations to farmers in their own words.

Transparent predictions

Every prediction from the Machine Learning API can be accompanied by a reasoning trace. This is not a post-hoc explanation — it is the model's actual decision path, making the result verifiable and auditable.

Authentication

All Machine Learning API endpoints require a valid API key in the Authorization header: 

Authorization: Bearer YOUR_API_KEY

Your key must have the machine_learning API enabled and carry the machine_learning:predict scope. All ML inference endpoints are billed per call. Locale can be passed in the request body, as a query parameter, or via the Accept-Language header — the body takes precedence.

Endpoints

POST /api/v1/ml/crop/basic

Returns a crop recommendation based on soil and climate features. Result only — no reasoning trace.

POST /api/v1/ml/crop/with_trace

Crop recommendation with a full reasoning trace. Includes the feature importances and decision path the model used to reach its recommendation.

POST /api/v1/ml/yield/basic

Yield prediction given fertilizer usage and soil/climate conditions. Returns predicted yield range. Result only.

POST /api/v1/ml/snapshot

Combined endpoint. Runs crop recommendation, yield analysis, or both in a single call. Useful for generating a complete farm intelligence snapshot with minimal round-trips.

Crop recommendation

The crop recommendation endpoints accept a features object describing the farm's soil and climate conditions. The country field narrows predictions to region-appropriate crops.

Required fields

  • features (object) — Soil and climate data (see example below)

Optional fields

  • country (string) — ISO country code to localise recommendations
  • locale (string) — Response language locale key

Example request

POST /api/v1/ml/crop/with_trace
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "features": {
    "N": 90,
    "P": 42,
    "K": 43,
    "temperature": 21.0,
    "humidity": 82.0,
    "ph": 6.5,
    "rainfall": 202.9
  },
  "country": "ZM",
  "locale": "en-us"
}

Yield analysis

Yield analysis endpoints accept fertilizer application data and soil/climate conditions. The with_trace variant also accepts a target_yield and budget to provide optimisation recommendations.

Required fields (basic)

  • fertilizer (object) — Fertilizer application data
  • soil_climate (object) — Soil and climate conditions

Optional fields (with_trace only)

  • target_yield — Desired yield target for optimisation
  • budget — Budget constraint for input optimisation
  • country (string) — Region context
  • locale (string) — Response language

Combined ML snapshot

POST /api/v1/ml/snapshot runs multiple models in a single call. All input objects are optional — you can run crop recommendation only, yield analysis only, or both together. This minimises round-trips when building a comprehensive farm intelligence view.

Example snapshot request

POST /api/v1/ml/snapshot
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "crop_features": {
    "N": 90, "P": 42, "K": 43,
    "temperature": 21.0, "humidity": 82.0,
    "ph": 6.5, "rainfall": 202.9
  },
  "fertilizer": {
    "urea_kg_ha": 100,
    "dap_kg_ha": 50
  },
  "soil_climate": {
    "ph": 6.5, "rainfall_mm": 820,
    "temperature_c": 21.0
  },
  "include_traces": true,
  "country": "ZM",
  "locale": "en-us"
}

Reasoning traces

The with_trace variants and the include_traces: true snapshot option return a structured explanation of the model's reasoning alongside the prediction. This includes:

Feature importance

Which input features (e.g. soil pH, nitrogen level, rainfall) most strongly influenced the prediction, expressed as relative weights.

Decision path

The step-by-step path through the model's decision logic, showing which thresholds or rules were applied to reach the final output.

Confidence score

A calibrated confidence score for the top prediction, indicating how strongly the model's training supports this recommendation for the given inputs.

Alternatives

Runner-up recommendations with their scores, helping agronomists consider fallback options if the primary recommendation is not feasible.

How to use traces

Traces are designed for agronomist review and farmer communication — not for raw display to end users. Use the feature importance data to explain to a farmer why a particular crop was recommended given their soil conditions. If the top feature is rainfall and the farmer has irrigation, the recommendation may need to be reconsidered locally.

Error codes

The Machine Learning API maps service errors to standard HTTP status codes:

Client errors (4xx)

  • 400 — Invalid or missing input object (e.g. missing features, invalid field type)
  • 401 — Missing or invalid API key
  • 403 — Key lacks the required scope
  • 429 — Rate limit exceeded

Server errors (5xx)

  • 500 — Model inference failed (internal error)
  • 503 — ML service temporarily unavailable; retry with backoff
  • 504 — Inference timeout; the model took longer than the allowed window