{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/boardwalkai-com/json-schema/boardwalkai-com-ai-search-request-schema.json",
  "title": "AiSearchRequest",
  "description": "Strict AI-search input. Each individual geography array accepts at most 100 raw items (duplicates count). After deduplication, geography accepts at most 100 unique IDs total across state, county, and city fields, including singular and legacy aliases.",
  "x-generated": "2026-11-02",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/boardwalkai-com-openapi.yml#/components/schemas/AiSearchRequest",
  "type": "object",
  "additionalProperties": false,
  "anyOf": [
    {
      "required": [
        "query"
      ]
    },
    {
      "required": [
        "q"
      ]
    }
  ],
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Natural-language search query."
    },
    "q": {
      "type": "string",
      "minLength": 1,
      "description": "Alias for `query` (same vocabulary as structured search)."
    },
    "representation": {
      "type": "string",
      "enum": [
        "compact",
        "standard",
        "full"
      ],
      "default": "standard",
      "description": "How much of each record to return. Representation does not change the record price: County, State, and National are free; Standalone API Only and the free trial are 1 credit per new or changed record. Find Contact Info is billed separately. Also accepted as a `?representation=` query parameter."
    },
    "deliveryMode": {
      "type": "string",
      "enum": [
        "all"
      ],
      "default": "all",
      "description": "Only `all` is accepted on AI search; `deliveryMode=new` is supported on `GET /projects/search`. Other values return `400` rather than being ignored."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 10,
      "description": "Default is 10. Cap is 100. Prefer a low limit until cost is estimated."
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 999,
      "default": 0,
      "description": "Zero-based offset. The complete result window (`offset + limit`) may not exceed 1,000 on the AI-search job route."
    },
    "sort": {
      "type": "string",
      "enum": [
        "meeting_date",
        "updated_at",
        "data_richness"
      ],
      "default": "meeting_date"
    },
    "order": {
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ],
      "default": "desc"
    },
    "states": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "items": {
        "oneOf": [
          {
            "type": "integer",
            "minimum": 1
          },
          {
            "type": "string",
            "minLength": 1
          }
        ]
      },
      "description": "Optional state filter. Integer IDs, USPS abbreviations (`UT`), or names (`Utah`). Same vocabulary as `GET /projects/search`."
    },
    "stateIds": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "items": {
        "oneOf": [
          {
            "type": "integer",
            "minimum": 1
          },
          {
            "type": "string",
            "minLength": 1
          }
        ]
      },
      "description": "Alias of `states`. Integer IDs, USPS abbreviations, or names."
    },
    "stateId": {
      "oneOf": [
        {
          "type": "integer",
          "minimum": 1
        },
        {
          "type": "string",
          "minLength": 1
        }
      ],
      "description": "Optional single state: ID, USPS abbreviation, or name."
    },
    "state": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "items": {
        "oneOf": [
          {
            "type": "integer",
            "minimum": 1
          },
          {
            "type": "string",
            "minLength": 1
          }
        ]
      },
      "description": "Legacy alias for `states`."
    },
    "countyIds": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "items": {
        "type": "integer",
        "minimum": 1
      },
      "description": "Optional county ID filter from `/locations/states/{id}/counties`. Every ID must exist."
    },
    "countyId": {
      "type": "integer",
      "minimum": 1,
      "description": "Optional single county ID."
    },
    "county": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "items": {
        "type": "integer",
        "minimum": 1
      },
      "description": "Legacy alias for `countyIds`: integer IDs only, not names."
    },
    "cityIds": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "items": {
        "type": "integer",
        "minimum": 1
      },
      "description": "Optional city ID filter from nested cities location endpoint. Every ID must exist."
    },
    "cityId": {
      "type": "integer",
      "minimum": 1,
      "description": "Optional single city ID."
    },
    "city": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "items": {
        "type": "integer",
        "minimum": 1
      },
      "description": "Legacy alias for `cityIds`: integer IDs only, not names."
    },
    "type": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "items": {
        "type": "string",
        "minLength": 1
      },
      "description": "Optional land use type filter."
    },
    "subtype": {
      "type": "array",
      "minItems": 1,
      "maxItems": 100,
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "dateFrom": {
      "type": "string",
      "description": "Inclusive lower bound: YYYY, YYYY-MM, YYYY-MM-DD, or RFC3339."
    },
    "dateTo": {
      "type": "string",
      "description": "Inclusive upper bound: YYYY, YYYY-MM, YYYY-MM-DD, or RFC3339. Must not precede dateFrom."
    },
    "include": {
      "description": "Opt in to Find Contact Info for the projects this job will return. Paid plans and live trials. Off unless you send it.",
      "oneOf": [
        {
          "type": "string",
          "enum": [
            "contacts"
          ]
        },
        {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "contacts"
            ]
          }
        }
      ]
    },
    "contactOptions": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "minConfidence": {
          "type": "string",
          "enum": [
            "high",
            "medium"
          ],
          "default": "medium"
        },
        "maxProjects": {
          "type": "integer",
          "minimum": 1
        },
        "cachedOnly": {
          "type": "boolean",
          "default": false
        },
        "companyOnly": {
          "type": "boolean",
          "default": false
        }
      }
    },
    "notify": {
      "type": "object",
      "additionalProperties": false,
      "description": "Async jobs only. Controls the settlement email sent to the submitter's account address when the job reaches a terminal state (completed, partial, failed, or cancelled). The email is a pointer: counts, credits, and the poll URL, never record data. Unknown keys return `400`.",
      "properties": {
        "email": {
          "type": "boolean",
          "default": true,
          "description": "Send the settlement email. Defaults to true."
        }
      }
    }
  }
}