Quickstart - WiseYield

This guide gets you from zero to a successful API call against the WiseYield versioned API (/api/v1/*). Allow ~5 minutes.

51 endpoints across 7 scope families are live: Farms, Crops, Fields/Blocks/Plants, Tasks/Recurring/Templates, Crop Library, Analytics, Market Intelligence. Browse the full surface in the API Reference.

1. Create an API key

Summit-tier required. API key creation is gated to the Summit subscription. Lower tiers (Seed / Sprout / Harvest / Grove / Trial) get 403 TIER_INSUFFICIENT on POST /api/api-keys. See Subscription tiers for what’s included at each tier and Authentication for the full key contract.

Sign in to your WiseYield dashboard as a Summit-tier user.
Open Settings → API Keys.
Click Create API Key, give it a name and pick scopes (for this guide: farms:read and farms:write).
Copy the key shown on screen — it’s only displayed once.

Store the key in an environment variable or secret manager. Never commit it to a repo or paste it into client-side code.

2. List your farms

The GET /api/v1/farms endpoint returns the farms owned by the user behind the API key, paginated.

const WISEYIELD_API_KEY = process.env.WISEYIELD_API_KEY;

const res = await fetch('https://www.wiseyield.co/api/v1/farms?limit=10', {
  headers: {
    'Authorization': `Bearer ${WISEYIELD_API_KEY}`,
    'Content-Type': 'application/json',
  },
});

const { data, pagination } = await res.json();
console.log(`Got ${data.length} of ${pagination.total} farms`);

import os
import requests

WISEYIELD_API_KEY = os.environ['WISEYIELD_API_KEY']

res = requests.get(
    'https://www.wiseyield.co/api/v1/farms',
    params={'limit': 10},
    headers={
        'Authorization': f'Bearer {WISEYIELD_API_KEY}',
        'Content-Type': 'application/json',
    },
)

body = res.json()
print(f"Got {len(body['data'])} of {body['pagination']['total']} farms")

curl 'https://www.wiseyield.co/api/v1/farms?limit=10' \
  -H "Authorization: Bearer $WISEYIELD_API_KEY" \
  -H "Content-Type: application/json"

Successful response shape:

{
  "data": [
    {
      "id": "...",
      "name": "Green Valley Farm",
      "farmType": "commercial",
      "primaryUse": "crops",
      "city": "Cairo",
      "country": "Egypt",
      "totalArea": "100",
      "areaUnit": "hectare",
      "soilType": "sandy",
      "irrigationSystem": "drip",
      "status": "active",
      "createdAt": "2026-05-01T09:30:00.000Z",
      "updatedAt": "2026-05-17T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1
  }
}

Supported query parameters:

Parameter	Type	Default	Notes
`page`	integer ≥ 1	`1`	Pagination cursor
`limit`	integer 1–100	`20`	Page size
`status`	`active` \| `inactive` \| `archived` \| `draft`	—	Optional filter
`sort`	`createdAt` \| `name` \| `totalArea`	`createdAt`	Sort field
`order`	`asc` \| `desc`	`desc`	Sort direction

3. Create a farm

POST /api/v1/farms creates a farm under the authenticated user’s account.

const res = await fetch('https://www.wiseyield.co/api/v1/farms', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${WISEYIELD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Green Valley Farm',
    farmType: 'commercial',
    primaryUse: 'crops',
    city: 'Cairo',
    country: 'Egypt',
    totalArea: 100,
    areaUnit: 'hectare',
    soilType: 'sandy',
    irrigationSystem: 'drip',
    status: 'active',
  }),
});

const { data: farm } = await res.json();
console.log('Created farm:', farm.id);

res = requests.post(
    'https://www.wiseyield.co/api/v1/farms',
    headers={
        'Authorization': f'Bearer {WISEYIELD_API_KEY}',
        'Content-Type': 'application/json',
    },
    json={
        'name': 'Green Valley Farm',
        'farmType': 'commercial',
        'primaryUse': 'crops',
        'city': 'Cairo',
        'country': 'Egypt',
        'totalArea': 100,
        'areaUnit': 'hectare',
        'soilType': 'sandy',
        'irrigationSystem': 'drip',
        'status': 'active',
    },
)

farm = res.json()['data']
print('Created farm:', farm['id'])

curl -X POST https://www.wiseyield.co/api/v1/farms \
  -H "Authorization: Bearer $WISEYIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Green Valley Farm",
    "farmType": "commercial",
    "primaryUse": "crops",
    "city": "Cairo",
    "country": "Egypt",
    "totalArea": 100,
    "areaUnit": "hectare",
    "soilType": "sandy",
    "irrigationSystem": "drip",
    "status": "active"
  }'

A 201 Created response wraps the new farm under data:

{
  "data": {
    "id": "...",
    "ownerId": "...",
    "name": "Green Valley Farm",
    "status": "active",
    "createdAt": "2026-05-17T14:23:01.000Z"
  }
}

Validation rules

Field	Required	Rules
`name`	yes	1–200 characters
`city`	yes	1–200 characters
`country`	yes	1–200 characters
`totalArea`	yes	Positive number
`areaUnit`	no (default `hectare`)	One of `hectare`, `acre`, `feddan`
`farmType`	no	One of `commercial`, `organic`, `mixed`, `specialty`
`primaryUse`	no	One of `crops`, `livestock`, `mixed`, `research`
`irrigationSystem`	no	One of `drip`, `sprinkler`, `flood`, `pivot`, `manual`, `none`
`latitude`	no	−90 to 90
`longitude`	no	−180 to 180
`boundaries`	no	GeoJSON `Polygon`
`status`	no (default `active`)	One of `active`, `inactive`, `archived`, `draft`

A duplicate farm name for the same user returns 409 Conflict.

4. Handle errors gracefully

Errors share a stable shape:

{
  "error": "Validation failed",
  "details": {
    "totalArea": ["Total area must be greater than 0"]
  }
}

Status	When
`400`	Validation failed — inspect `details` for per-field messages
`401`	Missing, malformed, expired, or revoked API key
`403`	Key lacks the required scope (e.g. `farms:write` for `POST`)
`409`	Conflict (e.g. duplicate farm name)
`429`	Rate-limited — back off until `X-RateLimit-Reset`
`5xx`	Server error — safe to retry with backoff

See the Authentication page for the full list of error codes and a retry-with-backoff implementation.

Next steps

Authentication

Scopes, rate limits, and security best practices

API Reference

Every endpoint and its parameters

Integration guides

Crop recommendations, yield predictions, weather, webhooks

Webhooks

Real-time event notifications

Need help?

Email support@wiseyield.co
Browse the Help Center

​1. Create an API key

​2. List your farms

​3. Create a farm

​Validation rules

​4. Handle errors gracefully

​Next steps

Authentication

API Reference

Integration guides

Webhooks

​Need help?

1. Create an API key

2. List your farms

3. Create a farm

Validation rules

4. Handle errors gracefully

Next steps

Need help?