> 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 Oxylabs Web API, una API REST todo en uno para búsqueda web y recopilación de datos de páginas.

La API web de Oxylabs proporciona a las aplicaciones y a los agentes de IA acceso en tiempo real a la web abierta mediante una interfaz REST unificada. Gestiona la representación de JavaScript, los desafíos contra el tráfico de bots, la rotación de proxies y la segmentación geográfica mediante endpoints separados para las distintas etapas de adquisición de datos web:

<table><thead><tr><th width="106">Endpoint</th><th width="504">Uso</th><th width="148">Entrada</th></tr></thead><tbody><tr><td><a href="https://developers.oxylabs.io/products/es/api-web/search.md">/search</a></td><td>Descubrir y clasificar resultados orgánicos de la web.</td><td>Palabra clave / consulta</td></tr><tr><td><a href="https://developers.oxylabs.io/products/es/api-web/scrape.md">/scrape</a></td><td>Representar páginas y extraer sus datos como Markdown, HTML, JSON o captura de pantalla.</td><td>URL de la página</td></tr></tbody></table>

{% hint style="success" %}
Los endpoints de la API web están diseñados para usarse en conjunto: **usa search para encontrar y scrape para leer.** `/search` Las descripciones son fragmentos, así que todo lo que necesites verificar debe obtenerse de `/scrape`.
{% endhint %}

## Cómo usarla

### 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 (por ejemplo, al terminal del sistema operativo o al terminal de la CLI en el espacio de trabajo del proyecto):

```bash
export OXYLABS_WEB_API_KEY=your_api_key_here
```

Consulta [Autenticación](https://developers.oxylabs.io/products/es/api-web/autenticacion.md) para obtener información sobre la gestión y rotación de claves.

### Elige un método de integración

* **¿Quieres integrar esto en un agente de IA (Claude Code, Cursor o tu propio agente)?**\
  Consulta las [integraciones de agentes de IA](#ai-agent-integration) para empezar a usarlo con un solo comando.
* **¿Estás creando tu propia integración?**\
  Sigue los pasos siguientes para integrar directamente mediante 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": "Implementation Timeline | EU Artificial Intelligence Act",
      "outline": [
        "Date 2 August 2025 Providers: need to be compliant with the AI Act by 2 August 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](https://developers.oxylabs.io/products/es/api-web/search.md) para ver los parámetros de la solicitud y el diccionario de salida.
{% endstep %}

{% step %}

#### Extraer

Lee las páginas recopiladas por `/search` o la lista de URL:

{% 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](https://developers.oxylabs.io/products/es/api-web/scrape.md) para ver los parámetros de la solicitud, el diccionario de salida y los modos de entrega.
{% endstep %}

{% step %}

#### Combinar: búsqueda y extracción

Los fragmentos de búsqueda (`outline`) están truncados y no bastan para un análisis exhaustivo ni para canalizaciones de LLM. El patrón de integración estándar consiste en consultar `/v1/search` para descubrir enlaces fiables y, a continuación, envía esas URL a `/v1/scrape` solicitando la salida en Markdown para eliminar los elementos HTML innecesarios.

El siguiente ejemplo en Python muestra ambos endpoints en un único flujo de trabajo:

{% 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. Discover target URLs
    hits = requests.post(
        f"{API}/v1/search",
        headers=HEADERS,
        json={"query": question, "max_results": 10},
        timeout=120,
    )
    hits.raise_for_status()
    # 2. Extract full page content as 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"skipped {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 agentes de IA

Conecta la Web API directamente con frameworks 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 con IA (Claude Code, Cursor, Copilot) para indicarle que cree una integración personalizada siguiendo nuestra especificación técnica:

{% code expandable="true" %}

```
Integra la Web API de Oxylabs en este proyecto para realizar búsquedas web y leer páginas en tiempo real.

Lee https://developers.oxylabs.io/products/web-api/for-agents.md y sigue
sus instrucciones. Incluye la URL base, la autenticación, los esquemas de ambos endpoints, código de referencia, las reglas de errores y reintentos
y una lista de comprobación para cumplir los requisitos. Si no se puede cargar la página, detente y avísame; no
reconstruyas la API de memoria.

Decide qué opción seguir y dímelo antes de escribir nada:
- ¿El código de este proyecto llamará a la API durante la ejecución? -> escribe el cliente que la página
  especifica, siguiendo el modo en que este código ya realiza llamadas HTTP salientes.
- ¿Necesitas acceso web durante esta sesión, en lugar de para el código del proyecto?
  -> instala el servidor MCP y las skills, tal como se describe en la página.

La clave está en OXYLABS_WEB_API_KEY o en un archivo .env de este directorio. Si no está en ninguno de los dos, pregúntame. Nunca
imprimas la clave: ni en el código, los registros, las pruebas ni tus respuestas.

Comprueba que funciona antes de escribir pruebas: realiza una búsqueda real, extrae una URL de los
resultados y muéstrame ambos ID de solicitud. Si una llamada devuelve 401, detente y avísame.

Si el resultado de una extracción está vacío o contiene muy poco contenido, vuelve a intentarlo una vez con run_js: true. Si sigue
vacío y el sitio tiene un TLD de país (.lt, .es, .co.uk), vuelve a intentarlo una vez más con run_js y
con la ubicación configurada en ese país y, luego, informa de que la página no se puede leer.

Luego, añade una prueba para los reintentos y la asignación de errores usando un transporte simulado y ejecútala.
Si no puedes ejecutar comandos en este entorno, dilo una vez e indica los
comandos exactos que debo ejecutar en su lugar.

Informa de lo siguiente: la ruta que seguiste, si marcaste como completado cada elemento de la lista de verificación de la página,
lo que todavía debo hacer por mi cuenta y todo lo que no pudiste terminar. No me preguntes
si debes continuar; haz el trabajo.
```

{% endcode %}

El prompt dirige al agente a una sola página que contiene la fuente de verdad completa del producto: URL base, autorización, esquemas de ambos endpoints, código de referencia, reglas de errores y reintentos, y una lista de verificación para el agente.

Puedes consultar la especificación completa de referencia para agentes en la [página For Agents](https://developers.oxylabs.io/products/es/api-web/for-agents.md) .

{% hint style="info" %}
**Si el agente no puede acceder a las URL**, proporciónale la página completa. `for-agents.md` está en Markdown sin formato y es autónomo, así que guárdalo o pégalo antes del prompt y elimina el párrafo que menciona la URL. No incluyas la especificación en el prompt: allí se repiten las dos reglas de reintento porque el agente las aplica durante la tarea; todo lo demás debe estar en la página para que no quede desactualizado.
{% endhint %}

#### Opción 2: Habilidades para agentes

Instala las habilidades oficiales para agentes a fin de enseñar a tu agente de IA metodologías de investigación, reglas para citar fuentes y el proceso de búsqueda y extracción:

```bash
npx skills add oxylabs/web-api-skills
```

Para ver más opciones de instalación, consulta [Oxylabs Agent Skills](https://developers.oxylabs.io/ai-workflows/agent-skills).

#### Opción 3: Servidor MCP

Conéctate a nuestro servidor MCP oficial o alójalo por tu cuenta para ofrecer herramientas de búsqueda y extracción de Web API, además de herramientas específicas de scraping, directamente a Claude Code, Cursor o a tu agente de IA personalizado. Para ello, dirige tu agente al servidor alojado por Oxylabs: `https://mcp.oxylabs.io/web-api-mcp`:

<details>

<summary><i class="fa-claude">:claude:</i>  <strong>Claude Code</strong></summary>

```bash
claude mcp add --transport http --scope user oxylabs-web-api \
  https://mcp.oxylabs.io/web-api-mcp \
  --header "Authorization: Bearer ${OXYLABS_WEB_API_KEY}"
```

</details>

<details>

<summary><i class="fa-openai">:openai:</i>  <strong>ChatGPT/Codex</strong></summary>

```bash
codex mcp add oxylabs-web-api \
  --url https://mcp.oxylabs.io/web-api-mcp \
  --bearer-token-env-var OXYLABS_WEB_API_KEY
```

</details>

<details>

<summary><i class="fa-cursor">:cursor:</i>  <strong>Cursor</strong> (u otros clientes compatibles con encabezados personalizados)</summary>

En cualquier cliente compatible con servidores MCP remotos y encabezados personalizados, añade la URL del servidor y un encabezado `Authorization` a la configuración MCP del cliente. Por ejemplo, en Cursor, en `mcp.json`:

```json
{
  "mcpServers": {
    "oxylabs-web-api": {
      "url": "https://mcp.oxylabs.io/web-api-mcp",
      "headers": {
        "Authorization": "Bearer ${env:OXYLABS_WEB_API_KEY}"
      }
    }
  }
}
```

Los nombres de los campos pueden variar según el cliente. Consulta la documentación de tu cliente para saber cómo añadir un servidor MCP remoto con encabezados.

</details>

Para obtener más información sobre Web API MCP o sobre cómo alojar por tu cuenta el servidor oficial de Oxylabs, consulta [Servidores MCP](https://developers.oxylabs.io/ai-workflows/mcp).

#### ¿Habilidades o MCP?

<table data-header-hidden><thead><tr><th width="210"></th><th></th><th></th></tr></thead><tbody><tr><td></td><td><a href="https://developers.oxylabs.io/ai-workflows/agent-skills"><strong>Habilidades</strong></a></td><td><a href="https://developers.oxylabs.io/ai-workflows/mcp"><strong>Servidor MCP</strong></a></td></tr><tr><td>Proporciona al agente</td><td>Criterio: cuándo buscar, en qué fuentes confiar y cómo citar</td><td>Herramientas tipadas a las que puede llamar directamente</td></tr><tr><td>Necesita un proceso en ejecución</td><td>No</td><td>Sí</td></tr><tr><td>Funciona en</td><td>Agentes que cargan directorios de habilidades</td><td>Cualquier cliente MCP</td></tr></tbody></table>

También puedes instalar ambos. El servidor incluye `oxylabs-web-api` y lo ofrece como recurso `oxylabs://skill/web-api` por lo que conectarlo por sí solo proporciona al agente ambas partes. Instala las habilidades por separado si las quieres sin un servidor en ejecución o si quieres migrar tu base de código a Oxylabs.

## Más información

<table data-header-hidden><thead><tr><th width="170"></th><th></th></tr></thead><tbody><tr><td><a href="https://developers.oxylabs.io/products/es/api-web/autenticacion.md"><strong>Autenticación</strong></a></td><td>Gestión de claves, requisitos de encabezados y solución de problemas de autenticación.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/es/api-web/search.md"><strong>Búsqueda</strong></a></td><td>Parámetros completos de solicitud y esquemas de respuesta para <code>/v1/search</code>.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/es/api-web/search/company.md"><strong>Búsqueda de empresas</strong></a></td><td>Parámetros de solicitud y diccionario de salida para <code>/v1/search/companies</code>.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/es/api-web/scrape.md"><strong>Extraer</strong></a></td><td>Parámetros de solicitud y diccionario de salida para <code>/v1/scrape</code>.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/es/api-web/scrape/scrapers-dedicados.md"><strong>Scrapers dedicados</strong></a></td><td>Endpoints analizados específicos para cada sitio (Google, Amazon, YouTube, Walmart, etc.).</td></tr><tr><td><a href="https://developers.oxylabs.io/products/es/api-web/scrape/modos-de-entrega.md"><strong>Modos de entrega</strong></a></td><td>Llamadas Realtime, trabajos asíncronos individuales, colas de procesamiento por lotes y almacenamiento en la nube.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/es/api-web/scrape/analisis-de-ia.md"><strong>Análisis con IA</strong></a></td><td>Extracción de JSON estructurado mediante indicaciones en lenguaje natural o esquemas JSON.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/es/api-web/solucion-de-problemas.md"><strong>Solución de problemas</strong></a></td><td>Códigos de estado HTTP, lógica de reintentos y consejos para solucionar problemas.</td></tr></tbody></table>


---

# 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=<question>&goal=<user_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.
