API

Web Search and Fetching

Use built-in web search and understand how URL fetching differs across Desktop, CLI, and API.

Web Search and URL Fetching

MaxLabs supports two different web capabilities:

  1. Web search — finding relevant information on the internet.
  2. URL fetching — opening and reading a specific webpage after you already know its URL.

The MaxLabs Desktop app and CLI support both.

Raw API users can use built-in web search directly, but arbitrary URL fetching must currently be implemented as a client-side tool.

Web search allows the model to retrieve current information that may not exist in its training data or conversation context.

Typical uses include:

  • Recent news
  • Current documentation
  • Latest software releases
  • Pricing
  • Product changes
  • Company announcements
  • Current public data
  • Up-to-date technical information

Web search is available through MaxLabs Desktop, CLI, and API.

Enabling Web Search in the API

{
  "model": "worker",
  "messages": [
    {
      "role": "user",
      "content": "What happened today?"
    }
  ],
  "web_search": "auto",
  "web_search_uses": 4
}

web_search controls whether search is disabled, optional, or required.

web_search_uses controls the maximum number of searches the model may perform for the request.

Search Modes

auto

The model decides whether search is needed.

This is usually the best default for general-purpose agents.

always

The model searches before every answer.

Use it when freshness is fundamental to the application, such as news, market research, current product research, release tracking, or live documentation lookup.

off or omitted

The model will not search the internet.

Use this when the task only depends on supplied context, external information is unnecessary, or you manage retrieval through your own tools.

Search Budget

Searches are capped at 10 per request.

Workload Suggested Searches
Simple current fact 1–2
Technical documentation lookup 2–4
Product comparison 3–6
Broader research 5–10

More searches do not automatically produce a better answer.

Search Billing

Web search is billed separately through provider usage.

Avoid unnecessary searches when the information is already present, stable, or previously retrieved.

Search and Fetch Are Different

Web search finds relevant pages.

URL fetching reads the contents of a specific page.

Search
  ↓
Find relevant URLs
  ↓
Fetch selected pages
  ↓
Read page contents
  ↓
Reason over the retrieved information

Desktop and CLI support this complete workflow.

Raw API users currently need to provide the URL-fetching step themselves.

Desktop and CLI

MaxLabs Desktop and CLI allow the agent to:

  • Search the web
  • Identify relevant results
  • Fetch specific pages
  • Read their contents
  • Continue reasoning over the retrieved information

You do not need to implement URL fetching yourself.

URL Fetching for API Users

MaxLabs Gateway does not currently fetch arbitrary URLs on behalf of API clients.

If you want the model to open a webpage, expose a tool such as fetch_url.

{
  "type": "function",
  "function": {
    "name": "fetch_url",
    "description": "Retrieve readable content from a public HTTP or HTTPS URL.",
    "parameters": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "The public URL to fetch."
        }
      },
      "required": ["url"]
    }
  }
}

The flow is:

User request
    ↓
Model searches if needed
    ↓
Model identifies a useful URL
    ↓
Model calls fetch_url
    ↓
Your application performs the request
    ↓
Your application returns page content
    ↓
Model continues reasoning

Designing a Safe fetch_url Tool

Arbitrary URL fetching is security-sensitive.

A production fetcher should account for:

  • SSRF
  • Private IP ranges
  • Internal hostnames
  • Redirects
  • Cloud metadata endpoints
  • Very large responses
  • Binary files
  • Infinite streams
  • Compression bombs
  • Malformed HTML
  • Authentication
  • Cookies
  • JavaScript-heavy pages
  • Timeouts
  • Content types

Restrict normal web retrieval to http:// and https://.

Block localhost, loopback addresses, RFC1918 private networks, link-local addresses, cloud metadata endpoints, and internal DNS names.

Revalidate every redirect.

Use connection, read, and overall request timeouts.

Limit raw response size and extracted text size.

Define the content types your fetcher supports.

Where possible, extract readable content rather than returning raw HTML.

Return Source Metadata

A useful fetch result may look like:

{
  "requested_url": "https://example.com/docs",
  "final_url": "https://docs.example.com/latest",
  "status": 200,
  "content_type": "text/html",
  "title": "Documentation",
  "content": "...",
  "truncated": false
}

This gives the model clear provenance and useful retrieval metadata.

If prompt caching matters, keep this output format deterministic where practical.

Search First, Fetch Selectively

A good research workflow is:

  1. Search.
  2. Identify the strongest results.
  3. Fetch only the most useful pages.
  4. Reason over those sources.
  5. Fetch additional pages only when necessary.

The goal is enough high-quality evidence, not maximum retrieval.

Prefer Primary Sources

For factual or technical questions, prefer official documentation, vendor changelogs, release notes, project repositories, product documentation, and standards bodies where possible.

Search Complements Repository Inspection

Web search should complement repository inspection rather than replace it.

External information tells the agent what changed.

Repository context tells it what must change in your application.

Treat Fetched Content as Untrusted

Fetched webpage content is external input.

It may contain incorrect information, outdated documentation, user-generated content, malicious instructions, or prompt-injection attempts.

The model should treat retrieved page content as data, not privileged instructions.

Desktop, CLI, and API Compared

Capability Desktop CLI Raw API
Web search Yes Yes Yes
Search mode controls Yes Yes Yes
Search budget controls Yes Yes Yes
Fetch arbitrary URLs Yes Yes Client implements
Safe URL fetching Built in Built in Client implements
Tool execution loop Built in Built in Client handles

For most integrations:

  1. Use web_search: "auto" unless every request depends on fresh information.
  2. Keep web_search_uses reasonably small by default.
  3. Increase search budget only for research-heavy tasks.
  4. Expose a dedicated fetch_url tool when full page contents are needed.
  5. Execute arbitrary network requests on infrastructure you control.
  6. Restrict fetching to safe URL schemes.
  7. Block private and metadata network ranges.
  8. Revalidate every redirect.
  9. Use strict timeouts and response-size limits.
  10. Extract readable content instead of unnecessary raw HTML.
  11. Return source URLs and useful metadata.
  12. Prefer authoritative first-party sources.
  13. Treat fetched content as untrusted external data.
  14. Keep tool-result serialization deterministic where practical.
  15. Fetch only pages likely to materially improve the answer.

Search discovers information.

Fetch retrieves the source itself.

MaxLabs provides web search across Desktop, CLI, and API.

Desktop and CLI also provide the URL-fetching layer.

For raw API integrations, you retain control over arbitrary URL access by exposing and executing the appropriate tool yourself.