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

# Search crops

> Text + filter search over the verified admin crop catalog.

```
GET https://www.wiseyield.co/api/v1/crop-library/search
```

The crop library is a shared, curated catalog of verified admin crops with climate, soil, growth, yield, management, and economic metadata. Use this endpoint to discover crops; use [Get crop details](/api-reference/crop-library/crop-details) for the full record by ID.

### Authentication

Requires a key with the `library:read` scope. See [Authentication](/authentication).

### Query parameters

All optional.

<ParamField query="q" type="string">Text search across name, scientific name, and localized names (Arabic, French, Spanish, German).</ParamField>
<ParamField query="category" type="string">Category ID filter.</ParamField>
<ParamField query="waterRequirement" type="string">`low`, `moderate`, `high`, `very_high`.</ParamField>
<ParamField query="sunRequirement" type="string">`full_sun`, `partial_shade`, `shade`.</ParamField>
<ParamField query="frostTolerance" type="string">`none`, `light`, `moderate`, `high`.</ParamField>
<ParamField query="droughtTolerance" type="string">`low`, `moderate`, `high`.</ParamField>
<ParamField query="demandTrend" type="string">`declining`, `stable`, `growing`, `high_growth`.</ParamField>
<ParamField query="maxDaysToMaturity" type="integer">Filter for crops maturing within N days.</ParamField>
<ParamField query="sortBy" type="string" default="name">`name`, `daysToMaturity`, `yield`.</ParamField>
<ParamField query="limit" type="integer" default="50">1–100.</ParamField>

### Response

<ResponseField name="data" type="array">
  Array of admin crop objects matching the query.

  <Expandable title="Admin crop">
    <ResponseField name="id" type="string">UUID.</ResponseField>
    <ResponseField name="name" type="string">Common name (English).</ResponseField>
    <ResponseField name="scientificName" type="string | null">Binomial.</ResponseField>
    <ResponseField name="category" type="string">Category ID.</ResponseField>
    <ResponseField name="description" type="string | null">Free text.</ResponseField>
    <ResponseField name="climateData" type="object">Frost / drought tolerance, ideal temp range, rainfall needs.</ResponseField>
    <ResponseField name="soilRequirements" type="object">Preferred soil types, pH range, drainage.</ResponseField>
    <ResponseField name="managementData" type="object">Water + sun requirements, fertilization schedule, pest pressure.</ResponseField>
    <ResponseField name="growthData" type="object">Days to maturity, growth stages, FAO-56 Kc coefficients.</ResponseField>
    <ResponseField name="yieldData" type="object">Average yield per hectare, harvest windows.</ResponseField>
    <ResponseField name="economicData" type="object">Price ranges, demand trends, market signals.</ResponseField>
    <ResponseField name="metadata" type="object">Localized names, source citations, additional flags.</ResponseField>
    <ResponseField name="dataSource" type="string">Original source (FAO, USDA, etc.).</ResponseField>
    <ResponseField name="verificationStatus" type="string">Always `verified` for results returned here.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601.</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl 'https://www.wiseyield.co/api/v1/crop-library/search?q=tomato&maxDaysToMaturity=120' \
    -H "Authorization: Bearer $WISEYIELD_API_KEY"
  ```
</RequestExample>

## Errors

| Status                    | When                                            |
| ------------------------- | ----------------------------------------------- |
| `401`                     | Missing, malformed, expired, or revoked API key |
| `403 INSUFFICIENT_SCOPE`  | Key lacks `library:read` scope                  |
| `429 RATE_LIMIT_EXCEEDED` | Per-user rate limit reached                     |
| `5xx`                     | Server error                                    |