Web Search API for LLM Agents#

POST /v2/lookup is a web search API built for LLM agents: it runs a search in one of six categories and hands back a flat, provider-neutral result list. Set perceive_top and it also renders the top-N result URLs in a real browser, so an agent gets the search-engine results page (SERP) and the page content behind each hit in a single round trip. As a SERP API alternative it collapses the usual stack (hit a search API, parse its results, then fan out a scraper) into one call. It will be EnConvert's answer to Firecrawl /search.

Serper is the search provider behind it. The request and response speak a neutral search vocabulary (category, country, locale, time_filter), so a future provider swap does not change the contract you code against.

Here is the smallest useful call. Send a query, get the top web results back:

curl -X POST https://api.enconvert.com/v2/lookup \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "headless chrome pdf rendering"
  }'

The response is a flat result list plus provenance for support correlation:

{
    "lookup_id": 81423,
    "query": "headless chrome pdf rendering",
    "category": "web",
    "total": 10,
    "results": [
        {
            "title": "Generate PDFs with headless Chrome",
            "url": "https://example.com/guide/chrome-pdf",
            "snippet": "Render a page and print it to PDF...",
            "position": 1
        },
        {
            "title": "Print to PDF with the Chrome DevTools Protocol",
            "url": "https://example.dev/cdp/print-to-pdf",
            "snippet": "Page.printToPDF returns base64 PDF data...",
            "position": 2
        }
    ],
    "perceive_top": 0,
    "perceive_operation_ids": [],
    "credits": 1,
    "cost_cents": 0.06,
    "warnings": []
}

Endpoints#

/v2/lookup is a single-call endpoint with no separate status or retrieval path. When you auto-perceive, each rendered page becomes a first-class perceive operation with its own operation_id, which you can re-fetch later through GET /v2/perceive/{operation_id}.

Content-Type: application/json.

Authentication#

Authenticate with a private key in the X-API-Key header for server-to-server calls. This is the path the examples below use.

X-API-Key: sk_your_private_key

Public keys with a JWT bearer token also work, using the same flow as every other endpoint: generate a token with your pk_ key, then send it as Authorization: Bearer <token>. The full flow, including domain locking and token refresh, is in the authentication guide.

Each API key carries an allowed-endpoints allowlist. If /v2/lookup is not on the key's list, the request is rejected with 403.

How lookup works#

One request runs one provider search and, only if you ask for it, renders the top results afterward.

1. Quota gate. Before anything bills, the handler checks your plan's unified monthly ops allowance. A disabled plan or an exhausted allowance is rejected with 402, so nothing is charged on a rejection.
2. Search. The query goes to the search provider (Serper) on the endpoint for your category. Recency, country, locale, location, page size, and autocorrect map onto the provider's parameters.
3. Normalise. Each provider hit is flattened into a neutral LookupResult carrying title, url, snippet, and position. The category-specific extras land in extra so the contract never grows a column per provider quirk.
4. Charge and audit. The search succeeded, so one op is billed and one ch_lookup_queries audit row is written. The row id comes back as lookup_id for support correlation.
5. Auto-perceive (optional). If perceive_top > 0, the top-N result URLs are rendered one at a time through the shared headless Chrome singleton, the same pipeline as the perceive endpoint. Each render is a full /v2/perceive operation: its own op billed against the shared allowance, its own operation row, its own operation_id. By default auto-perceive requests Markdown only, with no screenshot, PDF, or LLM extraction; send an enrich object to widen the outputs, run them in parallel, or add schema extraction and a synthesized answer.

Auto-perceive is best-effort. A single URL that fails, or the ops allowance running out part-way through, degrades to a warning and still returns the search results. The SERP is the primary product here, so a perception problem never sinks the whole call.

Request parameters#

Query and category#

Targeting and recency#

Pagination#

Auto-perceive#

Enrichment (enrich)#

An optional enrich object tunes how the top-N results (perceive_top) are read, and can synthesize one grounded answer across them. When enrich is omitted, perceive_top keeps its default behaviour (Markdown-only, one result at a time).

enrich.schema and enrich.synthesize_answer use the LLM extraction tier. If that extraction step cannot run, they degrade to a warning and the rest of the response is unaffected.

{
  "query": "best open-source vector databases",
  "perceive_top": 3,
  "enrich": {
    "outputs": ["markdown"],
    "concurrency": 3,
    "synthesize_answer": true
  }
}

Categories#

Each category hits a different provider endpoint and surfaces a slightly different result shape. The universal fields (title, url, snippet, position) are always typed; category-specific fields land in extra.

Worth flagging: for images and maps, url can be null for a given hit when the provider returns no navigable link. Auto-perceive skips any result whose url is null, so a perceive_top of 5 on a SERP with two URL-less hits perceives at most three pages.

Response#

The endpoint omits null fields, so a minimal web result carries only the fields that are actually populated.

LookupResult#

Reading auto-perceive results#

When you send perceive_top, walk the results and check for the perceive field. It is present only on the results that were perceived, and only when their render succeeded. The Markdown for each lives behind a pre-signed download URL (a short-lived, signed link to object storage) under perceive.outputs.markdown.url, the same as a direct perceive call.

{
    "lookup_id": 81910,
    "query": "react server components data fetching",
    "category": "web",
    "total": 10,
    "results": [
        {
            "title": "Data fetching with RSC",
            "url": "https://example.com/rsc/data",
            "snippet": "Fetch on the server, stream to the client...",
            "position": 1,
            "perceive": {
                "operation_id": "per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7",
                "status": "completed",
                "url": "https://example.com/rsc/data",
                "outputs": {
                    "markdown": {
                        "url": "https://spaces.example.com/...signed...",
                        "size_bytes": 7421,
                        "content_type": "text/markdown; charset=utf-8",
                        "expires_in": 900
                    }
                },
                "cost_cents": 0.0,
                "duration_ms": 5840
            }
        }
    ],
    "perceive_top": 1,
    "perceive_operation_ids": [
        "per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7"
    ],
    "credits": 1,
    "cost_cents": 0.06,
    "warnings": []
}

Those signed URLs expire after 15 minutes. To download a perceived page later, re-fetch its operation with GET /v2/perceive/{operation_id} using the id from perceive_operation_ids. That re-signs the URLs and does not re-render, so it costs no ops. See the perceive retrieve section for the details.

Code examples#

curl: web search#

curl -X POST https://api.enconvert.com/v2/lookup \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "open source vector database",
    "num_results": 20
  }'

curl: recent news, localised#

curl -X POST https://api.enconvert.com/v2/lookup \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "rbi monetary policy",
    "category": "news",
    "country": "in",
    "locale": "en",
    "time_filter": "week"
  }'

curl: search plus auto-perceive the top 3#

curl -X POST https://api.enconvert.com/v2/lookup \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "langchain retrieval augmented generation",
    "perceive_top": 3
  }'

Python#

import requests

response = requests.post(
    "https://api.enconvert.com/v2/lookup",
    headers={"X-API-Key": "sk_your_private_key"},
    json={
        "query": "langchain retrieval augmented generation",
        "perceive_top": 3,
    },
)
response.raise_for_status()
data = response.json()

# Pull the Markdown of every result that was perceived
for result in data["results"]:
    perceived = result.get("perceive")
    if not perceived:
        continue
    markdown_url = perceived["outputs"]["markdown"]["url"]
    page_text = requests.get(markdown_url).text
    print(result["url"], len(page_text), "chars")

for note in data["warnings"]:
    print("warning:", note)

Node.js#

const res = await fetch("https://api.enconvert.com/v2/lookup", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "sk_your_private_key"
    },
    body: JSON.stringify({
        query: "langchain retrieval augmented generation",
        perceive_top: 3
    })
});

const data = await res.json();

// Pull the Markdown of every result that was perceived
for (const result of data.results) {
    if (!result.perceive) continue;
    const markdownUrl = result.perceive.outputs.markdown.url;
    const pageText = await fetch(markdownUrl).then(r => r.text());
    console.log(result.url, pageText.length, "chars");
}

for (const note of data.warnings) {
    console.log("warning:", note);
}

If you call EnConvert from Claude, Cursor, or another Model Context Protocol (MCP) client, the search capability will be exposed as a tool there too. See the MCP server page.

Error responses#

The handler never echoes raw provider text to the client. Provider and SSRF detail stays in the server logs, and the client gets a clean, generic message.

A failing auto-perceive never raises an error of its own. It lands in warnings and the call still answers 200. The full status-code reference is in the error-codes guide.

Limits#

Frequently asked questions#

How do I run a web search and get page content back in one REST API call?#

Send POST /v2/lookup with a query and set perceive_top (0–10). The top-N result URLs are rendered in a real browser, and each perceived result carries an inline perceive object whose Markdown sits behind a pre-signed URL at perceive.outputs.markdown.url.

Is /v2/lookup a SERP API alternative I can adopt without provider lock-in?#

Yes. Serper is the search provider behind it, but the request and response speak a neutral search vocabulary (category, country, locale, time_filter), so a future provider swap does not change the contract you code against.

What search categories does the lookup API support?#

Six: web (the default), news, images, scholar, patents, and maps. The universal fields (title, url, snippet, position) are always typed, and category-specific extras land in extra.

Why did lookup perceive fewer pages than my perceive_top value?#

Auto-perceive skips results whose url is null, stops if the monthly ops allowance runs out mid-loop, and degrades a failed render to a warning. The response's perceive_top reports how many pages were actually perceived, and warnings explains the gaps.