> 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/pt-br/api-da-web.md).

# API da Web

Aprenda a usar e integrar a Oxylabs Web API – uma API REST completa para busca na web e coleta de dados de páginas.

A Web API da Oxylabs dá a aplicativos e agentes de IA acesso em tempo real à web aberta por meio de uma interface REST unificada. Ela lida com a renderização de JavaScript, desafios contra tráfego de bots, rotação de proxies e segmentação geográfica por meio de endpoints separados para diferentes etapas da aquisição de dados da web:

<table><thead><tr><th width="106">Endpoint</th><th width="504">Usado para</th><th width="148">Entrada</th></tr></thead><tbody><tr><td><a href="https://developers.oxylabs.io/products/pt-br/api-da-web/search.md">/search</a></td><td>Descobrir e classificar resultados orgânicos da web.</td><td>Palavra-chave / Consulta</td></tr><tr><td><a href="https://developers.oxylabs.io/products/pt-br/api-da-web/scrape.md">/scrape</a></td><td>Renderizar e extrair dados da página como Markdown, HTML, JSON ou captura de tela.</td><td>URL da página</td></tr></tbody></table>

{% hint style="success" %}
Os endpoints da Web API foram projetados para serem usados em conjunto: **use search para encontrar e scrape para ler.** `/search` as descrições são trechos, então qualquer informação que precise ser precisa deve vir de um `/scrape`.
{% endhint %}

## Como usar

### Obter uma chave de API

No [painel da Oxylabs](https://dashboard.oxylabs.io), crie uma instância de **Web API** , obtenha a chave de API na instância do produto e exporte-a para o ambiente do seu projeto (por exemplo, o terminal do sistema operacional ou o terminal da CLI no espaço de trabalho do projeto):

```bash
export OXYLABS_WEB_API_KEY=your_api_key_here
```

Consulte [Autenticação](https://developers.oxylabs.io/products/pt-br/api-da-web/autenticacao.md) para saber como gerenciar e alternar chaves.

### Escolher um método de integração

* **Vai integrar isso a um agente de IA (Claude Code, Cursor ou seu próprio agente)?**\
  Consulte [Integrações de agentes de IA](#ai-agent-integration) para começar a usar com um único comando.
* **Está criando sua própria integração?**\
  Siga as etapas abaixo para integrar diretamente usando endpoints REST.

### Integração manual

{% stepper %}
{% step %}

#### Pesquisar

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

**Exemplo de saída**

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

Consulte [/search](https://developers.oxylabs.io/products/pt-br/api-da-web/search.md) para ver os parâmetros da solicitação e o dicionário de saída.
{% endstep %}

{% step %}

#### Extração

Leia as páginas coletadas por `/search` ou sua 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 %}

Consulte [/scrape](https://developers.oxylabs.io/products/pt-br/api-da-web/scrape.md) para ver os parâmetros da solicitação, o dicionário de saída e os modos de entrega.
{% endstep %}

{% step %}

#### Combine: pesquisa e extração

Os trechos da pesquisa (`outline`) são truncados e insuficientes para análises aprofundadas ou pipelines de LLM. O padrão de integração usual faz uma consulta `/v1/search` para descobrir links confiáveis e, em seguida, encaminha esses URLs para `/v1/scrape` solicitando a saída em Markdown para remover artefatos HTML desnecessários.

O exemplo em Python abaixo mostra os dois endpoints em um único fluxo de trabalho:

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

### Integração com agentes de IA

Conecte a Web API diretamente a frameworks de IA, assistentes de programação (Cursor, Claude Code) ou agentes personalizados.

#### Opção 1: Prompt de integração

Cole o prompt completo a seguir em um agente de programação com IA (Claude Code, Cursor, Copilot) para instruí-lo a criar uma integração personalizada seguindo nossa especificação técnica:

{% code expandable="true" %}

```
Integrate the Oxylabs Web API into this project for live web search and page reading.

Read https://developers.oxylabs.io/products/web-api/for-agents.md and follow
it. It has the base URL, auth, both endpoint schemas, reference code, the error and retry
rules, and the checklist to satisfy. If the page does not load, stop and tell me; do not
reconstruct the API from memory.

Decide the path and tell me before writing anything:
- Will this project's own code call the API at runtime? -> write the client the page
  specifies, matching how this codebase already makes outbound HTTP calls.
- Is the web access for you during this session rather than for the project's code?
  -> install the MCP server and the skills, the way the page describes.

The key is in OXYLABS_WEB_API_KEY or a .env here. If it is in neither, ask me. Never
print the key: not in code, logs, tests, or your replies to me.

Prove it works before writing tests: make one real search, scrape one URL from the
results, and show me both request ids. If a call returns 401, stop and tell me.

When a scrape comes back empty or skeletal, retry it once with run_js: true. If it is still
empty and the site is on a country TLD (.lt, .es, .co.uk), retry once more with run_js and
com a localização definida para esse país e, em seguida, informe que a página está ilegível.

Em seguida, adicione um teste para as tentativas e o mapeamento de erros usando um transporte simulado e execute-o.
Se não puder executar comandos neste ambiente, informe isso uma vez e forneça os comandos exatos
que devo executar.

Informe: o caminho percorrido, cada item da lista de verificação da página marcado como concluído ou não,
o que ainda preciso fazer por conta própria e tudo o que você não conseguiu concluir. Não me pergunte
se deve prosseguir; faça o trabalho.
```

{% endcode %}

O prompt direciona o agente para uma única página que contém a fonte oficial completa do produto: URL base, autorização, esquemas dos dois endpoints, código de referência, regras de erro e repetição, além de uma lista de verificação para o agente.

Você encontra a especificação completa de referência para agentes na [Para agentes](https://developers.oxylabs.io/products/pt-br/api-da-web/for-agents.md) .

{% hint style="info" %}
**Se o agente não conseguir acessar URLs**, forneça a página completa. `for-agents.md` é um Markdown simples e autocontido; portanto, salve-o ou cole-o antes do prompt e remova o parágrafo que menciona a URL. Não inclua a especificação no prompt: as duas regras de repetição são repetidas ali porque o agente as aplica durante a tarefa; todo o restante deve ficar na página para evitar divergências.
{% endhint %}

#### Opção 2: habilidades de agente

Instale as habilidades oficiais para agentes para ensinar ao seu agente de IA metodologias de pesquisa, regras de citação de fontes e execução de buscas até a extração de dados:

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

Para ver mais opções de instalação, consulte [Habilidades de agente da Oxylabs](https://developers.oxylabs.io/ai-workflows/agent-skills).

#### Opção 3: servidor MCP

Conecte-se ao nosso servidor MCP oficial ou hospede-o por conta própria para disponibilizar as ferramentas de busca e extração da Web API, além de ferramentas dedicadas de extração, diretamente no Claude Code, Cursor ou no seu agente de IA personalizado. Para isso, configure o agente para usar o servidor hospedado pela 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> (ou outros clientes compatíveis com cabeçalhos personalizados)</summary>

Para qualquer cliente compatível com servidores MCP remotos e cabeçalhos personalizados, adicione a URL do servidor e um cabeçalho `Authorization` à configuração MCP do cliente. Por exemplo, no arquivo `mcp.json`:

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

Os nomes dos campos podem variar entre clientes. Consulte a documentação do seu cliente para saber como adicionar um servidor MCP remoto com cabeçalhos.

</details>

Para saber mais sobre o Web API MCP ou sobre como hospedar por conta própria o servidor oficial da Oxylabs, consulte [Servidores MCP](https://developers.oxylabs.io/ai-workflows/mcp).

#### Habilidades ou 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>Oferece ao agente</td><td>Capacidade de julgamento: quando pesquisar, em quais fontes confiar e como citar</td><td>Ferramentas tipadas que ele pode chamar diretamente</td></tr><tr><td>Precisa de um processo em execução</td><td>Não</td><td>Sim</td></tr><tr><td>Funciona em</td><td>Agentes que carregam diretórios de skills</td><td>Qualquer cliente MCP</td></tr></tbody></table>

Instalar ambos é uma opção. O servidor inclui `oxylabs-web-api` e o disponibiliza como o recurso `oxylabs://skill/web-api` para que, ao conectar apenas o servidor, o agente tenha acesso às duas partes. Instale as skills separadamente quando quiser usá-las sem um servidor em execução ou quando quiser migrar sua base de código para a Oxylabs.

## Saiba mais

<table data-header-hidden><thead><tr><th width="170"></th><th></th></tr></thead><tbody><tr><td><a href="https://developers.oxylabs.io/products/pt-br/api-da-web/autenticacao.md"><strong>Autenticação</strong></a></td><td>Gerenciamento de chaves, requisitos de cabeçalho e solução de problemas de autenticação.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/pt-br/api-da-web/search.md"><strong>Pesquisar</strong></a></td><td>Parâmetros completos da solicitação e esquemas de resposta para <code>/v1/search</code>.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/pt-br/api-da-web/search/company.md"><strong>Pesquisa de empresas</strong></a></td><td>Parâmetros da solicitação e dicionário de saída para <code>/v1/search/companies</code>.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/pt-br/api-da-web/scrape.md"><strong>Extração</strong></a></td><td>Parâmetros da solicitação e dicionário de saída para <code>/v1/scrape</code>.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/pt-br/api-da-web/scrape/raspadores-dedicados.md"><strong>Scrapers dedicados</strong></a></td><td>Endpoints analisados específicos para cada alvo (Google, Amazon, YouTube, Walmart etc.).</td></tr><tr><td><a href="https://developers.oxylabs.io/products/pt-br/api-da-web/scrape/modos-de-entrega.md"><strong>Modos de entrega</strong></a></td><td>Chamadas Realtime, tarefas assíncronas individuais, filas de processamento em lote e armazenamento em nuvem.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/pt-br/api-da-web/scrape/analise-por-ia.md"><strong>Análise com IA</strong></a></td><td>Extração de JSON estruturado usando instruções em linguagem natural ou esquemas JSON.</td></tr><tr><td><a href="https://developers.oxylabs.io/products/pt-br/api-da-web/solucao-de-problemas.md"><strong>Solução de problemas</strong></a></td><td>Códigos de status HTTP, lógica de novas tentativas e dicas para solução de 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/pt-br/api-da-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.
