> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mireye.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/search/fields

> List every Search name with its filter operators, output support, hints and price.

## When to use this

Read `/v1/search/fields` before building a [Search](https://docs.mireye.ai/api-reference/search.md) request.
For every name it says which operators the name accepts in `filters` and whether
it can be named in `fields`, so an agent can validate a query before paying for it.
An unknown name in a Search request returns `422 search_invalid_filter`. Enrich and
Fetch have their own lists: [`GET /v1/enrich/fields`](https://docs.mireye.ai/api-reference/get-enrich-fields)
and [`GET /v1/meta/fields`](https://docs.mireye.ai/api-reference/meta-fields).

No authentication is required and the call is free. The response carries an `ETag`
and `Cache-Control: public, max-age=3600`. Send `If-None-Match` with the last `ETag`
to receive `304 Not Modified` when nothing changed.

## Request shape

`GET` with no body and no query parameters.

```bash theme={null}
curl https://api.mireye.com/v1/search/fields
```

## Example response

An excerpt: one filterable name and one output-only name are shown.

```json theme={null}
{
  "version": "0.18.0",
  "pricing": {
    "currency": "USD",
    "unit": "query",
    "price_usd": "0.20",
    "plan_prices_usd": {"build": "0.18", "free": "0.20", "growth": "0.15"},
    "charged_when": "Once per completed page, including a valid page with zero matches. Every requested field is included."
  },
  "fields": [
    {
      "name": "parcel_boundary_geojson",
      "type": "string",
      "unit": null,
      "description": "Full GeoJSON Polygon/MultiPolygon of the matched parcel (WGS84), encoded as a JSON string.",
      "interpretation_hints": "One uniquely intersecting parcel, preserving all polygon parts and holes. No nearest fallback. A multi-parcel site requires separate assembly.",
      "null_meaning": "No unique parcel at the point, or the matched record lacks this attribute. Storage or parse failures carry failed status.",
      "nullable": true,
      "source": "PARCEL_VENDOR",
      "filter_ops": [],
      "returnable": true
    },
    {
      "name": "pvd_gisacre",
      "type": "float",
      "unit": "acres",
      "description": "Parcel vendor area calculated from parcel boundary",
      "interpretation_hints": "Parcel vendor area calculated from parcel boundary",
      "null_meaning": null,
      "nullable": true,
      "source": "PARCEL_VENDOR",
      "filter_ops": ["eq", "ne", "lt", "lte", "gt", "gte", "in", "between"],
      "returnable": true
    }
  ]
}
```

## Response shape

| Key | Meaning |
| - | - |
| `version` | Response envelope version. |
| `pricing` | Search price: `price_usd` on Free, `plan_prices_usd` per plan, and `charged_when`. |
| `fields` | Every Search name, sorted by name. |

Each entry has `name`, `type`, `unit` (null when unitless), `description`,
`interpretation_hints`, `null_meaning` (null when not documented), `nullable` and
`source`, plus:

* `filter_ops`: operators the name accepts in `filters`. Text and boolean names take
  `eq`, `ne` and `in`; numbers and dates also take `lt`, `lte`, `gt`, `gte` and
  `between`; `geometry` takes `intersects` and `within`. An empty list means the
  name is output-only.
* `returnable`: whether the name can be listed in the request's `fields`.

Every request still needs a `state2` filter with `eq` or `in`.

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | `query_parameter_unknown` | The request included a query parameter; this endpoint takes none. |


## OpenAPI

````yaml GET /v1/search/fields
openapi: 3.1.0
info:
  description: >-
    Provenance-tagged geospatial data for US coordinates. POST /v1/fetch for
    deterministic field values (POST /v1/fetch/batch for up to 25 locations at
    once); POST /v1/ask for natural-language Q&A; GET /v1/meta/fields for the
    catalog.
  title: Mireye Earth
  version: 0.18.0
servers:
  - description: Production
    url: https://api.mireye.com
security: []
paths:
  /v1/search/fields:
    get:
      summary: List Search filters and output fields
      description: >-
        Every name accepted by POST /v1/search. filter_ops lists the operators a
        name accepts in filters (an empty list means output-only), and
        returnable says whether it may be named in fields. Includes type, unit,
        description, interpretation hints, null meaning, source and the Search
        price. No authentication is required. The response carries an ETag and
        Cache-Control: public, max-age=3600; send If-None-Match to receive 304
        when nothing changed.
      operationId: search_fields_catalog_v1_search_fields_get
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchFieldsResponse'
          description: Successful Response
        '304':
          description: Not modified; the cached copy matching If-None-Match is current.
        '400':
          content:
            application/json:
              example:
                detail:
                  error: query_parameter_unknown
                  message: 'Unknown query parameter(s): limit.'
                  retryable: false
          description: An unknown query parameter was supplied.
components:
  schemas:
    SearchFieldsResponse:
      additionalProperties: false
      properties:
        fields:
          items:
            $ref: '#/components/schemas/SearchDiscoveryField'
          title: Fields
          type: array
        pricing:
          $ref: '#/components/schemas/EndpointPricing'
        version:
          description: Response envelope version.
          title: Version
          type: string
      required:
        - version
        - pricing
        - fields
      title: SearchFieldsResponse
      type: object
    SearchDiscoveryField:
      additionalProperties: false
      properties:
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        filter_ops:
          description: >-
            Operators this name accepts in filters. An empty list means the name
            is output-only.
          items:
            type: string
          title: Filter Ops
          type: array
        interpretation_hints:
          anyOf:
            - type: string
            - type: 'null'
          description: How to read the value.
          title: Interpretation Hints
        name:
          description: Field ID to use in requests.
          title: Name
          type: string
        null_meaning:
          anyOf:
            - type: string
            - type: 'null'
          description: What a null value means, when documented.
          title: Null Meaning
        nullable:
          description: Whether a valid response can carry null.
          title: Nullable
          type: boolean
        returnable:
          description: Whether the name is accepted in the fields list.
          title: Returnable
          type: boolean
        source:
          anyOf:
            - type: string
            - type: 'null'
          description: Public source ID returned with values.
          title: Source
        type:
          description: 'Value type: string, int, float, bool, object or array.'
          title: Type
          type: string
        unit:
          anyOf:
            - type: string
            - type: 'null'
          description: Unit of the value, or null when unitless.
          title: Unit
      required:
        - name
        - type
        - unit
        - description
        - interpretation_hints
        - null_meaning
        - nullable
        - source
        - filter_ops
        - returnable
      title: SearchDiscoveryField
      type: object
    EndpointPricing:
      additionalProperties: false
      properties:
        charged_when:
          description: When a request is charged.
          title: Charged When
          type: string
        currency:
          const: USD
          title: Currency
          type: string
        plan_prices_usd:
          additionalProperties:
            type: string
          description: Price per unit on each plan, keyed by plan ID.
          title: Plan Prices Usd
          type: object
        price_usd:
          description: Price per unit on the Free plan, as a decimal string.
          title: Price Usd
          type: string
        unit:
          description: What one charge covers.
          enum:
            - parcel
            - query
          title: Unit
          type: string
      required:
        - currency
        - unit
        - price_usd
        - plan_prices_usd
        - charged_when
      title: EndpointPricing
      type: object

````