> ## 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 > Performs a web search and returns structured results. Search effort is set automatically per query by default (`searchMode=auto`), with fixed modes (low-cost, fast, balanced, deep, exhaustive) available for manual control. Supports domain and date filtering, query operators, and multiple output formats. ## OpenAPI ````yaml /api-reference/openapi.json get /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: get: summary: Search the web description: >- Performs a web search and returns structured results. Search effort is set automatically per query by default (`searchMode=auto`), with fixed modes (low-cost, fast, balanced, deep, exhaustive) available for manual control. Supports domain and date filtering, query operators, and multiple output formats. operationId: search parameters: - name: q in: query required: true description: >- Search query string. Supports query operators when `parseOperators` is enabled. You can also pass a JSON array of up to 5 queries for multi-query searches (e.g., `["query one", "query two"]`). schema: type: string example: best programming languages - name: limit in: query description: Maximum number of results to return. schema: type: integer default: 10 minimum: 1 maximum: 100 - name: offset in: query description: Number of results to skip for pagination. schema: type: integer default: 0 minimum: 0 - name: searchMode in: query 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`). schema: type: string enum: - auto - low-cost - fast - balanced - deep - exhaustive default: auto - name: effort in: query 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. schema: type: string enum: - low - medium - high - max - name: reranker in: query 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. schema: type: string enum: - auto - small - medium - large - xl default: auto - name: intent in: query 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. Set `none` to disable intent detection entirely; `auto` is equivalent to omitting the parameter. schema: type: string examples: news: value: news summary: Latest news results video: value: video summary: Video search results images: value: images summary: Image search results weather: value: weather summary: Weather data wiki: value: wiki summary: Wikipedia/knowledge results code: value: code summary: Programming-related results recipe: value: recipe summary: Recipe results place: value: place summary: Business/place results time: value: time summary: Time query results - name: format in: query description: >- Response format. `json` returns a JSON object. `context` returns results as markdown text, suitable for passing to language models. schema: type: string enum: - json - context default: json - name: metadata in: query description: >- Level of metadata to include. `basic` includes standard search metrics. `full` includes extended metadata with content type details and reader data on results. schema: type: string enum: - basic - full default: basic - name: extracts in: query description: >- Include text extracts from result pages in the response. Defaults to `true` when `format=context`. schema: type: boolean default: false - name: content in: query 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`). schema: type: boolean default: false - name: enrichContent in: query deprecated: true description: >- Deprecated alias of `content`. Retained for backward compatibility; use `content` instead. schema: type: boolean default: false - name: maxContentLength in: query description: >- Maximum number of characters of enriched content to return per result. Only applies when `content` (or its deprecated alias `enrichContent`) is true. schema: type: integer - name: safe in: query description: >- Safe search filtering level. `off` disables filtering, `moderate` filters most explicit content, `strict` applies maximum filtering. schema: type: string enum: - 'off' - moderate - strict default: 'off' - name: country in: query description: Two-letter ISO 3166-1 country code to localize results. schema: type: string default: US example: US - name: sourceCountry in: query 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. schema: type: string example: GB - name: language in: query description: Two-letter ISO 639-1 language code to filter results by language. schema: type: string default: en example: en - name: units in: query description: >- Unit system for weather and calculation results. Defaults based on the `country` parameter — `imperial` for `US`, `metric` for all other countries. schema: type: string enum: - metric - imperial - name: noCache in: query description: Bypass cached results and fetch fresh data. schema: type: boolean default: false - name: dateRange in: query description: Relative date range filter for results. schema: type: string enum: - day - week - month - year - 24h - 7d - 30d - 90d - 1y - name: dateFrom in: query description: >- Filter results published on or after this date. Format: `YYYY-MM-DD`. schema: type: string format: date example: '2025-01-01' - name: dateTo in: query description: >- Filter results published on or before this date. Format: `YYYY-MM-DD`. schema: type: string format: date example: '2025-12-31' - name: includeDomains in: query description: >- Comma-separated list of domains to restrict results to. Supports wildcards (`*.example.com`). schema: type: string example: github.com,stackoverflow.com - name: excludeDomains in: query description: >- Comma-separated list of domains to exclude from results. Supports wildcards. schema: type: string example: pinterest.com,reddit.com - name: includeTerms in: query description: Comma-separated terms that must appear in results. schema: type: string - name: excludeTerms in: query description: Comma-separated terms to exclude from results. schema: type: string - name: parseOperators in: query description: >- Parse query operators (like `site:`, `filetype:`, `intitle:`) from the query string. When disabled, the query is treated as literal text. schema: type: boolean default: true - name: linkFormat in: query 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. schema: type: string enum: - link - url default: link - name: imageFormat in: query description: >- Field naming for image results. `long` (default) uses full field names. `short` uses abbreviated field names. schema: type: string enum: - short - long default: long - name: filetype in: query description: Filter results by file type. schema: type: string example: pdf - name: intitle in: query description: Filter results to pages with this term in the title. schema: type: string - name: inurl in: query description: Filter results to pages with this term in the URL. schema: type: string - name: intext in: query description: Filter results to pages with this term in the body text. schema: type: string 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' example: error: 'Missing required parameter: q' message: The q parameter is required '401': description: Unauthorized — missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Unauthorized message: Invalid API key '402': description: Insufficient credits — account balance depleted content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Insufficient Credits message: >- Your account has insufficient credits. Please add credits to continue. '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Too Many Requests message: Rate limit of N requests per second exceeded '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Internal server error message: Unknown 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). ````