Quickstart

Make your first /v1/ask call and read a cited answer in five minutes.

1 · Get a token

Grab an API token from your dashboard (see Authentication) and export it:

export PESTREN_API_TOKEN="sk_live_…"

2 · Ask a question

curl -s https://api.pestren.com/v1/ask \
  -H "Authorization: Bearer $PESTREN_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"lat": 4.57, "lng": -75.66,
       "question": "Coffee leaf rust risk here this week — should I act?"}'

import os, requests
r = requests.post(
    "https://api.pestren.com/v1/ask",
    headers={"Authorization": f"Bearer {os.environ['PESTREN_API_TOKEN']}"},
    json={"lat": 4.57, "lng": -75.66,
          "question": "Coffee leaf rust risk here this week?"},
)
print(r.json()["answer"], r.json()["confidence"])

# after installing the MCP server
/pestren_ask lat=4.57 lng=-75.66 \
  question="Coffee leaf rust risk here this week?"

3 · Read the response

You get a prose answer, an overall confidence bucket (high/medium/low), a citations[] array (one entry per source, each with a source_url, fetched_at, and verification tier), the fields_used[] that grounded the answer, and an optional recommended_action.

Authentication

Three ways in — all bearer-token based. The public catalog needs no auth.

Dashboard API token

Copy a token from your account and send it as a bearer header on every call. Tokens are only accepted over https (with a loopback exception for local development).

Authorization: Bearer <PESTREN_API_TOKEN>

Device-flow login

For CLIs and local MCP, run a one-time browser login that stores a credential file:

pestren-mcp login   # opens a browser, writes ~/.pestren/credentials

MCP OAuth

Remote MCP clients authenticate against the hosted endpoint https://api.pestren.com/mcp via OAuth — no token pasting.

Rotate & revoke

Rotate tokens from the dashboard; revoked tokens fail immediately with 401 unauthorized. Scope tokens per environment and never commit them.

Field catalog & layers

Every value Pestren returns belongs to one of seven layers, plus a derived actions block. Here are representative fields per layer.

Provenance & confidence

Two things that must never be conflated: the per-field verification tier and the per-answer confidence.

The provenance envelope

Every field is returned wrapped, not as a bare value:

{
  "value": 74,
  "unit": "risk_index_0_100",
  "source": "FAO FAW-Monitor",
  "source_url": "https://…",
  "confidence": "field-verified",   // verification tier
  "fetched_at": "2026-07-01T06:12Z",
  "dataset_vintage": "2026-W26",
  "ttl_seconds": 86400,
  "notes": "warm nights + rainfall on whorl-stage maize"
}

The 3-tier verification ladder

Answer calibration

An /v1/ask answer gets one overall high / medium / low, derived from three signals:

• Field coverage — how many of the fields the question needed were actually fetched.
• Tier mix — whether driver fields are field-verified/lab-confirmed or only literature.
• Cross-source agreement — whether independent sources corroborate.

Presets

Named field bundles for common jobs. Pass preset instead of enumerating fields[].

Skills

Drop-in agronomy files an agent loads to reason about a crop or a practice — reusable across models and stacks.

What a skill is

A self-contained file describing an entity's agronomy: stages, thresholds, the sources behind them, and a verification tier. The agent reads the skill for reasoning; it calls /v1/fetch for live values.

skills/
  crop.coffee.skill.md        # agronomy, stages, thresholds, sources, tier
  crop.maize.skill.md
  practice.irrigation.md      # reusable across crops
  practice.disease-scouting.md

Schema

Each skill declares an entity, its stages, decision thresholds, the sources that back them, and a default verification tier. Load it in Claude/GPT skills or a custom stack.

Benchmarking

Run any farm question at any coordinate and see Pestren scored against other models. A first-class, public feature.

What it does

Each model is scored on four axes and rolled into a single number:

Programmatic access

Run the same rubric in CI over your own prompts:

curl -s https://api.pestren.com/v1/eval \
  -H "Authorization: Bearer $PESTREN_API_TOKEN" \
  -d '{"lat": 47.3, "lng": 8.5,
       "question": "Late-blight risk for potato this week?",
       "models": ["pestren","gpt-5","gemini","claude"]}'

Returns a per-model, per-axis scored comparison. Open the hosted playground →

POST /v1/fetch

The developer escape hatch — deterministic, provenance-wrapped fields with no LLM in the loop.

Request

Worked example — irrigation_plan, maize in Kenya

{
  "fields": {
    "soil_moisture": { "value": 0.18, "unit": "m3/m3",
        "source": "NASA SMAP", "confidence": "field-verified" },
    "et0":           { "value": 5.1,  "unit": "mm/day", "source": "NASA POWER" },
    "rainfall_7d":   { "value": 6,    "unit": "mm",     "source": "ERA5" },
    "irrigation_need":{ "value": "moderate", "confidence": "literature" },
    "growth_stage":  { "value": "whorl", "confidence": "field-verified" }
  },
  "partial_failures": []
}

The honesty pattern

When a source can't be reached, the field is not silently defaulted — it lands in partial_failures with a retryable flag:

"partial_failures": [
  { "field": "ndvi_current", "error": "cloudy_sentinel_pass",
    "retryable": true }
]

GET /v1/meta/fields

The public catalog — no auth. Every field, described.

Returns each field's id, layer, unit, description, default source, typical confidence tier, and ttl_seconds. Companion endpoint GET /v1/meta/presets lists the bundles.

{
  "fields": [
    { "id": "disease_risk", "layer": "pest_disease",
      "unit": "risk_index_0_100", "source": "CABI PlantwisePlus",
      "confidence": "literature", "ttl_seconds": 86400,
      "description": "Weekly disease pressure for the resolved crop." }
  ]
}

Field catalog

The browsable table of every field by layer — generated from /v1/meta/fields so docs never drift from the API.

Errors

HTTP errors, the non-error partial_failures contract, and the crop_unsupported soft-fallback.

partial_failures (not an error)

A 200 can still carry per-field failures — each with an error and a retryable flag. Treat it as data, not an exception.

crop_unsupported soft-fallback

For an unsupported crop, Pestren answers generically, drops tier to literature, and flags it in notes rather than failing the call.

Installation

Wire Pestren into any MCP-aware agent. Server name com.pestren/agri.

Hosted (OAuth) — Claude Code

claude mcp add --transport http pestren https://api.pestren.com/mcp
# then run /mcp in Claude Code and complete the browser login

Local stdio fallback

A slim adapter (no GDAL) for Claude Desktop, Cursor, or custom clients:

uvx pestren-mcp            # run the server
pestren-mcp login          # or set PESTREN_BEARER_TOKEN

Config blocks

{ "mcpServers": {
    "pestren": { "command": "uvx", "args": ["pestren-mcp"] }
} }

Environment variables

Tools, resources & prompts

Two tools, three resources, four prompts — results are the verbatim /v1 JSON.

Tools

• pestren_ask(lat, lng, question[, crop]) — mirrors /v1/ask.
• pestren_fetch(lat, lng, fields|preset) — mirrors /v1/fetch.

Resources

• pestren://catalog/fields
• pestren://catalog/presets
• pestren://catalog/coverage

Prompts

pestren_grower_report · pestren_pest_check · pestren_irrigation_plan · pestren_pick_fields — each exposed as a slash command in Claude Code.

Troubleshooting

Smoke-test with MCP Inspector, then fix the usual suspects.

Grower advisory

A grower or agronomist asks pest / irrigation / yield questions in language and gets a cited answer, an action, and optional products.

Query

"Coffee at 4.57, -75.66 — leaf rust risk this week, and should I irrigate?"

Response & audit trail

A grounded answer + recommended_action, every claim citing CABI / Sentinel / NASA with tiers a field officer can re-open.

Why it works

The planner pulls the disease and water layers for the exact coordinate — not generic advice.

Insurance underwriting

Verify crop, sowing window, flood/drainage exposure, and yield-risk with per-field citations an adjuster or regulator can re-fetch.

Query

"Verify crop, sowing window, and flood exposure for this parcel to settle a claim."

Why it works

Use the insurance_underwrite preset; every figure is sourced and audit-trailed with a fetched_at.

Agri-lending & collateral

Crop, acreage, NDVI trend, and a yield-risk band as sourced collateral evidence — reproducible at loan time.

Why it works

The lending_collateral preset returns an independent, citable read on the standing crop and its trajectory.

Robotics & sensor builders

/v1/fetch as training data and risk polygons to task fleets and calibrate models. Your detections flow back as ground truth.

Why it works

Sourced field priors reduce false positives; the precision_scouting preset returns polygons to fly.

Government & policy

Aggregate crop maps and climate-risk zones for scheme targeting and policy modeling — every figure sourced.

Why it works

Fetch across a district's parcels with the climate_risk preset; provenance makes the aggregate defensible.

Building agents

Drop the MCP tools + Skills into an agent loop; let the planner pick fields; keep citations flowing through tool calls.

Sample transcript

user → Is my rice at 21.94, 87.75 at risk this week?
agent → pestren_ask(lat=21.94, lng=87.75,
             question="pest/disease risk this week for rice?")
tool → { answer, confidence:"high", citations:[…], recommended_action }
agent → Elevated stem-borer pressure — scout now. (FAO, Sentinel ↗)