Andi AI Search API

openapi: 3.2.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 27 fixed topics, with an optional `q` keyword filter. Search and fetch support `format=context`, which returns markdown suited to language models; the news endpoint also returns RSS and an HTML widget. 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: []
tags:
- name: Search
paths:
  /api/v1/search:
    get:
      operationId: search
      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.
      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.2 seconds. `balanced` is everyday web search, about 3–4 seconds. `deep` searches from multiple angles with spell correction, about 6.5 seconds. `exhaustive` is Andi''s most thorough mode: more sources and more time, up to about 15 seconds; for a question with several parts or steps it searches each part. Deeper modes add query expansion, follow-up searches fanned out from initial queries, 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` gives the most complete results and also searches each part of a question — 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. `small` is the lightest and fastest; `medium` and above apply stronger 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 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`, `content=true` or `content=focused`; pass `extracts=false` to turn them off in those cases. Also returned by default with `metadata=full`.
        schema:
          type: boolean
          default: false
      - name: content
        in: query
        description: Include each result's full page text, in `reader.markdown` (or `reader.content` when the page has no markdown version). `true` returns the head of each page. `focused` returns the parts of each page that answer the query, in page order under section headings; it is billed and capped like `true` and falls back to the normal page text when no focused text can be built. Any other value is treated as `false`. Also turns on `extracts` unless `extracts=false` is passed. Adds time and cost; deeper modes allow more time.
        schema:
          type: string
          enum:
          - 'true'
          - focused
          - 'false'
          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: timeout
        in: query
        description: Target time in milliseconds for ranked results (1000–30000). It is a target, not a hard ceiling. Omit it for the mode's normal speed; a larger value (e.g., 30000) lets slower sources run longer, so deep/exhaustive searches can take close to that long. The search may run a little past it when it needs a moment more to return a useful page. Values below 1000 are raised to 1000; values above 30000 are lowered to 30000; 0, empty or non-numeric values are ignored.
        schema:
          type: integer
      responses:
        '200':
          description: Successful search results
          content:
            application/json:
              schema:
                type: object
      tags:
      - Search