Parcourir les informations de référence sur l’API REST

Point de terminaison :POST https://api.microsoft.ai/v3/browse

Exemple de demande :

curl -X POST "https://api.microsoft.ai/v3/browse" \
  -H "host: api.microsoft.ai" \
  -H "x-apikey: <Your key>" \
  -H "content-type: application/json" \
  -d '{
    "url": "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
    "query": "How fast is Web IQ",
    "contentFormat": "passage",
    "maxLength": 3000,
    "liveCrawl": "fallback",
    "language": "en",
    "region": "US"
  }'

Les passages sont le format recommandé pour la mise au sol. Les applications disposant d’un accès complet aux documents peuvent plutôt demander l’intégralité de la page en définissant contentFormattextsur , htmlou .markdown Consultez passages et formats de contenu.

Parameters

Pour les demandes de passage, définissez contentFormat sur « passage » et envoyez un non-vide query. Si vous quittez contentFormat, « passage » est la valeur par défaut, sauf si votre application dispose d’un accès complet au document, où la valeur par défaut est « html ». Requête de passage sans query retour HTTP 400 (HandlerInvalidInput).

Demandes de passage

Une demande de passage est soumise à la validation normale de la demande, ainsi que les éléments suivants :

• query doit contenir du texte autre que l’espace blanc et comporter au maximum 1 000 caractères. Sinon, la requête retourne HTTP 400 (HandlerInvalidInput).
• liveCrawl doit être « aucun » ou « secours ».

Sur MCP, ces échecs retournent HTTP 200 avec une erreur d’outil (result.isError: true) qui porte l’ID de requête d’origine. Le passage est retourné dans le champ existant content ; la réponse a la même forme que pour les autres formats de contenu.

Contenu de passage

Un passage est un extrait axé sur la requête de la page demandée. Au lieu de renvoyer la page à partir du début, le service sélectionne les parties de la page les plus pertinentes query et les retourne dans le content champ.

• Sélection : la page est divisée en segments classés par pertinence.query Les segments les plus classés sont sélectionnés jusqu’à ce que le maxLength budget soit atteint.
• Classement : les segments sélectionnés sont retournés dans leur ordre de page d’origine, et non dans l’ordre de classement. Les segments non adjacents sont séparés par ....
• Limites de segment : les segments sont définis par longueur plutôt que par phrase ou paragraphe, afin qu’un extrait puisse commencer ou terminer la phrase intermédiaire. Affichez les passages sous forme d’extraits et utilisez la source url pour l’attribution.
• Format : le contenu de passage est du texte brut. Les références de balisage, de liens hypertexte et d’image ne sont pas incluses dans content.
• Longueur :content ne dépasse jamais les maxLength caractères. La valeur par défaut maxLength est 3000 sans accès complet aux documents et 1 0000 avec accès complet aux documents. Les pages courtes peuvent être retournées en intégralité.
• Secours : si la sélection de pertinence n’est pas disponible temporairement pour une demande, le service retourne le début de la page sous forme de texte brut, tronqué à maxLength.
• Restrictions de contenu : les stratégies d’éditeur et de site, telles que les directives de robots et les règles de paywall, sont appliquées avant la sélection. Les passages ne sont sélectionnés que dans le contenu qui peut être retourné pour la page.
• Autre comportement : La résolution d’URL, l’analyse dynamique avec « secours », les réponses d’analyse en attente (HTTP 202), les champs de réponse tels que title, crawledAtet isAdultles réponses d’erreur sont identiques aux autres formats de contenu.

En-têtes de requête

Response

Exemple : demande de passage et réponse

La requête dans l’exemple ci-dessus retourne une réponse semblable à ce qui suit. Le service a sélectionné des segments non adjacents de la page et les a joints à ....

{
  "url": "https://techcommunity.microsoft.com/blog/azuredevcommunityblog/why-ai-agents-need-external-grounding/4565283",
  "title": "Why AI agents need external grounding | Microsoft Web IQ",
  "content": "Why AI agents need external grounding | Microsoft Web IQ Microsoft Community Hub Azure Microsoft Developer Community Blog nodeTitle minReadText Why AI Agents Need External Grounding bkingms Microsoft Oct 18, 2026 Earlier this year, we introduced Microsoft Web IQ, a suite of AI-native web search and grounding APIs that gives LLMs, AI agents, and applications access to current, relevant web information. This post explores why web grounding is becoming a foundational layer of AI, how it helps deliver answers customers can use and verify, and how we’re addressing the quality, speed, and efficiency developers need. -- When customers ask an AI agent or application for help, the answer may do more than inform them—it may shape a recommendation, trigger a workflow, or guide an action. If that answer relies on... ... an engineering approach that treats quality, speed, and token efficiency as a connected problem. You can read more on our engineering approach here. Highest grounding satisfaction. On a 3,000 query blind test sampled from production traffic, Web IQ scored 79.05 against 75.70 for the next best service and more than 14 points ahead of the lowest. It gets there by returning more complete, structured context drawn from web, news, images, and video. What your users see is answers that hold up: more accurate, more consistent, and properly attributed. In the domains where source quality, freshness, and attribution drive the decision, that is the difference between an agent people act on and one they quietly double check. 2.5x faster than today's best alternative. P95 latency measured 164 milliseconds across five datacenter regions, against 406 for the closest competitor and 2,090 for the slowest. Latency compounds in agent workloads, because a multi-step chain pays the retrieval cost at every hop. Cutting it at each step keeps workflows moving and keeps interactive agents feeling interactive instead of batch. Highest quality answers with the fewest tokens. Web IQ sits on a new Pareto curve of efficiency, reaching peak quality at around 40,000 tokens per query while competing services spend 60,000 to 100,000 to score lower. Prioritizing the most relevant passages and cutting unnecessary context reduces both token spend and reasoning time, and those savings compound across high volume production workloads. Most web search APIs force a tradeoff — fast or accurate, cost-efficient or complete. Web IQ is delivers across the board: industry-leading quality, fastest performance, and fewest tokens per query — all in an enterprise-ready solution. For teams evaluating Web IQ, those results provide a starting point. We recommend testing your own questions, sources, models, and end-to-end workflows to understand how retrieval quality and efficiency translate into customer outcomes. Grounding satisfaction is a benchmark score, not an accuracy percentage, and retrieval latency is only one part of the time required to complete a task. Within Microsoft IQ,...",
  "isAdult": false,
  "lastUpdatedAt": "2026-10-18T00:00:00",
  "crawledAt": "2026-10-29T07:44:00Z",
  "traceId": "6ae4fd995e3d425f847c07c2f0839e38"
}

Codes d’erreur

Erreurs de requête de passage

Ces erreurs s’appliquent aux demandes de passage. Ils s’appliquent également lorsque « passage » est le format par défaut.

Codes d’erreur granulaires

Les codes d’erreur granulaires sont activés par défaut pour Parcourir. Ils identifient la raison spécifique pour laquelle une page n’a pas pu être retournée, comme le filtrage de contenu, un document manquant ou un échec d’analyse, et incluent des conseils de nouvelle tentative le cas échéant. Aucune demande d’inscription ou de support n’est requise.

Pour obtenir la liste complète des codes et des actions recommandées, consultez Parcourir les erreurs spécifiques à l’API.

Pour obtenir des instructions détaillées sur la gestion des erreurs, consultez Gestion des erreurs.

Voir aussi :Recherche devidéos recherche | d’actualités Recherche | d’imagesde recherche | d’actualités MCP |