Agronomist API

The API and SDK let organisations build DeepLeaf infrastructure into their own services. OpenAI-compatible: set model to agronomist, send a stable farmer id. Same id, same chat.

Partner with DeepLeaf Read the docs

Quick start

chat.shcurl

curl https://<host>/v1/chat/completions \
  -H "Authorization: Bearer $DEEPLEAF_API_KEY" \
  -H "X-Farmer-Id: your-farmer-12345" \
  -H "Content-Type: application/json" \
  -d '{"model": "agronomist",
       "messages": [{"role": "user", "content": "my tomato leaves have brown spots"}]}'

What the run looks like: the thinking fold and each tool call

You

my tomato leaves have brown spots

Brown rings with a yellow halo, lower canopy first. Field is day 41, 18 mm of rain in three days.

Consistent with early blight. Need registered products before naming any.

Input: {"hours": 72}
Output: 18 mm rain over 3 days. Dry 06:00 to 12:00 tomorrow, wind 5 to 8 km/h.

06:12

Likely early blight (Alternaria solani). Remove the lowest leaves today and spray tomorrow 06:00 to 10:00 with a product on the national register.

Diagnose a photo

photo.shcurl

curl https://<host>/v1/chat/completions \
  -H "Authorization: Bearer $DEEPLEAF_API_KEY" \
  -H "X-Farmer-Id: your-farmer-12345" \
  -d '{"model": "agronomist",
       "messages": [{"role": "user", "content": [
         {"type": "text", "text": "what is wrong with this plant?"},
         {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}]}]}'

Tomato leaf with early blight lesions — What the farmer sees: the diagnosis card with its citations

Ask for a spray window

forecast.shcurl

curl https://<host>/v1/chat/completions \
  -H "Authorization: Bearer $DEEPLEAF_API_KEY" \
  -H "X-Farmer-Id: your-farmer-12345" \
  -d '{"model": "agronomist",
       "messages": [{"role": "user", "content": "when can I spray this week?"}]}'

What the farmer sees: the spray window card

You

When can I spray the tomatoes this week?

06:14

Spray window

Best window tomorrow 06:00 to 10:00. Rain likely from 14:00.

Wind: 5 to 8 km/h until 10:00
Rain: 40% from 14:00, 6 mm
Delta T: 3.1 °C at 08:00

Next days

Tue 13Good06:00–10:00
Wed 14AvoidRain
Thu 15Fair07:00–09:00

weather.forecast · hourly12 Oct, 05:40

Spray tomorrow morning. Wednesday is out because of the rain.

What you get

Stable farmer id: Send X-Farmer-Id or the user field. Same id, same farmer, same fields, same memory.
SDKs: React SDK for embedding, Python SDK for servers.
Embed tokens: Short-lived tokens for browsers. API keys never reach a browser.
WhatsApp relay: Keep your own number and bot; relay messages to Agronomist.
Voice calls: POST /v1/calls starts a real-time call for a farmer.
Webhooks: Field briefings and events, signed with HMAC (X-Agronomist-Signature) and carrying an idempotency key.
Versioned docs: Open /v1/openapi.json; Deprecation and Sunset headers before any meaning change.
Playground: Try requests against a sandbox farmer before writing code.

SDKs

The React SDK embeds the Agronomist chat and voice in your app. The Python SDK wraps this API for servers and WhatsApp bots, with the farmer id as a first-class argument. Both are shared with partners ahead of their public npm and PyPI release.

Agronomist SDKs

Verify a webhook

verify.pyPython

import hmac, hashlib

def verify(secret: bytes, body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret, body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)  # X-Agronomist-Signature

The field.briefing event you verified, as the farmer reads it

05:45

This morning · North block

Scout zone 3DueLow vigour, 0.4 ha
Spray windowGood06:00–10:00
IrrigationSkip today, 18 mm fell

field.briefing12 Oct, 05:45

Proposal

Add spray to the calendar

Tue 13 Oct06:00–10:00

Nothing is written until you confirm.

Security

Keys are scoped to an organisation and stay on your servers. Image URLs are not fetched by the API; send images inline. Report issues to trust@deepleaf.org.

Suggested