Examinar la referencia de la API REST

Punto final:POST https://api.microsoft.ai/v3/browse

Solicitud de ejemplo:

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"
  }'

Los pasajes son el formato recomendado para la puesta a tierra. Las aplicaciones con acceso completo a documentos pueden solicitar en su lugar toda la página estableciendo contentFormattexten , htmlo markdown. Consulte Secciones y formatos de contenido.

Parameters

Parámetro Required Tipo Default Description
url Sí string - Dirección URL de la página web que se va a examinar.
query Obligatorio para passage string - Consulta usada para seleccionar pasajes de la página, hasta 1000 caracteres. Una passage solicitud requiere una consulta que no esté en blanco. Para otros formatos, query es opcional. Un valor de más de 1000 caracteres devuelve HTTP 400. Este límite es independiente de maxLength.
longitud máxima No integer 3000 (10000 con acceso completo a documentos) Número máximo de caracteres en content, de 1 a 500000. Un valor fuera de ese intervalo devuelve HTTP 400. Sin acceso completo a documentos, content tiene como máximo 3000 caracteres y los valores mayores están limitados a 3000.
liveCrawl No string "none" Controla el comportamiento del rastreo en vivo. Valores admitidos: "none" (solo devuelve contenido indexado, sin rastreo activo) y "reserva" (solicite un rastreo activo si la dirección URL no se encuentra en el índice). Para "none", si la dirección URL no se encuentra en el índice, la API devuelve 404 (no se encuentra la dirección URL).

Nota: El rastreo en vivo está sujeto a restricciones y disponibilidad del publicador; "reserva" no garantiza un rastreo real.
includeWebLinks No booleano falso Incluya hipervínculos salientes de la página. Se omite para el contenido de pasaje.
renderDynamicPages No booleano falso Habilite la representación de JavaScript para la captura de pantalla de contenido dinámico. Solo funciona cuando liveCrawl está establecido en "reserva".
includeImageLinks No booleano falso Incluya direcciones URL de imagen desde la página. Se omite para el contenido de pasaje.
idioma No string "en" El código de idioma (ISO 639-1 de 2 letras). Consulte Idiomas admitidos para obtener la lista completa.
region No string "US" Código de región (código de país o región de 2 letras). Consulte Regiones admitidas para obtener la lista completa.
contentFormat No string "passage" ("html" con acceso completo al documento) "passage" devuelve las partes de la página más relevantes para query (recomendado para la puesta a tierra). "text", "html" y "markdown" devuelven el documento completo y solo se aplican a las aplicaciones con acceso completo al documento; sin él, devuelven HTTP 403 (AuthContentFormatForbidden). Consulte Secciones y formatos de contenido.

En el caso de las solicitudes de paso, establezca contentFormat en "pasaje" y envíe un noblank query. Si deja fuera contentFormat, "passage" es el valor predeterminado a menos que la aplicación tenga acceso completo al documento, donde el valor predeterminado es "html". Una solicitud de pasaje sin un query devuelve HTTP 400 (HandlerInvalidInput).

Solicitudes de pasaje

Una solicitud de paso está sujeta a la validación normal de la solicitud, además de lo siguiente:

  • query debe contener texto distinto del espacio en blanco y tener como máximo 1000 caracteres. De lo contrario, la solicitud devuelve HTTP 400 (HandlerInvalidInput).
  • liveCrawl debe ser "none" o "fallback".

A través de MCP, estos errores devuelven HTTP 200 con un error de herramienta (result.isError: true) que contiene el identificador de solicitud original. El pasaje se devuelve en el campo existente content ; la respuesta tiene la misma forma que para otros formatos de contenido.

Contenido de pasaje

Un pasaje es un extracto centrado en la consulta de la página solicitada. En lugar de devolver la página desde el principio, el servicio selecciona las partes de la página más relevantes para query y las devuelve en el content campo .

  • Selección: la página se divide en segmentos, que se clasifican por relevancia para query. Los segmentos con clasificación más alta se seleccionan hasta que se alcanza el maxLength presupuesto.
  • Ordenación: los segmentos seleccionados se devuelven en su orden de página original, no en el orden de clasificación. Los segmentos no adyacentes están separados por ....
  • Límites de segmento: los segmentos se definen por longitud en lugar de por frase o párrafo, por lo que un extracto puede comenzar o finalizar la oración media. Mostrar pasajes como extractos y usar la fuente url para la atribución.
  • Formato: el contenido del pasaje es texto sin formato. El marcado, los hipervínculos y las referencias de imagen no se incluyen en content.
  • Longitud:content nunca supera los maxLength caracteres. El valor predeterminado maxLength es 3000 sin acceso completo al documento y 10000 con acceso completo al documento. Se pueden devolver páginas cortas completas.
  • Reserva: si la selección de relevancia no está disponible temporalmente para una solicitud, el servicio devuelve el principio de la página como texto sin formato, truncado en maxLength.
  • Restricciones de contenido: las directivas de editor y sitio, como las directivas robots y las reglas de pago, se aplican antes de la selección. Los pasajes solo se seleccionan en el contenido que se puede devolver para la página.
  • Otro comportamiento: Resolución de direcciones URL, rastreo en vivo con respuestas de "reserva", rastreo pendiente (HTTP 202), campos de respuesta como title, crawledAty isAdultrespuestas de error son los mismos que para otros formatos de contenido.

Encabezados de solicitud

Field Tipo Description
host string Host para las API de IA de Microsoft: api.microsoft.ai.
x-apikey o Authorization string La clave de API o Entra ID token de acceso para la autenticación.
content-type (tipo de contenido) string Tipo MIME del cuerpo de la solicitud. Utilice application/json.

Respuesta

Field Tipo Description
url string La dirección URL de la página web o la dirección URL que se va a reintentar cuando un rastreo está pendiente.
title string El título de la página web.
contenido string Contenido extraído de la página web (también conocido como tierra). Para una solicitud de pasaje, los pasajes seleccionados para query.
lastUpdatedAt string La última fecha actualizada de la página web sigue ISO8601 formato.
crawledAt string La última fecha rastreada de la página web sigue ISO8601 formato.
traceId string Identificador de seguimiento para la depuración.
retryAfter string La primera vez que se reintenta, como marca de tiempo ISO 8601 UTC (por ejemplo, "2026-10-30T01:01:00Z"). Presente cuando un rastreo a petición está en curso (202) y en algunos errores.
isAdult booleano Indica si la página web contiene contenido para adultos.

Note

Los titlecampos , content, isAdult, lastUpdatedAty crawledAt solo están presentes en respuestas correctas (200). Se omiten de las respuestas de reintento (202).

Ejemplo: solicitud de paso y respuesta

La solicitud del ejemplo anterior devuelve una respuesta similar a la siguiente. El servicio seleccionó segmentos no adyacentes de la página y los unió con ....

{
  "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"
}

Códigos de error

Código de estado Categoría de error Description Causas comunes
200 Success La solicitud tuvo éxito. -
202 Aceptado Solicitud aceptada para el procesamiento (rastreo en directo). Rastreo a petición en curso
400 Solicitud incorrecta Parámetros de solicitud no válidos. Faltan campos obligatorios, valores de parámetro no válidos, JSON con formato incorrecto, falta o está en blanco query para una solicitud de paso.
401 Unauthorized Error de autenticación o falta. Clave de API no válida, falta el encabezado x-apikey
403 Prohibida Credenciales válidas, pero no se puede completar la solicitud. La clave de API carece de los permisos necesarios, la dirección URL bloqueada por directiva, el contenido filtrado, text, htmlo markdown solicitado sin acceso completo al documento
404 No encontrado No se encontró el documento. Dirección URL no válida o inaccesible
410 Pasado (Gone) SE requiere HTTPS. Solicitud realizada a través de HTTP en lugar de HTTPS
415 Tipo de medio no admitido No se admite el tipo de contenido. Falta o falta un encabezado de tipo de contenido incorrecto
429 Demasiadas solicitudes Se superó el límite de velocidad o el límite de rastreo a petición. Demasiadas solicitudes en el período de tiempo o solicitudes de rastreo en vivo excesivas
430 Demasiados rastreos a petición Demasiados rastreos a petición (códigos de error heredados). Solicitudes de rastreo en vivo excesivas
500 Error interno del servidor Error inesperado del servidor. Problema de servidor temporal
503 Servicio no disponible El servicio no está disponible temporalmente. Interrupción temporal o mantenimiento
504 Tiempo de espera de puerta de enlace Se ha agotado el tiempo de espera para la solicitud. Tiempo de espera del servicio ascendente
520 Error de procesamiento de contenido Se recuperó la página, pero no se pudo generar contenido utilizable. Error en el procesamiento de documentos o se agota el tiempo de espera de la representación dinámica
523 Rastreo cancelado El rastreo no produjo contenido debido a una cuota limitada de rastreo del sitio. Cuota de rastreo limitada para el host de origen
524 Tiempo de espera de rastreo El rastreo no produjo contenido porque agotó el tiempo de espera. Se agota el tiempo de espera del host remoto.

Errores de solicitud de pasaje

Estos errores se aplican a las solicitudes de paso. También se aplican cuando "passage" es el formato predeterminado.

Condition Estado HTTP Código de error
query falta, está en blanco o tiene más de 1000 caracteres. 400 HandlerInvalidInput
Una aplicación sin solicitudes textde acceso a documentos completas, html, o markdown 403 AuthContentFormatForbidden

Códigos de error pormenorizados

Los códigos de error granulares están habilitados de forma predeterminada para Examinar. Identifican el motivo específico por el que no se pudo devolver una página, como el filtrado de contenido, un documento que falta o un error de rastreo, e incluyen instrucciones de reintento cuando corresponda. No se requiere ninguna solicitud de participación o soporte técnico.

Para obtener la lista completa de códigos y acciones recomendadas, consulte Examinar errores específicos de la API.

Para obtener instrucciones detalladas sobre el control de errores, consulte Control de errores.

Consulte también:Web Search | Videos Search | News Search | Images Search | MCP

  • Se actualizó por última vez el