API Reference

This section documents the wire contract for the WiseYield API: base URL, auth, request and response format, pagination, and rate limits. Endpoint pages live under the groups in the left nav.

Base URL

https://www.wiseyield.co

API key–authenticated routes live under the versioned /api/v1/* namespace. 51 endpoints across 7 scope families are live today (2026-05-18):

Scope family	Routes
Farms	`/v1/farms`, `/v1/farms/{id}`
Crops	`/v1/crops`, `/v1/crops/{id}` (+ status)
Fields / Blocks / Plants	`/v1/farms/{id}/fields/`, `/v1/farms/{id}/fields/{id}/blocks/`, `/v1/farms/{id}/fields/{id}/blocks/{id}/plants/*`
Tasks / Recurring / Templates	`/v1/tasks/`, `/v1/recurring-tasks/`, `/v1/task-templates/*`
Crop Library	`/v1/crop-library/`, `/v1/user-crops/`
Analytics	`/v1/farms/{id}/health-score`, `/v1/farms/{id}/yield-prediction`
Market Intelligence	`/v1/market/regional-prices`

API key minting is Summit-tier only. The full per-endpoint breakdown is in the API Reference left nav. Additional surface ships over time (AI, Billing, Team, User Profile — see V1_API_EXPANSION_PLAN.md). The unversioned /api/* surface powers the WiseYield dashboard and uses session authentication (Clerk cookies); it is not addressable from server-to-server integrations and is intentionally not part of this reference.

Request format

Every API request sends:

Authorization: Bearer wy_live_...
Content-Type: application/json

Request bodies are JSON. Field names use camelCase. Numeric values may be sent as numbers or numeric strings — the API coerces sensibly.

Response format

Successful responses wrap payloads under a data key:

{
  "data": { "id": "...", "name": "..." }
}

List endpoints add a pagination envelope:

{
  "data": [ /* records */ ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "totalPages": 3
  }
}

Timestamps are ISO 8601 in UTC (2026-05-17T14:23:01.000Z).

HTTP status codes

Status	Meaning
`200 OK`	Read or update succeeded
`201 Created`	Resource was created
`204 No Content`	Delete succeeded
`400 Bad Request`	Validation failed — see `details`
`401 Unauthorized`	Missing, malformed, expired, or revoked API key
`403 Forbidden`	Authenticated but lacking required scope or IP
`404 Not Found`	Resource doesn’t exist or is soft-deleted
`409 Conflict`	Uniqueness or state-machine violation
`429 Too Many Requests`	Rate limit exceeded
`5xx`	Server error — safe to retry with backoff

The complete error-code reference lives in Errors & status codes.

Error response shape

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

Field	Always present?	Notes
`error`	Yes	Short category
`code`	When the error has a stable kind	Machine-readable identifier
`message`	Frequently	Human-readable description
`details`	When structured context exists	Per-field validation errors, available scopes, etc.

Authentication

Pass a key from your dashboard:

Authorization: Bearer wy_live_a1b2c3d4...

Keys are wy_(live|test)_[a-f0-9]{48}. See Authentication for scopes, rotation, and security guidance.

Rate limits

Per-user, sliding-window, by subscription tier:

Tier	Requests / hour
Expired trial	3
Seed	25
Sprout	50
Trial / Harvest	100
Grove	200
Summit	1,000

Every response carries:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 2026-05-17T15:00:00.000Z

X-RateLimit-Reset is an ISO 8601 string, not a Unix timestamp. The complete rate-limit contract — backoff implementations, what to do on 429, what the limits are NOT — is on the Rate-limit handling guide.

Pagination

Offset pagination with two parameters:

GET /api/v1/farms?page=2&limit=50

Parameter	Default	Constraints
`page`	`1`	≥ 1
`limit`	`20`	1–100

See Pagination for iteration patterns and edge cases.

Sorting

List endpoints accept sort and order parameters:

GET /api/v1/farms?sort=createdAt&order=desc
GET /api/v1/farms?sort=name&order=asc

The supported fields per endpoint are listed on each endpoint page.

Soft deletes

Domain records are soft-deletable. DELETE calls set a deletedAt timestamp; subsequent reads exclude soft-deleted rows. There is no includeDeleted flag — deleted records are not retrievable via the public API. See Soft deletes for the full semantics.

Currency in financial endpoints

Financial rows carry an ISO 4217 currency code. Aggregations convert per row using daily spot rates and return a byCurrency breakdown alongside the base-currency total. See Currency model for the precedence chain and Currency in financial endpoints for usage patterns.

Land hierarchy

Operations attach to the level they belong to: irrigation to a field, fertigation to a block, soil samples to a field, leaf samples to a block, expenses to a crop or field, overhead to a farm. See Land hierarchy for the model.

Conventions


Casing	`camelCase` for JSON fields, `kebab-case` in URLs
IDs	UUIDs in path parameters, prefixed strings (`key_…`, `wl_…`) elsewhere
Timestamps	ISO 8601 UTC strings
Booleans	Native JSON `true` / `false`
Nullable fields	Explicit `null` rather than omission

Support

Email — support@wiseyield.co
Help Center — wiseyield.featurebase.app

Overview

Versioned API (v1)

Crops

Fields

Blocks

Plants

Tasks

Recurring Tasks

Task Templates

Crop Library

Analytics

Market Intelligence

API Keys

Public Endpoints

Base URL

Request format

Response format

HTTP status codes

Error response shape

Authentication

Rate limits

Sorting

Soft deletes

Currency in financial endpoints

Land hierarchy

Conventions

Support

​Base URL

​Request format

​Response format

​HTTP status codes

​Error response shape

​Authentication

​Rate limits

​Pagination

​Sorting

​Soft deletes

​Currency in financial endpoints

​Land hierarchy

​Conventions

​Support

Base URL

Request format

Response format

HTTP status codes

Error response shape

Authentication

Rate limits

Pagination

Sorting

Soft deletes

Currency in financial endpoints

Land hierarchy

Conventions

Support