> ## Documentation Index > Fetch the complete documentation index at: https://docs.wiseyield.co/llms.txt > Use this file to discover all available pages before exploring further. # API Reference > Conventions, conventions, and the canonical wire contract for the WiseYield API. 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`](https://github.com/shenoudab/wiseyield/blob/main/docs/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: ```http theme={null} 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: ```json theme={null} { "data": { "id": "...", "name": "..." } } ``` List endpoints add a `pagination` envelope: ```json theme={null} { "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](/concepts/errors). ## Error response shape ```json theme={null} { "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: ```bash theme={null} Authorization: Bearer wy_live_a1b2c3d4... ``` Keys are `wy_(live|test)_[a-f0-9]{48}`. See [Authentication](/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: ```http theme={null} 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](/guides/rate-limits) guide. ## Pagination Offset pagination with two parameters: ```bash theme={null} GET /api/v1/farms?page=2&limit=50 ``` | Parameter | Default | Constraints | | --------- | ------- | ----------- | | `page` | `1` | ≥ 1 | | `limit` | `20` | 1–100 | See [Pagination](/guides/pagination) for iteration patterns and edge cases. ## Sorting List endpoints accept `sort` and `order` parameters: ```bash theme={null} 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](/concepts/soft-delete) 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](/concepts/currency) for the precedence chain and [Currency in financial endpoints](/guides/currency) 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](/concepts/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](mailto:support@wiseyield.co) * Help Center — [wiseyield.featurebase.app](https://wiseyield.featurebase.app)