> ## 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.

# Quickstart

> Make your first WiseYield API request in under 5 minutes

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

<Note>
  **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](/api-reference/introduction).
</Note>

## 1. Create an API key

<Warning>
  **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](/concepts/tier-ladder) for what's included at each tier and [Authentication](/authentication) for the full key contract.
</Warning>

1. Sign in to your [WiseYield dashboard](https://www.wiseyield.co/dashboard) as a Summit-tier user.
2. Open **Settings → API Keys**.
3. Click **Create API Key**, give it a name and pick scopes (for this guide: `farms:read` and `farms:write`).
4. Copy the key shown on screen — it's only displayed **once**.

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

## 2. List your farms

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

<CodeGroup>
  ```javascript JavaScript theme={null}
  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`);
  ```

  ```python Python theme={null}
  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")
  ```

  ```bash cURL theme={null}
  curl 'https://www.wiseyield.co/api/v1/farms?limit=10' \
    -H "Authorization: Bearer $WISEYIELD_API_KEY" \
    -H "Content-Type: application/json"
  ```
</CodeGroup>

Successful response shape:

```json theme={null}
{
  "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.

<CodeGroup>
  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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'])
  ```

  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

A `201 Created` response wraps the new farm under `data`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/authentication) page for the full list of error codes and a retry-with-backoff implementation.

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Scopes, rate limits, and security best practices
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Every endpoint and its parameters
  </Card>

  <Card title="Integration guides" icon="book" href="/guides/crop-recommendations">
    Crop recommendations, yield predictions, weather, webhooks
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Real-time event notifications
  </Card>
</CardGroup>

## Need help?

* Email [support@wiseyield.co](mailto:support@wiseyield.co)
* Browse the [Help Center](https://wiseyield.featurebase.app)