Farms (v1) - WiseYield

curl 'https://www.wiseyield.co/api/v1/farms?page=1&limit=20&status=active&sort=name&order=asc' \
  -H "Authorization: Bearer $WISEYIELD_API_KEY"

const res = await fetch(
  'https://www.wiseyield.co/api/v1/farms?page=1&limit=20&status=active&sort=name&order=asc',
  { headers: { Authorization: `Bearer ${process.env.WISEYIELD_API_KEY}` } }
);
const { data, pagination } = await res.json();
console.log(`Got ${data.length} of ${pagination.total} farms`);

import os, requests

res = requests.get(
    'https://www.wiseyield.co/api/v1/farms',
    params={'page': 1, 'limit': 20, 'status': 'active', 'sort': 'name', 'order': 'asc'},
    headers={'Authorization': f"Bearer {os.environ['WISEYIELD_API_KEY']}"},
)
body = res.json()
print(f"Got {len(body['data'])} of {body['pagination']['total']} farms")

{
  "data": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "name": "Green Valley Farm",
      "farmType": "commercial",
      "primaryUse": "crops",
      "city": "Cairo",
      "country": "Egypt",
      "totalArea": "250",
      "areaUnit": "hectare",
      "soilType": "sandy loam",
      "irrigationSystem": "drip",
      "status": "active",
      "createdAt": "2026-04-12T10:00:00.000Z",
      "updatedAt": "2026-05-14T14:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

{
  "error": "Unauthorized",
  "message": "Invalid or revoked API key",
  "code": "INVALID_API_KEY"
}

{
  "error": "Forbidden",
  "message": "Insufficient permissions. Required scope: farms:read",
  "code": "INSUFFICIENT_SCOPE",
  "details": {
    "requiredScope": "farms:read",
    "availableScopes": ["crops:read"]
  }
}

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED"
}

GET

api

farms

curl 'https://www.wiseyield.co/api/v1/farms?page=1&limit=20&status=active&sort=name&order=asc' \
  -H "Authorization: Bearer $WISEYIELD_API_KEY"

const res = await fetch(
  'https://www.wiseyield.co/api/v1/farms?page=1&limit=20&status=active&sort=name&order=asc',
  { headers: { Authorization: `Bearer ${process.env.WISEYIELD_API_KEY}` } }
);
const { data, pagination } = await res.json();
console.log(`Got ${data.length} of ${pagination.total} farms`);

import os, requests

res = requests.get(
    'https://www.wiseyield.co/api/v1/farms',
    params={'page': 1, 'limit': 20, 'status': 'active', 'sort': 'name', 'order': 'asc'},
    headers={'Authorization': f"Bearer {os.environ['WISEYIELD_API_KEY']}"},
)
body = res.json()
print(f"Got {len(body['data'])} of {body['pagination']['total']} farms")

{
  "data": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "name": "Green Valley Farm",
      "farmType": "commercial",
      "primaryUse": "crops",
      "city": "Cairo",
      "country": "Egypt",
      "totalArea": "250",
      "areaUnit": "hectare",
      "soilType": "sandy loam",
      "irrigationSystem": "drip",
      "status": "active",
      "createdAt": "2026-04-12T10:00:00.000Z",
      "updatedAt": "2026-05-14T14:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

{
  "error": "Unauthorized",
  "message": "Invalid or revoked API key",
  "code": "INVALID_API_KEY"
}

{
  "error": "Forbidden",
  "message": "Insufficient permissions. Required scope: farms:read",
  "code": "INSUFFICIENT_SCOPE",
  "details": {
    "requiredScope": "farms:read",
    "availableScopes": ["crops:read"]
  }
}

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED"
}

The versioned /api/v1/farms endpoint is the API-key-authenticated path for managing farms. The list operation returns paginated farms owned by the authenticated user; the create operation persists a new farm under that user.

List farms

GET https://www.wiseyield.co/api/v1/farms

Authentication

Requires a key with the farms:read scope. See Authentication.

Query parameters

page

integer

default:"1"

Page number (≥ 1).

limit

integer

default:"20"

Results per page (1–100; values above 100 are clamped to 100).

status

string

Filter by farm status: active, inactive, archived, draft.

sort

string

default:"createdAt"

Sort field: createdAt, name, totalArea.

order

string

default:"desc"

Sort direction: asc, desc.

Response

Returns paginated farm records.

data

array

Array of farm objects.

Show Farm

string

UUID identifier.

name

string

Farm name.

farmType

string

One of commercial, organic, mixed, specialty.

primaryUse

string

One of crops, livestock, mixed, research.

city

string

City.

country

string

Country.

totalArea

string

Numeric string (precision preserved).

areaUnit

string

One of hectare, acre, feddan.

soilType

string

Free-text soil description.

irrigationSystem

string

One of drip, sprinkler, flood, pivot, manual, none.

status

string

One of active, inactive, archived, draft.

createdAt

string

ISO 8601 timestamp.

updatedAt

string

ISO 8601 timestamp.

pagination

object

Show Pagination

page

integer

Echoes the requested page.

limit

integer

Page size that was applied.

total

integer

Total active records matching the query.

totalPages

integer

Math.ceil(total / limit).

curl 'https://www.wiseyield.co/api/v1/farms?page=1&limit=20&status=active&sort=name&order=asc' \
  -H "Authorization: Bearer $WISEYIELD_API_KEY"

const res = await fetch(
  'https://www.wiseyield.co/api/v1/farms?page=1&limit=20&status=active&sort=name&order=asc',
  { headers: { Authorization: `Bearer ${process.env.WISEYIELD_API_KEY}` } }
);
const { data, pagination } = await res.json();
console.log(`Got ${data.length} of ${pagination.total} farms`);

import os, requests

res = requests.get(
    'https://www.wiseyield.co/api/v1/farms',
    params={'page': 1, 'limit': 20, 'status': 'active', 'sort': 'name', 'order': 'asc'},
    headers={'Authorization': f"Bearer {os.environ['WISEYIELD_API_KEY']}"},
)
body = res.json()
print(f"Got {len(body['data'])} of {body['pagination']['total']} farms")

{
  "data": [
    {
      "id": "11111111-2222-3333-4444-555555555555",
      "name": "Green Valley Farm",
      "farmType": "commercial",
      "primaryUse": "crops",
      "city": "Cairo",
      "country": "Egypt",
      "totalArea": "250",
      "areaUnit": "hectare",
      "soilType": "sandy loam",
      "irrigationSystem": "drip",
      "status": "active",
      "createdAt": "2026-04-12T10:00:00.000Z",
      "updatedAt": "2026-05-14T14:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}

{
  "error": "Unauthorized",
  "message": "Invalid or revoked API key",
  "code": "INVALID_API_KEY"
}

{
  "error": "Forbidden",
  "message": "Insufficient permissions. Required scope: farms:read",
  "code": "INSUFFICIENT_SCOPE",
  "details": {
    "requiredScope": "farms:read",
    "availableScopes": ["crops:read"]
  }
}

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED"
}

Create farm

POST https://www.wiseyield.co/api/v1/farms

Authentication

Requires a key with the farms:write scope.

Request body

name

string

required

1–200 characters.

city

string

required

1–200 characters.

country

string

required

1–200 characters.

totalArea

number

required

Positive number.

areaUnit

string

default:"hectare"

One of hectare, acre, feddan.

farmType

string

One of commercial, organic, mixed, specialty.

primaryUse

string

One of crops, livestock, mixed, research.

soilType

string

Up to 200 characters.

irrigationSystem

string

One of drip, sprinkler, flood, pivot, manual, none.

latitude

number

Between −90 and 90.

longitude

number

Between −180 and 180.

boundaries

object

GeoJSON Polygon ({ type: "Polygon", coordinates: number[][][] }).

status

string

default:"active"

One of active, inactive, archived, draft.

Response

Returns the created farm wrapped under data.

curl -X POST https://www.wiseyield.co/api/v1/farms \
  -H "Authorization: Bearer $WISEYIELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maple Ridge Farm",
    "city": "Portland",
    "country": "United States",
    "totalArea": 180,
    "areaUnit": "acre",
    "farmType": "organic",
    "primaryUse": "crops",
    "soilType": "loam",
    "irrigationSystem": "drip",
    "latitude": 45.5152,
    "longitude": -122.6784,
    "status": "active"
  }'

const res = await fetch('https://www.wiseyield.co/api/v1/farms', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WISEYIELD_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Maple Ridge Farm',
    city: 'Portland',
    country: 'United States',
    totalArea: 180,
    areaUnit: 'acre',
    farmType: 'organic',
    primaryUse: 'crops',
    soilType: 'loam',
    irrigationSystem: 'drip',
    latitude: 45.5152,
    longitude: -122.6784,
    status: 'active',
  }),
});

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

import os, requests

res = requests.post(
    'https://www.wiseyield.co/api/v1/farms',
    headers={
        'Authorization': f"Bearer {os.environ['WISEYIELD_API_KEY']}",
        'Content-Type': 'application/json',
    },
    json={
        'name': 'Maple Ridge Farm',
        'city': 'Portland',
        'country': 'United States',
        'totalArea': 180,
        'areaUnit': 'acre',
        'farmType': 'organic',
        'primaryUse': 'crops',
        'soilType': 'loam',
        'irrigationSystem': 'drip',
        'latitude': 45.5152,
        'longitude': -122.6784,
        'status': 'active',
    },
)
farm = res.json()['data']
print('Created farm:', farm['id'])

{
  "data": {
    "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "ownerId": "user_...",
    "name": "Maple Ridge Farm",
    "farmType": "organic",
    "primaryUse": "crops",
    "city": "Portland",
    "country": "United States",
    "totalArea": "180",
    "areaUnit": "acre",
    "soilType": "loam",
    "irrigationSystem": "drip",
    "latitude": "45.5152",
    "longitude": "-122.6784",
    "status": "active",
    "createdAt": "2026-05-17T14:23:01.000Z",
    "updatedAt": "2026-05-17T14:23:01.000Z"
  }
}

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

{
  "error": "Conflict",
  "message": "A farm with this name already exists"
}

Errors

Status	When
`400`	Validation failed — `details` carries per-field messages
`401`	Missing, malformed, expired, or revoked API key
`403`	Key lacks `farms:read` (GET) or `farms:write` (POST)
`409`	Farm name already exists for this user (active rows only)
`429`	Rate limit reached — see Rate-limit handling
`5xx`	Server error — retry with backoff

Authentication

Scopes, key format, rate limits

Pagination

Iterator patterns for list endpoints

Errors

Canonical error response shape

API Keys

Manage keys from your dashboard

API Reference List crops

​List farms

​Authentication

​Query parameters

​Response

​Create farm

​Authentication

​Request body

​Response

​Errors

​Related

Authentication

Pagination

Errors

API Keys

List farms

Authentication

Query parameters

Response

Create farm

Authentication

Request body

Response

Errors

Related