Quickstart: Make your first Web IQ API calls

Make your first Microsoft Web IQ REST API call in a few minutes. You will search the web, inspect the response, and then extract content from a known URL.

API keys are the fastest way to evaluate Web IQ. For production workloads, use Microsoft Entra ID.

Prerequisites

Tip

Use the Web IQ Playground to send requests from the browser and generate code in cURL, Python, JavaScript, C#, Java, Go, and Ruby.

1. Store your API key

Put the key in an environment variable so the request examples do not repeat it or place it in your source code.

macOS or Linux

export WEBIQ_API_KEY="your-api-key"

Windows PowerShell

$env:WEBIQ_API_KEY="your-api-key"

Warning

Don't commit your key to source control or expose it in browser or client-side code. Store production credentials in a secret manager.

2. Search the web

Use Web Search when you have a question or query and want Web IQ to discover and rank relevant pages.

We recommend starting with maxResults = 10, contentFormat = passage, and maxLength = 3000 (the defaults) as an optimized operating point. From there, you can fine-tune these settings based on your use case.

Endpoint: POST https://api.microsoft.ai/v3/search/web

cURL

curl --request POST "https://api.microsoft.ai/v3/search/web" \
  --header "x-apikey: $WEBIQ_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "query": "latest developments in retrieval augmented generation",
    "maxResults": 10,
    "contentFormat": "passage",
    "maxLength": 3000
  }'

Python

import os
import json
import requests

response = requests.post(
    "https://api.microsoft.ai/v3/search/web",
    headers={
        "x-apikey": os.environ["WEBIQ_API_KEY"],
        "content-type": "application/json",
    },
    json={
        "query": "latest developments in retrieval augmented generation",
        "maxResults": 10,
        "contentFormat": "passage",
        "maxLength": 3000,
    },
    timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

JavaScript

Save this example as search.mjs and run it with node search.mjs.

const response = await fetch("https://api.microsoft.ai/v3/search/web", {
  method: "POST",
  headers: {
    "x-apikey": process.env.WEBIQ_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    query: "latest developments in retrieval augmented generation",
    maxResults: 10,
    contentFormat: "passage",
    maxLength: 3000,
  }),
});

if (!response.ok) {
  throw new Error(`Web Search failed: ${response.status} ${await response.text()}`);
}

console.log(JSON.stringify(await response.json(), null, 2));

3. Understand the response

A successful Web Search returns a webResults array. This abbreviated example shows the fields you will use most often:

{
  "webResults": [
    {
      "title": "Example result",
      "url": "https://example.com/article",
      "content": "The query-relevant passage extracted from the page...",
      "crawledAt": "2026-07-18T12:00:00Z"
    }
  ],
  "traceId": "00000000000000000000000000000000"
}
  • title and url identify the source.
  • content contains the query-relevant passage because the request used contentFormat: "passage".
  • traceId helps Web IQ Support investigate a request.

Across REST responses and MCP tool results, model fields with null, empty string (""), or empty list/array ([]) values are omitted, including fields of nested result objects. Treat an absent string field as unavailable and an absent list field as having no items. Whitespace-only strings, false, 0, empty dictionaries, individual array/dictionary entries, and embedded raw JSON are preserved. Root arrays and protocol-envelope collections such as MCP content are unchanged.

See the Web Search API reference for all parameters and response fields.

4. Choose Web Search or Browse

Start with Use What you get
A question or search query Web Search Ranked pages with query-relevant content
A specific URL Browse Extracted content from that page

A common grounding workflow uses both endpoints: search for relevant sources, select a result URL, then browse that URL when you need more complete page content.

5. Extract content from a URL

Use Browse when you already know which page you want to read. liveCrawl: "fallback" asks Web IQ to crawl the page when it is not already available in the index.

Endpoint: POST https://api.microsoft.ai/v3/browse

cURL

curl --request POST "https://api.microsoft.ai/v3/browse" \
  --header "x-apikey: $WEBIQ_API_KEY" \
  --header "content-type: application/json" \
  --data '{
    "url": "https://news.microsoft.com/source/",
    "contentFormat": "markdown",
    "maxLength": 3000,
    "liveCrawl": "fallback"
  }'

Python

import os
import json
import requests

response = requests.post(
    "https://api.microsoft.ai/v3/browse",
    headers={
        "x-apikey": os.environ["WEBIQ_API_KEY"],
        "content-type": "application/json",
    },
    json={
        "url": "https://news.microsoft.com/source/",
        "contentFormat": "markdown",
        "maxLength": 3000,
        "liveCrawl": "fallback",
    },
    timeout=30,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))

JavaScript

Save this example as browse.mjs and run it with node browse.mjs.

const response = await fetch("https://api.microsoft.ai/v3/browse", {
  method: "POST",
  headers: {
    "x-apikey": process.env.WEBIQ_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    url: "https://news.microsoft.com/source/",
    contentFormat: "markdown",
    maxLength: 3000,
    liveCrawl: "fallback",
  }),
});

if (!response.ok) {
  throw new Error(`Browse failed: ${response.status} ${await response.text()}`);
}

console.log(JSON.stringify(await response.json(), null, 2));

A successful 200 response includes the page url, title, extracted content, and a traceId. A live crawl can return 202 with retryAfter; wait for that duration, then send the same request again. See the Browse API reference for the complete response contract.

Troubleshooting

Status What to check
401 Unauthorized Confirm WEBIQ_API_KEY is set and the request sends it in the x-apikey header.
415 Unsupported Media Type Send content-type: application/json.
429 Too Many Requests Wait before retrying and reduce request frequency.
Browse 404 Not Found Confirm the URL is public and valid. Use liveCrawl: "fallback" when indexed content might be unavailable.
Browse 202 Accepted Wait for the returned retryAfter duration, then retry the same request.

For other failures, save the traceId and see Error Handling or contact Web IQ Support.

Next steps

  • Last updated on