# Microsoft Web IQ API > Microsoft Web IQ provides real-time web grounding for LLMs and AI agents — web search, news, videos, images, and direct URL content extraction (Browse). Available via REST API and as an MCP (Model Context Protocol) server. Authenticate with an API key (`x-apikey`) or an Entra ID OAuth 2.0 token (`Authorization: Bearer`). Base URL: `https://api.microsoft.ai/v3/`. MCP endpoint: `https://api.microsoft.ai/v3/mcp`. Get a key in the [Microsoft Web IQ Portal](https://webiq.microsoft.ai/profiles/). Support: [Web IQ Support](https://aka.ms/microsoft-webiq-support). This single file contains the full developer documentation for Microsoft Web IQ v3, intended for LLMs and coding assistants (Cursor, GitHub Copilot, Claude, etc.) to consume in one pass without following links. Production GA services: **Web Search**, **Videos Search**, **Browse**, **News Search**, **Images Search**. ## Table of Contents - Quick Start - Authentication (API Key, Entra ID) - REST API Reference - Web Search - Videos Search - Browse - News Search - Images Search - Auto (Beta) - MCP Server - Error Handling - Supported Languages and Regions - Instrumentation - Portal (account & key management) --- ## Quick Start *Source: `app/documentation/_raw/Quick-Start.md`* ### Purpose This guide helps developers quickly make their first successful call to the Microsoft Web IQ API. ### What are the Microsoft Web IQ APIs? Microsoft Web IQ APIs provide the most up-to-date and accurate web results across multiple modalities such as web, news, videos, and browse for agentic consumption. These APIs provide grounding information to generate accurate and comprehensive LLM responses. ### Basic Requirements - Ability to run terminal commands or an API client (like Bruno) - Basic familiarity with JSON - Authentication credentials (API Key or Entra ID access token). Usage of the API is subject to the terms of your agreement with Microsoft. ### Authentication There are two ways to authenticate. #### API Key Create an API Key in the [Microsoft Web IQ Portal](https://webiq.microsoft.ai/profiles/) and pass it via the `x-apikey` header. #### Entra ID (OAuth 2.0 Client Credentials) Use Entra ID OAuth 2.0 Client Credentials (app-only token). **Prerequisites:** 1. **Set up a tenant** — An Azure tenant is required to register your app. If your organization already has an Azure subscription or M365 organization you already have a tenant; otherwise [provision a new tenant](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-create-new-tenant). 2. **Create an App Registration** — Registers your application with the Microsoft identity platform. See [Register an app](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app). Registration produces a Client ID, Object ID, and Directory ID. **Setup steps:** 1. **App Registration** — Use your existing Entra ID app registration (or create one). Note your Application (Client) ID — you'll need it in the next step. 2. **Bind your App Registration in the Portal** — In the Microsoft Web IQ Portal, go to **Profile Management** and select the **Application (Client) IDs** tab. Click **Bind Application (Client) ID** and enter your Application (Client) ID (a GUID). Profile updates may take up to ~1 minute to sync. 3. **Acquire a token** — Client credentials grant via MSAL: - Authority: `https://login.microsoftonline.com/{your-tenant-id}` - Scope: `https://api.microsoft.ai/.default` ### Your First API Call (cURL) Using API Key: ```bash curl -X POST "https://api.microsoft.ai/v3/search/web" \ -H "x-apikey: YOUR_API_KEY_HERE" \ -H "Content-Type: application/json" \ -d '{"query": "Latest AI trends"}' ``` Using Entra ID access token: ```bash curl -X POST "https://api.microsoft.ai/v3/search/web" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"query": "Latest AI trends"}' ``` On Windows PowerShell, use `curl.exe` instead of `curl`. ### REST API Endpoints | Offering | REST Endpoint | | --- | --- | | Web Search | `POST https://api.microsoft.ai/v3/search/web` | | Videos Search | `POST https://api.microsoft.ai/v3/search/videos` | | Browse | `POST https://api.microsoft.ai/v3/browse` | | News Search | `POST https://api.microsoft.ai/v3/search/news` | | Images Search | `POST https://api.microsoft.ai/v3/search/images` | | Auto (Beta) | `POST https://api.microsoft.ai/v3/auto` | All REST endpoints require: | Header | Value | Description | | --- | --- | --- | | `x-apikey` or `Authorization` | `` or `Bearer ` | Your API key or Entra ID access token for authentication | | `Content-Type` | `application/json` | Request body format | ### Example Response (Simplified) ```json { "webResults": [ { "title": "The 2026 AI Index Report | Stanford HAI", "url": "https://hai.stanford.edu/ai-index/2026-ai-index-report%C2%A0", "content": "The 2026 AI Index Report | Stanford HAI

...", "crawledAt": "2026-06-02T09:55:00.0000000Z", "language": "en", "isAdult": false } ], "traceId": "abc123-trace-id" } ``` ### Available Services Summary - **Web Search** (`search/web`) — Public web content compliantly retrieved for grounding. - **Videos Search** (`search/videos`) — Relevant video content for a query. - **Browse** (`/browse`) — Extracted content from a specific URL. - **News Search** (`search/news`) — Trusted news results. Returns articles from the **last 14 days only** — use Web Search for older content. - **Images Search** (`search/images`) — Relevant image content. ### Support & Feedback Send technical issues or feedback to [Web IQ Support](https://aka.ms/microsoft-webiq-support). --- ## REST API Reference ### Web Search *Source: `app/documentation/_raw/api-reference/web.md`* **Endpoint:** `POST https://api.microsoft.ai/v3/search/web` **Sample Request:** ```bash curl -X POST "https://api.microsoft.ai/v3/search/web" \ -H "host: api.microsoft.ai" \ -H "x-apikey: " \ -H "content-type: application/json" \ -d '{ "query": "latest trends in LLM RAG", "maxResults": 10, "language": "en", "region": "US", "maxLength": 10000, "contentFormat": "html" }' ``` #### Parameters | Parameter | Required | Type | Default | Description | | --- | --- | --- | --- | --- | | query | Yes | string | - | Search query. Max 1000 chars. Supports `site:` and `-site:` operators (use sparingly — reduces relevance). | | maxResults | No | integer | 10 | Max results. Max value 50. | | language | No | string | "en" | 2-letter ISO 639-1 language code. | | region | No | string | "US" | 2-letter country/region code. | | location | No | string | - | `lat:;long:`, e.g. `lat:40.753250;long:-74.003807`. If unset, inferred from query. | | contentFormat | No | string | "html" | `"passage"` (query-contextual extracted paragraphs in plain text up to `maxLength`), `"text"` (full doc plain text), `"html"` (full doc HTML), `"markdown"` (full doc markdown). Web API has no `snippet` field — use `contentFormat=passage` for query-dependent extracts. | | maxLength | No | integer | 10000 | Max chars in `content`/`passage`. Max 500000. | | safeSearch | No | string | "strict" | `"off"` or `"strict"`. | #### Request Headers | Field | Type | Description | | --- | --- | --- | | host | string | `api.microsoft.ai` | | x-apikey *or* Authorization | string | API key or Entra ID access token. | | content-type | string | `application/json` | #### Response `WebResponse`: | Field | Type | Description | | --- | --- | --- | | webResults | array of webResult | List of page results. | | querySignals | querySignals | Query-level ranking signals for the search query. | | riskLevel | string | The safety risk level assessed for the query. Possible values: `low`, `moderate`, `high`, `veryHigh`. | | instrumentationClickBase | string | Base URL for click ping requests. Append an `instrumentationSuffix` value from a result item to form the full ping URL. Only present for applications with the EnableInstrumentationPing profile flag. Note: User clicks can also be logged using URL redirection. When redirection is enabled, no action is required to log User clicks, and `instrumentationClickBase` will not be included in the response. | | instrumentationCitationBase | string | Base URL for LLM log ping requests. Append a DATA payload to form the full ping URL. Only present for applications with the EnableInstrumentationPing profile flag. | | traceId | string | Trace ID for debugging. | `querySignals`: | Field | Type | Description | | --- | --- | --- | | freshness | boolean | Indicates whether fresh documents should be prioritized over other documents for this query. | `webResult`: | Field | Type | Description | | --- | --- | --- | | title | string | Page title. | | url | string | The source URL of the webpage. For China users with URL redirection enabled, this field instead contains the same redirect URL as `clickUrl`. | | domain | string | The destination host for the result. Returned only for China users with URL redirection enabled. | | content | string | Grounding content of the page. | | crawledAt | string | Last crawled date (ISO 8601). | | lastUpdatedAt | string | Last updated date (ISO 8601). | | language | string | ISO 639-1 code. | | isAdult | boolean | Adult content flag. | | clickUrl | string | Redirect URL that proxies the click through Bing. Only present when click redirect is enabled. | | instrumentationSuffix | string | Suffix to append to the instrumentation ping URL base for this result item. Used as the K value for both the instrumentation ping URL and the `clickUrl` redirect. Present when instrumentation ping is enabled. | | contentTier | string | The content tier of the result, describing the commercial access characteristics of the content source. Possible values: `standard`, `entitled`, `premium`. | `crawledAt` and `lastUpdatedAt` coverage is not 100%; values may be empty. #### Error Codes | Status | Category | Description / Common Causes | | --- | --- | --- | | 200 | Success | Request succeeded. | | 400 | Bad Request | Invalid params — missing fields, bad values, malformed JSON. | | 401 | Unauthorized | Invalid API key or missing `x-apikey` header. | | 403 | Forbidden | API key lacks required permissions. | | 410 | Gone | HTTPS required (request was HTTP). | | 415 | Unsupported Media Type | Missing/incorrect `content-type`. | | 429 | Too Many Requests | Rate limit exceeded. | | 500 | Internal Server Error | Temporary server issue. | | 503 | Service Unavailable | Maintenance/outage. | | 504 | Gateway Timeout | Upstream timeout. | --- ### Videos Search *Source: `app/documentation/_raw/api-reference/videos.md`* **Endpoint:** `POST https://api.microsoft.ai/v3/search/videos` **Sample Request:** ```bash curl -X POST "https://api.microsoft.ai/v3/search/videos" \ -H "host: api.microsoft.ai" \ -H "x-apikey: " \ -H "content-type: application/json" \ -d '{ "query": "cute puppy videos", "maxResults": 30, "language": "en", "region": "US" }' ``` #### Parameters | Parameter | Required | Type | Default | Description | | --- | --- | --- | --- | --- | | query | Yes | string | - | Max 1000 chars. | | maxResults | No | integer | 30 | Max value 30. | | language | No | string | "en" | ISO 639-1. | | region | No | string | "US" | 2-letter country/region code. | | enablePlaylist | No | boolean | false | Include playlist results. | | freshness | No | string | - | `week`, `month`, `year`; or ISO 8601 interval `YYYY-MM-DD/YYYY-MM-DD` / `YYYY-MM-DDTHH:mm:ssZ/YYYY-MM-DDTHH:mm:ssZ` (use `..` to omit one end). | | embeddable | No | array of string | - | Allowed: `"player"` (has embeddable player). | | resolution | No | string | - | **Minimum** resolution: `"360p"`, `"480p"`, `"720p"`, `"1080p"`. | | safeSearch | No | string | "strict" | `"off"` or `"strict"`. | | duration | No | string | - | `"short"` (<5 min), `"medium"` (5–20 min), `"long"` (>20 min). | #### Response `VideosResponse`: | Field | Type | Description | | --- | --- | --- | | videoResults | array of videoResult | Video results. | | playlists | array of playlistResult (optional) | Optional even when `enablePlaylist=true`. | | instrumentationClickBase | string | Base URL for click ping requests. Append an `instrumentationSuffix` value from a result item to form the full ping URL. Only present for applications with the EnableInstrumentationPing profile flag. Note: User clicks can also be logged using URL redirection. When redirection is enabled, no action is required to log User clicks, and `instrumentationClickBase` will not be included in the response. | | instrumentationCitationBase | string | Base URL for LLM log ping requests. Append a DATA payload to form the full ping URL. Only present for applications with the EnableInstrumentationPing profile flag. | | traceId | string | Trace ID. | `videoResult`: | Field | Type | Description | | --- | --- | --- | | title | string | Video title. | | url | string | The source URL of the video. For China users with URL redirection enabled, this field instead contains the same redirect URL as `clickUrl`. | | domain | string | The destination host for the result. Returned only for China users with URL redirection enabled. | | description | string | Provided by uploader or generated by LLM. | | publishedBy | string | Uploader/publisher. | | viewCount | long | View count. | | summary | string | AI-generated summary. | | length | string | `HH:MM:SS`. | | allowHttpsEmbedding | boolean | HTTPS embedding allowed. | | allowMobileEmbedding | boolean | Mobile embedding allowed. | | embeddingUrl | string | Embed URL. | | lastUpdatedAt | string | Formatted date. | | bestMomentIndex | integer | Index of best moment in `moments`. | | moments | array of moment | Segments/moments. | | thumbnailUrl | string | Thumbnail. | | width | integer | Pixels. | | height | integer | Pixels. | | isAdult | boolean | Adult flag. | | clickUrl | string | Redirect URL that proxies the click through Bing. Only present when click redirect is enabled. | | instrumentationSuffix | string | Suffix to append to the instrumentation ping URL base for this result item. Used as the K value for both the instrumentation ping URL and the `clickUrl` redirect. Present when instrumentation ping is enabled. | `moment`: | Field | Type | Description | | --- | --- | --- | | title | string | Moment title. | | description | string | What happens. | | startTime | string | `d.hh:mm:ss`. | | endTime | string | `d.hh:mm:ss`. | | momentUrl | string | Deep link to moment. | `playlistResult`: | Field | Type | Description | | --- | --- | --- | | title | string | Playlist title. | | description | string | Playlist description. | | videos | array of video | Videos in playlist (subset of fields: title/description/url). | #### Error Codes Same as Web Search (200/400/401/403/410/415/429/500/503/504). --- ### Browse *Source: `app/documentation/_raw/api-reference/browse.md`* **Endpoint:** `POST https://api.microsoft.ai/v3/browse` **Sample Request:** ```bash curl -X POST "https://api.microsoft.ai/v3/browse" \ -H "host: api.microsoft.ai" \ -H "x-apikey: " \ -H "content-type: application/json" \ -d '{ "url": "https://news.microsoft.com/source/", "maxLength": 3000, "language": "en", "region": "US", "contentFormat": "html" }' ``` #### Parameters | Parameter | Required | Type | Default | Description | | --- | --- | --- | --- | --- | | url | Yes | string | - | URL to browse. | | maxLength | No | integer | 10000 | Max chars in `content`. Max 500000. | | liveCrawl | No | string | "none" | `"none"` (indexed only — returns 404 if not indexed) or `"fallback"` (crawl if not indexed). | | includeWebLinks | No | boolean | false | Include outbound hyperlinks. | | renderDynamicPages | No | boolean | false | Enable JS rendering. Only effective with `liveCrawl="fallback"`. | | includeImageLinks | No | boolean | false | Include image URLs. | | language | No | string | "en" | ISO 639-1. | | region | No | string | "US" | 2-letter country/region code. | | contentFormat | No | string | "html" | `"text"`, `"html"`, or `"markdown"`. | #### Response `BrowseResponse`: | Field | Type | Description | | --- | --- | --- | | url | string | The browsed URL. | | title | string | Page title. | | content | string | Extracted grounding content. | | lastUpdatedAt | string | ISO 8601. | | crawledAt | string | ISO 8601. | | traceId | string | Trace ID. | | retryAfter | string | Present when on-demand crawl is in progress (e.g. `"60s"`). | | isAdult | boolean | Adult flag. | `title`, `content`, `isAdult`, `lastUpdatedAt`, `crawledAt` are only present on 200 responses; omitted from 202 retry responses. #### Error Codes | Status | Category | Description | | --- | --- | --- | | 200 | Success | Request succeeded. | | 202 | Accepted | On-demand crawl in progress. Wait per `retryAfter`, then retry. | | 400 | Bad Request | Invalid params. | | 401 | Unauthorized | Auth failed/missing. | | 403 | Forbidden | Permissions, URL blocked by policy, or content filtered. | | 404 | Not Found | Invalid or inaccessible URL. | | 410 | Gone | HTTPS required. | | 415 | Unsupported Media Type | Bad content-type. | | 429 | Too Many Requests | Rate limited. | | 430 | Too Many On-Demand Crawls | Excessive live-crawl requests. | | 500 | Internal Server Error | Temporary issue. | | 503 | Service Unavailable | Outage. | | 504 | Gateway Timeout | Upstream timeout. | --- ### News Search *Source: `app/documentation/_raw/api-reference/news.md`* **Endpoint:** `POST https://api.microsoft.ai/v3/search/news` **Note:** Returns articles from the **last 14 days only**. For older content, use Web Search. **Sample Request:** ```bash curl -X POST "https://api.microsoft.ai/v3/search/news" \ -H "host: api.microsoft.ai" \ -H "x-apikey: " \ -H "content-type: application/json" \ -d '{ "query": "latest VC funding in tech", "maxResults": 10, "language": "en", "region": "US", "maxLength": 3000 }' ``` #### Parameters | Parameter | Required | Type | Default | Description | | --- | --- | --- | --- | --- | | query | Yes | string | - | Max 1000 chars. | | maxResults | No | integer | 10 | Max 20. | | language | No | string | "en" | ISO 639-1. | | region | No | string | "US" | 2-letter. | | contentFormat | No | string | "text" | `"passage"`, `"text"`, `"html"`, `"markdown"`. | | maxLength | No | integer | 10000 | Max chars. Max 500000. | #### Response `NewsResponse`: | Field | Type | Description | | --- | --- | --- | | newsResults | array of newsResult | News results. | | instrumentationClickBase | string | Base URL for click ping requests. Append an `instrumentationSuffix` value from a result item to form the full ping URL. Only present for applications with the EnableInstrumentationPing profile flag. Note: User clicks can also be logged using URL redirection. When redirection is enabled, no action is required to log User clicks, and `instrumentationClickBase` will not be included in the response. | | instrumentationCitationBase | string | Base URL for LLM log ping requests. Append a DATA payload to form the full ping URL. Only present for applications with the EnableInstrumentationPing profile flag. | | traceId | string | Trace ID. | `newsResult`: | Field | Type | Description | | --- | --- | --- | | title | string | Article title. | | url | string | The source URL of the news article. For China users with URL redirection enabled, this field instead contains the same redirect URL as `clickUrl`. | | domain | string | The destination host for the result. Returned only for China users with URL redirection enabled. | | content | string | Article grounding content. | | snippet | string | Terse search-like snippet. | | thumbnail | thumbnail object | `{url, width, height}` (optional). | | lastUpdatedAt | string | UTC ISO 8601 (optional). | | crawledAt | string | Last crawled date (ISO 8601). | | language | string | ISO 639-1 language code. | | source | string | Publisher (e.g. "CNN", "USA TODAY \| MSN"). | | isAdult | boolean | Adult flag. | | clickUrl | string | Redirect URL that proxies the click through Bing. Only present when click redirect is enabled. | | instrumentationSuffix | string | Suffix to append to the instrumentation ping URL base for this result item. Used as the K value for both the instrumentation ping URL and the `clickUrl` redirect. Present when instrumentation ping is enabled. | #### Error Codes Same shape as Web Search (200/400/401/403/410/415/429/500/503/504). --- ### Images Search *Source: `app/documentation/_raw/api-reference/images.md`* **Endpoint:** `POST https://api.microsoft.ai/v3/search/images` **Sample Request:** ```bash curl -X POST https://api.microsoft.ai/v3/search/images \ -H "host: api.microsoft.ai" \ -H "x-apikey: " \ -H 'content-type: application/json' \ -d '{ "query": "cats", "maxResults": 2, "language": "en", "region": "US" }' ``` #### Parameters | Parameter | Required | Type | Default | Description | | --- | --- | --- | --- | --- | | `query` | Yes | string | - | Max 1000 chars. | | `maxResults` | No | integer | 30 | Max 30. | | `language` | No | string | "en" | ISO 639-1. | | `region` | No | string | "US" | 2-letter. | | `aspectRatio` | No | enum | - | `"square"`, `"wide"`, `"tall"`. | | `color` | No | enum | - | `"colorOnly"` or `"monochrome"`. | | `safeSearch` | No | enum | "strict" | `"off"` or `"strict"`. | | `imageSize` | No | enum | - | `"small"` (<200²), `"medium"` (200–500), `"large"` (≥500), `"extraLarge"` (>1024×768). Pixel constraints (`maxHeight`/`minHeight`/`maxWidth`/`minWidth`) take precedence on conflict. | | `watermarkFree` | No | boolean | false | Exclude watermarked images. | | `maxHeight` | No | integer | - | Pixels. | | `minHeight` | No | integer | - | Pixels. | | `maxWidth` | No | integer | - | Pixels. | | `minWidth` | No | integer | - | Pixels. | #### Response `ImagesResponse`: | Field | Type | Description | | --- | --- | --- | | `imageResults` | array of ImageResult | Image results. | | `instrumentationClickBase` | string | Base URL for click ping requests. Append an `instrumentationSuffix` value from a result item to form the full ping URL. Only present for applications with the EnableInstrumentationPing profile flag. Note: User clicks can also be logged using URL redirection. When redirection is enabled, no action is required to log User clicks, and `instrumentationClickBase` will not be included in the response. | | `instrumentationCitationBase` | string | Base URL for LLM log ping requests. Append a DATA payload to form the full ping URL. Only present for applications with the EnableInstrumentationPing profile flag. | | `traceId` | string | Trace ID. | `ImageResult`: | Field | Type | Description | | --- | --- | --- | | `title` | string | Image title. | | `url` | string | The source URL of the image. For China users with URL redirection enabled, this field instead contains the same redirect URL as `clickUrl`. | | `domain` | string | The destination host for the result. Returned only for China users with URL redirection enabled. | | `hostPageUrl` | string | Page hosting the image. | | `caption` | string | Generated description. | | `width` | integer | Pixels. | | `height` | integer | Pixels. | | `thumbnailUrl` | string | Thumbnail URL. | | `lastUpdatedAt` | string | ISO 8601. | | `isAdult` | boolean | Adult flag. | | `clickUrl` | string | Redirect URL that proxies the click through Bing. Only present when click redirect is enabled. | | `instrumentationSuffix` | string | Suffix to append to the instrumentation ping URL base for this result item. Used as the K value for both the instrumentation ping URL and the `clickUrl` redirect. Present when instrumentation ping is enabled. | #### Error Codes Same as Web Search. --- ## Auto (Beta) `POST https://api.microsoft.ai/v3/auto` Auto returns typed evidence with citations scoped to each result. It is available to profiles enabled for Auto and does not require a preview header. ### Request ```json { "query": "Microsoft AI announcements", "language": "en", "region": "US", "location": "lat:47.6062;long:-122.3321", "mode": "fast", "maxResponseLength": 100000, "responseFilter": ["web", "news"] } ``` | Parameter | Required | Type | Default | Description | | --- | --- | --- | --- | --- | | `query` | Yes | string | - | Search query, from 1 to 1000 characters. Supports `site:` and `-site:` operators. | | `language` | No | string | `en` | Two-letter ISO 639-1 interface language. | | `region` | No | string | `US` | Two-letter market or country/region code. | | `mode` | No | string | `fast` | `fast` prioritizes speed; `advanced` prioritizes comprehensiveness. | | `maxResponseLength` | No | integer | 100000 | Maximum total response length, from 1500 to 500000. | | `location` | No | string | - | Geographic context in `lat:;long:` format. | | `responseFilter` | No | array of strings | - | Eligible answer types: `web`, `news`, `timezone`, `weather`, `images`, or `videos`. | Fields that require internal or preproduction visibility are omitted from this public Beta reference. ### Response A successful evidence response returns `200 OK`. Each `results` entry contains an `evidence` object and result-scoped `citations`. Unsupported or malformed evidence is omitted together with its citations. The evidence object's `type` selects its `content` schema: | `type` | `content` | | --- | --- | | `text` | String evidence returned for Web and News results. | | `media/image` | Image result object. | | `media/video` | Video result object. | | `structured/weather` | Weather object. | | `structured/timeZone` | Time-zone object. | | `structured/sports` | Sports card object. | | `structured/places` | Place result object. | Common status codes are `200`, `400`, `401`, `403`, `429`, `500`, `503`, and `504`. See Error Handling for the shared error schema and retry guidance. --- ## MCP Server *Source: `app/documentation/_raw/mcp.md`* The v3 MCP server lets AI agents integrate with Microsoft Web IQ's rich search capabilities. Provides real-time access to web, news, videos, browse, and images. **Endpoint:** `https://api.microsoft.ai/v3/mcp` (Streamable HTTP transport) **Authentication:** API key (`x-apikey: YOUR_API_KEY`) or Entra ID access token (`Authorization: Bearer `). See Authentication above. ### Available MCP Tools | Tool | Description | | --- | --- | | `web` | Search web pages, retrieve content. | | `videos` | Search videos. | | `browse` | Fetch/extract content from a URL. | | `news` | Search news. | | `images` | Search images. | Each MCP tool accepts the same parameters as its REST counterpart. ### Sample MCP Server Configuration For VS Code Copilot or other MCP-compatible clients (`mcp.json`): ```json { "Search-MCP": { "url": "https://api.microsoft.ai/v3/mcp", "type": "http", "headers": { "x-apikey": "" } } } ``` ### MCP Request Format (JSON-RPC) ```json { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "web", "arguments": { "query": "microsoft", "maxResults": 2, "language": "en", "region": "US" } }, "id": 1 } ``` MCP responses wrap the same data in a `structuredContent` field inside the standard JSON-RPC envelope. --- ## Error Handling *Source: `app/documentation/_raw/error-handling.md`* All v3 APIs return standardized error responses. ### HTTP Status Codes | Status | Applies To | Category | Description | Common Causes | | --- | --- | --- | --- | --- | | 200 | All | Success | Request succeeded. | - | | 202 | Browse only | Accepted | Live crawl in progress. | On-demand crawling | | 400 | All | Bad Request | Invalid request parameters. | Missing/invalid fields, malformed JSON | | 401 | All | Unauthorized | Auth failed/missing. | Invalid API key, missing `x-apikey` | | 403 | All | Forbidden | Valid creds but insufficient permissions. | Key lacks permissions | | 403 | Browse only | Forbidden | Content filtered or URL excluded. | URL blocked by policy | | 404 | Browse only | Not Found | Document not found. | Invalid/inaccessible URL | | 410 | All | Gone | HTTPS required. | HTTP request | | 415 | All | Unsupported Media Type | Content type not supported. | Missing/incorrect `content-type` | | 429 | All | Too Many Requests | Rate limit exceeded. | Too many requests in window | | 430 | Browse only | Server Error | Too many on-demand crawls. | Excessive live crawl requests | | 500 | All | Internal Server Error | Unexpected server error. | Temporary issue | | 503 | All | Service Unavailable | Temporary outage. | Maintenance | | 504 | All | Gateway Timeout | Request timed out. | Upstream timeout | ### Error Response Structure | Field | Type | Description | | --- | --- | --- | | errorCode | string | Machine-readable PascalCase error code (e.g. `HandlerInvalidInput`, `AuthUserThrottled`). | | errorCategory | string | High-level category: `UserError` or `SystemError`. | | userMessage | string | Human-readable description. | | technicalDetails | string | Debug info or validation details. | | retryAfter | string (optional) | Seconds with `"s"` suffix (e.g. `"60s"`). Returned for 429 and retryable 5xx. | | requestId | string | Request identifier. | | traceId | string | Trace ID for support. | > Note: 202 Accepted (Browse live crawl polling) is not an error response and does not use the error schema. **Example:** ```json { "errorCode": "HandlerInvalidInput", "errorCategory": "UserError", "userMessage": "Invalid input provided. Please check your request parameters.", "technicalDetails": "Parameter validation failed: maxResults=100 exceeds maximum=50", "requestId": "req_abc123", "traceId": "trace_xyz789" } ``` ### Common Scenarios **Auth errors (401/403):** verify API key, check `x-apikey` header, confirm key hasn't expired, confirm permissions. **Rate limit (429):** implement exponential backoff, respect `retryAfter` (`AuthUserThrottled` for QPS/QPM or `AuthUserDailyUsageExceeded` for daily cap which resets at 00:00 UTC): ```json { "errorCode": "AuthUserThrottled", "errorCategory": "UserError", "userMessage": "Rate limit exceeded. Please reduce your request frequency.", "retryAfter": "60s", "requestId": "req_123", "traceId": "trace_456" } ``` **Invalid parameters (400):** missing required fields, out-of-range values (e.g. `maxResults > 50`), wrong types, unsupported enum values. **Browse 202:** With `liveCrawl="fallback"` and the URL not in index, the API returns 202 with `retryAfter`. Wait, then retry the same request. ### Best Practices 1. Always check status codes — don't assume success. 2. Include `traceId` when contacting support. 3. Exponential backoff for transient errors (429, 500, 503). 4. Handle 202 for Browse with live crawl. 5. Validate parameters locally to avoid 400. 6. HTTPS only — HTTP returns 410. --- ## Supported Languages and Regions *Source: `app/documentation/_raw/supported-languages-and-regions.md`* ### Supported Languages | Language | Code | | --- | --- | | Arabic | ar | | Basque | eu | | Bengali | bn | | Bulgarian | bg | | Catalan | ca | | Chinese (Simplified) | zh | | Chinese (Traditional) | zh | | Croatian | hr | | Czech | cs | | Danish | da | | Dutch | nl | | English | en | | English-United Kingdom | en | | Estonian | et | | Finnish | fi | | French | fr | | Galician | gl | | German | de | | Gujarati | gu | | Hebrew | he | | Hindi | hi | | Hungarian | hu | | Icelandic | is | | Italian | it | | Japanese | ja | | Kannada | kn | | Korean | ko | | Latvian | lv | | Lithuanian | lt | | Malay | ms | | Malayalam | ml | | Marathi | mr | | Norwegian (Bokmål) | nb | | Polish | pl | | Portuguese (Brazil) | pt | | Portuguese (Portugal) | pt | | Punjabi | pa | | Romanian | ro | | Russian | ru | | Serbian (Cyrillic) | sr | | Slovak | sk | | Slovenian | sl | | Spanish | es | | Swedish | sv | | Tamil | ta | | Telugu | te | | Thai | th | | Turkish | tr | | Ukrainian | uk | | Vietnamese | vi | ### Supported Regions | Country/Region | Code | | --- | --- | | Argentina | AR | | Australia | AU | | Austria | AT | | Belgium | BE | | Brazil | BR | | Canada | CA | | Chile | CL | | Denmark | DK | | Finland | FI | | France | FR | | Germany | DE | | Hong Kong SAR | HK | | India | IN | | Indonesia | ID | | Italy | IT | | Japan | JP | | Korea | KR | | Malaysia | MY | | Mexico | MX | | Netherlands | NL | | New Zealand | NZ | | Norway | NO | | People's Republic of China | CN | | Poland | PL | | Portugal | PT | | Republic of the Philippines | PH | | Russia | RU | | Saudi Arabia | SA | | South Africa | ZA | | Spain | ES | | Sweden | SE | | Switzerland | CH | | Taiwan | TW | | Türkiye | TR | | United Kingdom | GB | | United States | US | --- ## Instrumentation *Source: `app/documentation/_raw/instrumentation.md`* Log which search results an LLM references and which citations users click. ### Enabling Contact your Microsoft contact to enable instrumentation in your profile. ### Response Fields | Field | Description | | --- | --- | | `instrumentationClickBase` | Base URL for click pings. Append `instrumentationSuffix` to log user clicks. | | `instrumentationCitationBase` | Base URL for LLM usage pings. Append URL-encoded JSON payload. | | `instrumentationSuffix` | Per-result identifier (e.g., `DevEx,1000`). | | `clickUrl` | Redirect URL for automatic click logging (when enabled, `instrumentationClickBase` is omitted). | ### Example Implementation **Response (simplified):** ```json { "webResults": [ { "title": "Example", "url": "https://example.com", "instrumentationSuffix": "DevEx,1000" } ], "instrumentationClickBase": "https://api.microsoft.ai/api/ping?IG=some-impression-id&CID=some-client-id&ID=", "instrumentationCitationBase": "https://api.microsoft.ai/api/ping/llmLog?IG=some-impression-id&CID=some-client-id&Type=Event.ClientInst&DATA=" } ``` ### Telemetry Workflow **Step 1: Provide Citations** — Include citations in the LLM response to the user. **Step 2: Log LLM Usage** — Build an array of objects with `T` ("CI.Info"), `FID` ("LLM"), `Name` ("citation"), `AppNS` (prefix of `instrumentationSuffix`), and `K` (suffix value): ```json [ { "T": "CI.Info", "FID": "LLM", "Name": "citation", "AppNS": "DevEx", "K": "1000" } ] ``` URL-encode the array and send: ```http GET https://api.microsoft.ai/api/ping/llmLog?IG=some-impression-id&CID=some-client-id&Type=Event.ClientInst&DATA= ``` **Step 3: Log User Clicks** — When a user clicks a citation, send: ```http GET https://api.microsoft.ai/api/ping?IG=some-impression-id&CID=some-client-id&ID=DevEx,1000 ``` --- ## Portal (Account & Key Management) *Source: product walkthrough of `https://webiq.microsoft.ai/`* ### Pages - **Playground** (`/playground/`) — Build sample requests interactively. Select API Key + Vertical, set parameters, click Run Request. Generated code is available in cURL, Python, JavaScript, C#, Java, Go, and Ruby tabs with a Copy button. - **Profile Management** (`/profiles/`) — View profile (name, quota limit such as `60 QPM`, account status, expiration), allowed services (Web, Videos, Browse, News, Images depending on your profile), and manage credentials under the Authentication tab (API Keys and Application (Client) IDs sub-tabs). Use **Create API Key** to provision a new key. - **Documentation** — Quick Start, API Reference (Web, Videos, Browse, News, Images), MCP Server, Languages & Regions, Error Handling. ### Access - API keys are displayed in a masked format in the UI (e.g., `eh8p****`), while the complete key remains available to copy for future use. ### Support Support: [Web IQ Support](https://aka.ms/microsoft-webiq-support). --- *End of llms-full.txt. For a navigation-style index, see `/llms.txt`.*