> ## Documentation Index > Fetch the complete documentation index at: https://docs.andiai.com/llms.txt > Use this file to discover all available pages before exploring further. # Search the web (JSON body) > Same contract as `GET /api/v1/search`, but accepts parameters as a JSON body. Preferred for location-bearing requests because GET-style location encoding is awkward and keeps `latitude`/`longitude` out of HTTP access logs. All GET query parameters are accepted as body fields, plus optional location fields (`latitude`, `longitude`, `accuracy`, `city`, `state`, `countryCode`, `postalCode`, `timezone`, `location`). ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/search openapi: 3.1.0 info: title: Andi AI Search API version: 1.7.0 description: >- Web search and page-fetch API for people and AI agents. `GET`/`POST /api/v1/search` returns structured results with query operators, domain and date filtering, and multiple output formats. `GET /api/v1/fetch` retrieves and extracts a single page. `GET /api/v1/news/:topic` returns a curated, ranked news feed for one of 23 fixed topics — no query required. Search and fetch support `format=context`, which returns markdown suited to language models; the news endpoint returns JSON only. By default (`searchMode=auto`) the API sets the search effort per query — compute, models, and depth — automatically; the fixed modes (`low-cost`, `fast`, `balanced`, `deep`, `exhaustive`) pin an effort level when you want the same behavior on every call. Requests are billed on outcome-based pricing, reported per call in `metrics.cost_dollars`. servers: - url: https://api.andiai.com description: Production security: - apiKey: [] paths: /api/v1/search: post: summary: Search the web (JSON body) description: >- Same contract as `GET /api/v1/search`, but accepts parameters as a JSON body. Preferred for location-bearing requests because GET-style location encoding is awkward and keeps `latitude`/`longitude` out of HTTP access logs. All GET query parameters are accepted as body fields, plus optional location fields (`latitude`, `longitude`, `accuracy`, `city`, `state`, `countryCode`, `postalCode`, `timezone`, `location`). operationId: searchPost requestBody: required: true content: application/json: schema: type: object required: - q properties: q: type: string description: >- Search query string. Same semantics as the GET `q` parameter. limit: type: integer default: 10 minimum: 1 maximum: 100 description: Maximum number of results to return. offset: type: integer default: 0 minimum: 0 description: Number of results to skip for pagination. searchMode: type: string enum: - auto - low-cost - fast - balanced - deep - exhaustive default: auto description: >- Search effort control. `auto` (default) sets the effort per query automatically — simple lookups resolve fast, complex questions get deeper treatment. The fixed modes pin an effort level: `low-cost` caps the work done per request for budget-constrained callers. `fast` returns results in about 1 second. `balanced` is everyday web search with mid-range latency. `deep` searches from multiple angles with spell correction in about 2–3 seconds. `exhaustive` runs multi-round retrieval for the most complete results, up to about 15 seconds. Deeper modes add query expansion, follow-up searches fanned out from initial results, and stronger reranking. Requests are billed on outcome-based pricing (see `metrics.cost_dollars`). effort: type: string enum: - low - medium - high - max description: >- Thoroughness dial, independent of `searchMode`: `low` favors speed, `medium` is balanced, `high` searches from multiple angles with spell correction, `max` runs multi-round retrieval for the most complete results — the same tiers as pinning `searchMode` to `fast`, `balanced`, `deep`, and `exhaustive` respectively. An explicit `searchMode` always wins over `effort`. With the default `auto` mode, an explicit `effort` pins its equivalent mode. Omit for the adaptive default. Invalid values return a `400` listing the valid tiers. reranker: type: string enum: - auto - small - medium - large - xl default: auto description: >- Semantic reranker size hint. Larger tiers apply more thorough relevance scoring but need a deeper `searchMode` and may be clamped by the request's time and cost budget (for example, `xl` needs `deep` or `exhaustive`). `auto` (default) selects a tier automatically based on the query and search mode. intent: type: string description: >- Force a specific search intent. When not set, the API auto-detects intent from the query. Accepts common aliases like `search`, `news`, `video`, `images`, `weather`, `wiki`, `code`, `recipe`, `place`, `time`, and others. format: type: string enum: - json - context default: json description: >- Response format. `json` returns a JSON object. `context` returns results as markdown text, suitable for passing to language models. metadata: type: string enum: - basic - full default: basic description: >- Level of metadata to include. `basic` includes standard search metrics. `full` includes extended metadata with content type details and reader data on results. extracts: type: boolean default: false description: Include text extracts from result pages in the response. enrichContent: type: boolean default: false description: >- Fetch and include full page content for results, beyond the standard description and snippet. Increases response time; the time budget scales with `searchMode` (more time is allotted for `deep` and `exhaustive`). maxContentLength: type: integer description: >- Maximum number of characters of enriched content to return per result. Only applies when `enrichContent` is true. safe: type: string enum: - 'off' - moderate - strict default: 'off' description: >- Safe search filtering level. `off` disables filtering, `moderate` filters most explicit content, `strict` applies maximum filtering. country: type: string default: US description: Two-letter ISO 3166-1 country code to localize results. sourceCountry: type: string description: >- Two-letter ISO 3166-1 country code to restrict results to sources from this country. Unlike `country`, which biases results by locale, `sourceCountry` excludes results from other countries. language: type: string default: en description: >- Two-letter ISO 639-1 language code to filter results by language. units: type: string enum: - metric - imperial description: >- Unit system for weather and calculation results. Defaults based on the `country` parameter — `imperial` for `US`, `metric` for all other countries. noCache: type: boolean default: false description: Bypass cached results and fetch fresh data. dateRange: type: string enum: - day - week - month - year - 24h - 7d - 30d - 90d - 1y description: Relative date range filter for results. dateFrom: type: string format: date description: >- Filter results published on or after this date. Format: `YYYY-MM-DD`. dateTo: type: string format: date description: >- Filter results published on or before this date. Format: `YYYY-MM-DD`. includeDomains: type: string description: >- Comma-separated list of domains to restrict results to. Supports wildcards (`*.example.com`). excludeDomains: type: string description: >- Comma-separated list of domains to exclude from results. Supports wildcards. includeTerms: type: string description: Comma-separated terms that must appear in results. excludeTerms: type: string description: Comma-separated terms to exclude from results. parseOperators: type: boolean default: true description: >- Parse query operators (like `site:`, `filetype:`, `intitle:`) from the query string. When disabled, the query is treated as literal text. linkFormat: type: string enum: - link - url default: link description: >- Field name for result URLs. Use `url` to receive the URL field as `url` instead of the default `link`. Only affects the `/search` endpoint. imageFormat: type: string enum: - short - long default: long description: >- Field naming for image results. `long` (default) uses full field names. `short` uses abbreviated field names. filetype: type: string description: Filter results by file type. intitle: type: string description: Filter results to pages with this term in the title. inurl: type: string description: Filter results to pages with this term in the URL. intext: type: string description: Filter results to pages with this term in the body text. latitude: type: number description: >- Latitude in decimal degrees. Sent in the body to keep coordinates out of HTTP access logs. longitude: type: number description: Longitude in decimal degrees. accuracy: type: number description: Location accuracy in meters. city: type: string description: City name for location-aware queries. state: type: string description: State or region name. countryCode: type: string description: >- Two-letter ISO 3166-1 country code for the caller's location. postalCode: type: string description: Postal or ZIP code. timezone: type: string description: IANA timezone, for example America/Los_Angeles. location: type: string description: >- Display name for the caller's location, for example "San Francisco, CA". example: q: best italian restaurants near me limit: 10 city: San Francisco state: California countryCode: US latitude: 37.7794 longitude: -122.4176 responses: '200': description: >- Search results. JSON by default; LLM-ready markdown with YAML frontmatter when `format=context`. content: application/json: schema: $ref: '#/components/schemas/SearchResponse' text/markdown: schema: type: string description: >- Markdown results with YAML frontmatter, returned when `format=context`. '400': description: Bad request — missing or invalid parameters content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized — missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: Insufficient credits — account balance depleted content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: SearchResponse: type: object properties: results_type: type: string description: >- The type of results returned (e.g., `Search`, `News`, `Weather`, `Calculator`). Determines which optional response sections are present. answer: type: string description: >- A generated answer for the query. May be an empty string when no direct answer is available. type: type: string description: Same as `results_type`. Indicates the category of results. title: type: string description: A title summarizing the search results. results: type: array description: Array of search results. items: $ref: '#/components/schemas/SearchResult' metrics: $ref: '#/components/schemas/Metrics' description: Search performance metrics. Always included in the response. correctedQuery: type: string description: >- Spell-corrected query. Present when a misspelling in the original query is detected and corrected — any mode can return it; deep and exhaustive modes run the strongest spell correction. related_searches: type: array description: Related search suggestions. Present on some queries. items: type: string topics: type: array description: Related topics. Present on some queries. items: type: string videos: type: array description: Video results. Present when the query triggers a video intent. items: $ref: '#/components/schemas/SearchResult' images: type: array description: Image results. Present when the query triggers an image intent. items: $ref: '#/components/schemas/ImageResult' news: type: array description: News results. Present when the query triggers a news intent. items: $ref: '#/components/schemas/SearchResult' places: type: array description: Place/business results. Present for location-related queries. items: $ref: '#/components/schemas/SearchResult' profiles: type: array description: Profile results. Present for people-related queries. items: $ref: '#/components/schemas/SearchResult' social: type: array description: Social media results. Present for social-related queries. items: $ref: '#/components/schemas/SearchResult' academic: type: array description: Academic results. Present for scholarly queries. items: $ref: '#/components/schemas/SearchResult' weather: $ref: '#/components/schemas/WeatherResult' description: Weather data. Present when the query triggers a weather intent. calculation: $ref: '#/components/schemas/CalculationResult' description: >- Calculation result. Present when the query triggers a calculation intent. required: - results_type - answer - type - title - results - metrics Error: type: object properties: error: type: string description: Error type or message. message: type: string description: Detailed error description. required: - error - message SearchResult: type: object properties: title: type: string description: Page title. link: type: string format: uri description: Page URL. desc: type: string description: Page description or summary. source: type: string description: Domain name of the result. type: type: string description: Result type. Only included when `metadata=full`. enum: - website - blog - news - video - image - place - profile - social - academic - calculation - weather - computation - instant answer date: type: string description: Publication date of the content, when available. image: type: string format: uri description: >- Preview image URL, when available. Only included when `metadata=full`. snippet: type: string description: >- Query-relevant text excerpt from the page. Distinct from `desc`, which is the general page description. answer: type: string description: Inline answer for instant answer results. extracts: type: array items: type: string description: >- Text extracts from the page, when available. Only included when `extracts=true`. contentType: type: string description: Content type of the page. Only included when `metadata=full`. reader: type: object description: >- Reader data with extracted page content. Only included when `metadata=full`. contentSafety: type: object description: Safety classification. Only included when `metadata=full`. properties: rating: type: string enum: - safe - unsafe - unknown description: Content safety rating. safeSearchApplied: type: boolean description: Whether safe-search filtering was applied to this result. bang: type: string description: >- Bang shortcut for the result domain. Only included when `metadata=full`. required: - title - link - desc - source Metrics: type: object description: Search performance metrics. Always included in the response. properties: query: type: string description: The query as processed. intent: type: string description: The detected or forced search intent. timestamp: type: string description: Timestamp of the search request. duration: type: number description: Total request duration in milliseconds. queries_executed: type: integer description: Number of search queries executed. api_requests_count: type: integer description: Number of API requests made during the search. results_returned: type: integer description: Number of results returned in this response. total_results_found: type: integer description: Total number of results found across all sources. cached: type: boolean description: >- Whether the response was served from cache. Only present on cache hits. cache_age_seconds: type: integer description: Age of the cached response in seconds. Only present on cache hits. cost_dollars: type: number description: >- Amount charged to your account for this request in USD, after any discounts. Pricing is outcome-based — each request is charged for the work performed and the content delivered, whether the effort was set automatically (`auto`) or pinned with a fixed mode. effort: type: string enum: - low - medium - high - max description: >- Resolved effort tier for this request — the tier `auto` mode selected, or the one pinned via `searchMode`/`effort`. response_time_ms: type: integer description: Total server response time in milliseconds. ImageResult: type: object properties: title: type: string description: Image title or alt text. link: type: string format: uri description: URL of the page containing the image. image: type: string format: uri description: Direct URL of the full-size image. source: type: string description: Domain name of the image source. type: type: string description: Always `image`. enum: - image thumbnail: type: string format: uri description: Thumbnail URL. width: type: string description: Image width in pixels (as a string). height: type: string description: Image height in pixels (as a string). required: - title - link - image - source - type WeatherResult: type: object properties: location: type: object description: Location details. properties: name: type: string description: Location name. country: type: string description: Country name or code. coordinates: type: object properties: latitude: type: number longitude: type: number temperature: type: number description: Current temperature. feelsLike: type: number description: Feels-like temperature. units: type: string description: 'Unit system: `metric` or `imperial`.' enum: - metric - imperial description: type: string description: Weather condition description. humidity: type: number description: Humidity percentage. windSpeed: type: number description: Wind speed. windDirection: type: number description: Wind direction in degrees. pressure: type: number description: Atmospheric pressure. icon: type: string description: Weather icon identifier. cloudiness: type: number description: Cloud cover percentage. visibility: type: number description: Visibility distance. timestamp: type: string description: Timestamp of the weather data. required: - location - temperature - units - description CalculationResult: type: object properties: expression: type: string description: The mathematical expression. result: type: string description: The calculated result. required: - expression - result securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: API key from the [API Console](https://console.andiai.com). ````