> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/es/api-web.md). # API web Aprende a usar e integrar la Oxylabs Web API, una API REST todo en uno para búsqueda web y recopilación de datos de páginas. La Web API de Oxylabs proporciona a las aplicaciones y a los agentes de IA acceso en vivo a la web abierta a través de una interfaz REST unificada. Gestiona el renderizado de JavaScript, los desafíos de tráfico de bots, la rotación de proxies y el geotargeting mediante un endpoint separado para diferentes etapas de adquisición de datos web:
EndpointSe usa paraEntrada
/searchDescubrir y clasificar los resultados orgánicos de la web.Palabra clave / consulta
/scrapeRenderizar y extraer datos de la página como Markdown, HTML, JSON o captura de pantalla.URL de la página
{% hint style="success" %} Los endpoints de Web API están diseñados para usarse juntos: **search para encontrar, scrape para leer.** `/search` las descripciones son fragmentos, así que cualquier cosa sobre la que necesites precisión proviene de un `/scrape`. {% endhint %} ## Cómo usarlo ### Obtén una clave de API En el [panel de Oxylabs](https://dashboard.oxylabs.io), crea una **instancia de Web API** , obtén la clave de API de la instancia del producto y expórtala al entorno de tu proyecto (p. ej., la terminal de tu SO o la terminal de la CLI en el espacio de trabajo del proyecto): ```bash export OXYLABS_WEB_API_KEY=your_api_key_here ``` Consulta [Autenticación](/products/es/api-web/autenticacion.md) para la gestión y rotación de claves. ### Elige el método de integración * **¿Lo vas a conectar a un agente de IA (Claude Code, Cursor o tu propio agente)?**\ Consulta las [integraciones con agentes de IA](#ai-agent-integration) para empezar a usarlo con un solo comando. * **¿Estás construyendo tu propia integración?**\ Sigue los pasos de abajo para integrarlo directamente usando endpoints REST. ### Integración manual {% stepper %} {% step %} #### Búsqueda {% tabs %} {% tab title="cURL" %} ```bash curl https://webapi.oxylabs.io/v1/search \\ -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \\ -H 'Content-Type: application/json' \\ -d '{"query": "eu ai act compliance deadlines", "max_results": 3}' ``` {% endtab %} {% tab title="Python" %} ```python import os, requests resp = requests.post( "https://webapi.oxylabs.io/v1/search", headers={"Authorization": f"Bearer {os.environ['OXYLABS_WEB_API_KEY']}"}, json={"query": "eu ai act compliance deadlines", "max_results": 3}, timeout=120, ) resp.raise_for_status() for r in resp.json()["results"]: print(r["metadata"]["position"], r["title"], r["url"], sep=" | ") ``` {% endtab %} {% tab title="Node.js" %} ```javascript const res = await fetch("https://webapi.oxylabs.io/v1/search", { method: "POST", headers: { Authorization: `Bearer ${process.env.OXYLABS_WEB_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ query: "eu ai act compliance deadlines", max_results: 3 }), }); if (!res.ok) throw new Error(`${res.status} ${await res.text()}`); const { results } = await res.json(); results.forEach((r) => console.log(r.metadata.position, r.title, r.url)); ``` {% endtab %} {% endtabs %} **Ejemplo de salida** ```json { "state": "done", "results": [ { "title": "Cronograma de implementación | Ley de Inteligencia Artificial de la UE", "outline": [ "Fecha 2 de agosto de 2025 Proveedores: deben cumplir con la AI Act antes del 2 de agosto de 2027..." ], "url": "https://artificialintelligenceact.eu/implementation-timeline/", "metadata": { "position": 1 } } ], "params": { "query": "eu ai act compliance deadlines", "location": null, "max_results": 3 }, "metadata": { "timestamp": 1787431568, "request_id": "1788875675880097469" } } ``` Consulta [/search](/products/es/api-web/search.md) para los parámetros de solicitud y el diccionario de salida. {% endstep %} {% step %} #### Extracción Lee las páginas recopiladas por `/search` o tu lista de URLs: {% tabs %} {% tab title="cURL" %} ```bash curl https://webapi.oxylabs.io/v1/scrape \\ -H "Authorization: Bearer $OXYLABS_WEB_API_KEY" \\ -H 'Content-Type: application/json' \\ -d '{ "url": "https://artificialintelligenceact.eu/implementation-timeline/", "output": ["markdown"] }' ``` {% endtab %} {% tab title="Python" %} ```python page = requests.post( "https://webapi.oxylabs.io/v1/scrape", headers={"Authorization": f"Bearer {os.environ['OXYLABS_WEB_API_KEY']}"}, json={ "url": "https://artificialintelligenceact.eu/implementation-timeline/", "output": ["markdown"], }, timeout=120, ) page.raise_for_status() print(page.json()["results"][0]["markdown"][:2000]) ``` {% endtab %} {% tab title="Node.js" %} ```javascript const page = await fetch("https://webapi.oxylabs.io/v1/scrape", { method: "POST", headers: { Authorization: `Bearer ${process.env.OXYLABS_WEB_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ url: "https://artificialintelligenceact.eu/implementation-timeline/", output: ["markdown"], }), }); if (!page.ok) throw new Error(`${page.status} ${await page.text()}`); const { results } = await page.json(); console.log(results[0].markdown.slice(0, 2000)); ``` {% endtab %} {% endtabs %} Consulta [/scrape](/products/es/api-web/scrape.md) para los parámetros de solicitud, el diccionario de salida, los modos de entrega. {% endstep %} {% step %} #### Combina: search-to-scrape Los fragmentos de búsqueda (`esquema`) están truncados y no son suficientes para un análisis profundo ni para canalizaciones de LLM. El patrón de integración estándar consulta `/v1/search` para descubrir enlaces autoritativos, y luego envía esas URLs a `/v1/scrape` solicitando salida en Markdown para eliminar artefactos HTML innecesarios. El ejemplo en Python de abajo muestra ambos endpoints en un solo flujo: {% code expandable="true" %} ```python import os, requests API = "https://webapi.oxylabs.io" HEADERS = {"Authorization": f"Bearer {os.environ['OXYLABS_WEB_API_KEY']}"} def research(question: str, read_top: int = 2) -> list[dict]: # 1. Descubre las URLs de destino hits = requests.post( f"{API}/v1/search", headers=HEADERS, json={"query": question, "max_results": 10}, timeout=120, ) hits.raise_for_status() # 2. Extrae el contenido completo de la página como Markdown pages = [] for hit in hits.json()["results"][:read_top]: page = requests.post( f"{API}/v1/scrape", headers=HEADERS, json={"url": hit["url"], "output": ["markdown"]}, timeout=120, ) if not page.ok: print(f"omitido {hit['url']}: {page.status_code}") continue pages.append( { "url": hit["url"], "title": hit["title"], "content": page.json()["results"][0]["markdown"], } ) return pages for page in research("eu ai act compliance deadlines"): print(f"--- {page['title']} ({page['url']})") print(page["content"][:500]) ``` {% endcode %} {% endstep %} {% endstepper %} ### Integración de agente de IA Conecta la Web API directamente con marcos de IA, asistentes de programación (Cursor, Claude Code) o agentes personalizados. #### Opción 1: Prompt de integración Pega el siguiente prompt completo en un agente de programación de IA (Claude Code, Cursor, Copilot) para indicarle que construya una integración personalizada siguiendo nuestra especificación técnica: {% code expandable="true" %} ``` Integra la Web API de Oxylabs en este proyecto para búsqueda web en vivo y lectura de páginas. Lee https://developers.oxylabs.io/products/web-api/for-agents.md y sigue lo. Tiene la URL base, la autenticación, los esquemas de ambos endpoints, el código de referencia, las reglas de error y reintento, y la lista de verificación que debe cumplir. Si la página no carga, detente y dime; no reconstruyas la API de memoria. Decide la ruta y dímela antes de escribir nada: - ¿El propio código de este proyecto llamará a la API en tiempo de ejecución? -> escribe el cliente que la página especifica, siguiendo la forma en que esta base de código ya hace llamadas HTTP salientes. - ¿El acceso web es para ti durante esta sesión en lugar de para el código del proyecto? -> instala el servidor MCP y las skills, tal como lo describe la página. La clave está en OXYLABS_WEB_API_KEY o en un .env aquí. Si no está en ninguno de los dos, pregúntame. Nunca imprimas la clave: ni en el código, ni en los registros, ni en las pruebas, ni en tus respuestas. Demuestra que funciona antes de escribir pruebas: haz una búsqueda real, extrae una URL de los resultados y muéstrame ambos IDs de solicitud. Si una llamada devuelve 401, detente y dime. Cuando una extracción vuelva vacía o escuálida, vuelve a intentarlo una vez con run_js: true. Si sigue vacía y el sitio está en un TLD de país (.lt, .es, .co.uk), vuelve a intentarlo una vez más con run_js y location configurada para ese país, y luego informa que la página es ilegible. Luego añade una prueba para el reintento y el mapeo de errores contra un transporte simulado y ejecútala. Si no puedes ejecutar comandos en este entorno, dilo una vez y dame los comandos exactos para ejecutarlos en su lugar. Repórtame: la ruta que seguiste, cada elemento de la lista de verificación de la página marcado como hecho o no, lo que todavía necesito hacer yo mismo y cualquier cosa que no pudiste terminar. No me preguntes si debo continuar; haz el trabajo. ``` {% endcode %} El prompt señala al agente una sola página con una fuente única de verdad completa del producto: URL base, autorización, esquemas de ambos endpoints, código de referencia, reglas de error y reintento, y una lista de verificación del agente. Puedes encontrar la referencia completa de la especificación del agente en la [página For Agents](/products/es/api-web/for-agents.md) . {% hint style="info" %} **Si el agente no puede obtener URLs**, dale la página completa en su lugar. `for-agents.md` está en Markdown plano y es autocontenido, así que guárdalo o pégalo encima del prompt y elimina el párrafo que nombra la URL. Mantén la especificación fuera del prompt: las dos reglas de reintento se repiten allí porque un agente las aplica durante la tarea; todo lo demás pertenece a la página para que no derive. {% endhint %} #### Opción 2: skills de agente Instala skills oficiales del agente para enseñarle metodologías de investigación, reglas de citación de fuentes y ejecución de search-to-scrape: ```bash npx skills add oxylabs/web-api-skills ``` Para más opciones de instalación, consulta [Oxylabs Agent Skills](https://developers.oxylabs.io/ai-workflows/agent-skills). #### Opción 3: servidor MCP Para una implementación más mínima y controlada, autoalberga nuestro servidor MCP oficial para exponer **search**, **scrape**, y **extraction** herramientas a cualquier cliente compatible con MCP: ```bash uv tool install git+https://github.com/oxylabs/web-api-mcp ``` Para detalles de configuración y definiciones de herramientas, consulta [Servidor MCP](https://developers.oxylabs.io/ai-workflows/mcp). #### ¿Skills o MCP?
Skillsservidor MCP
Le da al agenteCriterio: cuándo buscar, qué fuentes confiar, cómo citarHerramientas tipadas que puede invocar directamente
Necesita un proceso en ejecuciónNoSí
Funciona enAgentes que cargan directorios de skillsCualquier cliente MCP
Instalar ambos es una opción. El servidor agrupa `oxylabs-web-api` y lo sirve como el recurso `oxylabs://skill/web-api` , así que conectarlo por sí solo le da al agente ambas partes. Instala las skills por separado cuando las quieras sin un servidor en ejecución, o cuando quieras migrar tu base de código a Oxylabs. ## Más información
AutenticaciónGestión de claves, requisitos de encabezados y solución de problemas de autenticación.
BúsquedaParámetros completos de solicitud y esquemas de respuesta para /v1/search.
ExtracciónParámetros de solicitud y diccionario de salida para /v1/scrape.
Scrapers dedicadosEndpoints analizados específicos por destino (Google, Amazon, YouTube, Walmart, etc.).
Modos de entregaLlamadas Realtime, sondeo asíncrono para un solo trabajo/webhooks y colas de lotes masivos.
Análisis con IAExtracción de JSON estructurado usando indicaciones en lenguaje natural o esquemas JSON.
Solución de problemasCódigos de estado HTTP, lógica de reintento y consejos de solución de problemas.
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developers.oxylabs.io/products/es/api-web.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.