Search

Search across the web

curl --request POST \
  --url https://906e-2001-5a8-6cc-e000-55c0-f0b-9da7-10b0.ngrok-free.app/search \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "mode": "auto",
  "depth": "basic",
  "topic": "general",
  "max_results": 10,
  "add_answer": false,
  "include_raw_content": false,
  "include_images": false,
  "recency": "day",
  "filters": {
    "include_domains": [
      "<string>"
    ],
    "exclude_domains": [
      "<string>"
    ],
    "include_text": [
      "<string>"
    ],
    "exclude_text": [
      "<string>"
    ]
  },
  "view": [
    "results"
  ],
  "similar_to": "<string>",
  "stream": true,
  "response_format": "json",
  "user_context": {}
}
'

{
  "data": {
    "answer": "<string>",
    "results": [
      {
        "title": "<string>",
        "url": "<string>",
        "content": "<string>",
        "score": 0.5,
        "meta": {}
      }
    ],
    "images": [
      {
        "url": "<string>",
        "alt": "<string>"
      }
    ],
    "embeddings": [
      [
        123
      ]
    ]
  },
  "request_id": "<string>",
  "meta": {
    "api_version": "<string>",
    "processing_ms": 123,
    "tokens_used": 123,
    "cost": {
      "total": 1,
      "breakdown": {}
    }
  }
}

POST

Search across the web

curl --request POST \
  --url https://906e-2001-5a8-6cc-e000-55c0-f0b-9da7-10b0.ngrok-free.app/search \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "mode": "auto",
  "depth": "basic",
  "topic": "general",
  "max_results": 10,
  "add_answer": false,
  "include_raw_content": false,
  "include_images": false,
  "recency": "day",
  "filters": {
    "include_domains": [
      "<string>"
    ],
    "exclude_domains": [
      "<string>"
    ],
    "include_text": [
      "<string>"
    ],
    "exclude_text": [
      "<string>"
    ]
  },
  "view": [
    "results"
  ],
  "similar_to": "<string>",
  "stream": true,
  "response_format": "json",
  "user_context": {}
}
'

{
  "data": {
    "answer": "<string>",
    "results": [
      {
        "title": "<string>",
        "url": "<string>",
        "content": "<string>",
        "score": 0.5,
        "meta": {}
      }
    ],
    "images": [
      {
        "url": "<string>",
        "alt": "<string>"
      }
    ],
    "embeddings": [
      [
        123
      ]
    ]
  },
  "request_id": "<string>",
  "meta": {
    "api_version": "<string>",
    "processing_ms": 123,
    "tokens_used": 123,
    "cost": {
      "total": 1,
      "breakdown": {}
    }
  }
}

Search for information with various retrieval strategies.

Example Request

curl -X POST https://api.agentserp.com/search \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "openai"}'

Body

application/json

Input contract for POST /search

query

string

required

Natural-language search query

mode

enum<string>

default:auto

Retrieval strategy: let backend choose, force keyword, or force embedding

Available options:

auto,

keyword,

neural

depth

enum<string>

default:basic

Depth/quality tier; advanced costs more & may run longer

Available options:

basic,

advanced

topic

enum<string>

default:general

Domain-specific retrieval agent

Available options:

general,

news

max_results

integer

default:10

Maximum number of results to return

Required range: 1 <= x <= 50

add_answer

default:false

false → no answer. basic → one-sentence LLM answer. detailed → richer

Available options:

true,

false

include_raw_content

boolean

default:false

If true, include cleaned HTML text in each result

include_images

boolean

default:false

If true, also run an image search

recency

Limit results to this many days in the past or a preset

Available options:

day,

week,

month,

year

filters

object

Fine-grained filtering for /search

Show child attributes

filters.include_domains

string[]

Restrict results to these hostnames

filters.exclude_domains

string[]

Omit any result whose hostname matches

filters.include_text

string[]

Require these tokens appear in document body

filters.exclude_text

string[]

Reject docs containing these tokens

view

enum<string>[]

Which data blocks to include in the response

Selective blocks to include in response

Available options:

results,

answer,

images,

embeddings

similar_to

string<uri>

Return docs similar to this URL instead of keyword search

stream

boolean

If true, respond with NDJSON streaming

response_format

enum<string>

Serialization format for large/bulk results

Available options:

json,

ndjson,

csv,

parquet

user_context

object

Opaque object echoed for personalization

Show child attributes

user_context.{key}

unknown

Response

Search results

Universal response wrapper

data

object

required

Endpoint-specific payload

Show child attributes

data.answer

string

LLM answer if requested

data.results

object[]

Ordered list of search hits

Show child attributes

data.results.title

string

required

Human-readable title of the document

data.results.url

string

required

Canonical URL of the document

data.results.content

string

Snippet or full text, depending on request

data.results.score

number

Relevance score (0-1) where 1 is most relevant

Required range: 0 <= x <= 1

data.results.meta

object

Backend-specific key-value pairs (author, publishedDate, etc.)

Show child attributes

data.results.meta.{key}

unknown

data.images

object[]

Show child attributes

data.images.url

string<uri>

required

data.images.alt

string

data.embeddings

number[][]

Vector embeddings in the same order as results

request_id

string

Echo of client-supplied ID or server-assigned UUID

Documentation

API Reference

Example Request

Body

Response

Documentation

API Reference

​Example Request

Body

Response

Example Request