> 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/documentation/pt-br/comecar/inicio-rapido-web-api.md).

# Início rápido: Web API

Vá da chave de API à sua primeira busca e extração na Oxylabs Web API em apenas cinco minutos.

{% hint style="success" %}
Já conhece o básico? Confira [documentação da Web API](/products/pt-br/api-web.md).
{% endhint %}

[**Oxylabs Web API**](https://oxylabs.io/products/web-api) dá à sua aplicação ou ao seu agente de IA duas coisas que a web aberta torna surpreendentemente difíceis: **encontrar as páginas certas e novas, e extrair seus dados de forma confiável**. Um endpoint pesquisa a web ao vivo e o outro faz scrape de qualquer página (renderizando JavaScript e lidando com desafios de acesso) e devolve dados limpos prontos para uso.

<table><thead><tr><th width="159">Endpoint</th><th>Fornece</th><th>Use quando</th></tr></thead><tbody><tr><td><a href="https://developers.oxylabs.io/products/web-api/search"><code>POST /v1/search</code></a></td><td>Resultados ranqueados: título, descrição, URL</td><td>Você não sabe qual página contém a resposta</td></tr><tr><td><a href="https://developers.oxylabs.io/products/web-api/scrape"><code>POST /v1/scrape</code></a></td><td>Uma página como Markdown, HTML, JSON ou uma captura de tela</td><td>Você conhece a URL e precisa do conteúdo dela</td></tr></tbody></table>

Eles foram projetados para serem usados juntos: **pesquise para encontrar, faça scrape para extrair.** Este guia de início rápido cobre:

* **integração manual** – seu próprio código chamando a API diretamente.
* **integração fácil com IA** – usando a Web API por meio de um agente de IA proprietário ou personalizado.

{% hint style="success" %}
Quer testar a Web API em um ambiente simples baseado em interface antes da implementação completa? Confira [Web API Playground](https://developers.oxylabs.io/products/web-api/playground).
{% endhint %}

## Configuração e chave de API <a href="#docs-internal-guid-4566d081-7fff-6c77-5105-4c81aa345516" id="docs-internal-guid-4566d081-7fff-6c77-5105-4c81aa345516"></a>

1. **Crie uma conta:** Cadastre-se no [Oxylabs Dashboard](https://dashboard.oxylabs.io/).
2. **Adicione uma instância do produto:** Clique em **+ Adicionar instância do produto** e selecione Web API na categoria Acesso à web.
3. **Configure:** Escolha o nome da instância, os limites de uso do produto (opcional) e crie a instância.
4. **Obtenha as credenciais:** Clique na instância do Web API na tabela de instâncias da página inicial do painel e obtenha sua chave de API.
5. **Exporte sua chave de API** para o ambiente do seu projeto (por exemplo, o terminal do seu sistema operacional ou o terminal CLI no workspace do projeto):

```bash
export OXYLABS_WEB_API_KEY=your_api_key_here
```

{% hint style="info" %}
**Observação:** Mantenha sempre sua chave no lado do servidor. Nunca a coloque no controle de versão nem a exponha em código do lado do cliente.
{% endhint %}

## Integração com a Web API

#### Conectando isso a um agente de IA?

Pule para [integrações de agentes de IA](#ai-agent-integration) para começar a usá-la com um comando.

#### Construindo sua própria integração personalizada?

Comece a integração manual abaixo.

### integração manual

Dependendo das suas necessidades de dados, você pode usar os endpoints da Web API separadamente para busca na web, raspagem ou como um pipeline completo de coleta e entrega de dados.

{% stepper %}
{% step %}

#### Pesquisar páginas (`/search`)

Encontre quais páginas contêm a resposta para sua `consulta`:

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

<details>

<summary>Exemplo de saída</summary>

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

</details>
{% endstep %}

{% step %}

#### Fazer scrape de uma página (`/scrape`)

Faça scrape do conteúdo completo de qualquer site público passando a `url` e o formato de saída desejado (`markdown`, `html`, `json`, `screenshot`). Aqui está uma solicitação de conteúdo da página em Markdown:

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

{% endstep %}

{% step %}

#### Pipeline completa (da busca à raspagem)

`outline` encontrado em `/search` é uma lista de trechos truncados e muitas vezes não é útil para casos de uso avançados ou fluxos de trabalho de IA.

Para obter dados estruturados a partir de uma única consulta, pesquise na web com `/search` para encontrar dados relevantes de acordo com sua `consulta` e passe a URL do resultado para `/scrape` para recuperação de dados. Aqui está um exemplo completo em Python que funciona:

{% 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. Descubra as URLs de destino
    hits = requests.post(
        f"{API}/v1/search",
        headers=HEADERS,
        json={"query": question, "max_results": 10},
    )
    hits.raise_for_status()
    # 2. Extraia o conteúdo completo da 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"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 %}

{% hint style="info" %}
**Tudo acima é Realtime – o resultado volta na resposta.** Para coleta de dados em alto volume, recomendamos executar scrapers como jobs em `/v1/async/scrape` e entregar por polling, callback ou diretamente no seu bucket. Veja [Modos de entrega](https://developers.oxylabs.io/products/web-api/scrape/delivery-modes).
{% endhint %}

### Integração com agente de IA

A Oxylabs Web API foi projetada para fluxos de trabalho fáceis com agentes de IA usando **Habilidades de agente**, **MCP** (Protocolo de Contexto do Modelo) ou integrações simples **de um único prompt**. Depois que você tiver sua chave de API, escolha o método de integração.

{% tabs %}
{% tab title="Integração com um único prompt" icon="rectangle-terminal" %}
**Prompt de integração em uma página – cole um prompt em um agente de codificação e faça com que ele crie uma integração personalizada para você.**

Se você quiser que um assistente de codificação com IA (como Claude Code, Cursor ou Copilot) crie uma integração para você, cole o seguinte prompt:

{% code overflow="wrap" expandable="true" %}

```
Integre a Oxylabs Web API a este projeto para busca na web em tempo real e leitura de páginas.

Leia https://developers.oxylabs.io/products/web-api/for-agents.md e siga
ele. Ele tem a URL base, autenticação, os esquemas de ambos os endpoints, código de referência, as regras de erro e retry,
regras e a lista de verificação a cumprir. Se a página não carregar, pare e me avise; não
reconstrua a API de memória.

Decida o caminho e me diga antes de escrever qualquer coisa:
- O código deste projeto vai chamar a API em runtime? -> escreva o cliente que a página
  especifica, correspondendo à forma como esta base de código já faz chamadas HTTP de saída.
- O acesso à web é para você durante esta sessão, em vez de ser para o código do projeto?
  -> instale o servidor MCP e as habilidades, da maneira que a página descreve.

A chave está em OXYLABS_WEB_API_KEY ou em um .env aqui. Se não estiver em nenhum dos dois, me pergunte. Nunca
imprima a chave: nem no código, logs, testes ou nas suas respostas para mim.

Comprove que funciona antes de escrever testes: faça uma busca real, faça scrape de uma URL dos
resultados e me mostre os dois IDs da requisição. Se uma chamada retornar 401, pare e me avise.

Quando um scrape voltar vazio ou esquelético, tente novamente uma vez com run_js: true. Se ainda estiver
vazio e o site estiver em um TLD de país (.lt, .es, .co.uk), tente mais uma vez com run_js e
location definido para esse país, e então informe a página como ilegível.

Depois, adicione um teste para o retry e o mapeamento de erro usando um transporte mockado e execute-o.
Se você não puder executar comandos neste ambiente, diga isso uma vez e me dê os
comandos exatos para executar em vez disso.

Reporte de volta: o caminho que você seguiu, cada item da lista de verificação da página marcado como concluído ou não,
o que ainda preciso fazer sozinho e qualquer coisa que você não conseguiu concluir. Não me pergunte
se deve prosseguir; faça o trabalho.
```

{% endcode %}

Veja um exemplo completo e saiba mais sobre a integração com Web API na [documentação](https://developers.oxylabs.io/products/web-api).
{% endtab %}

{% tab title="Habilidades de agente" icon="head-side-gear" %}
**Habilidades de agente – instalam o conhecimento sobre como usar a API, sem necessidade de servidor em execução.**

Adicione habilidades oficiais de agente que ensinam seu agente de IA a pesquisar, fazer scrape, citar fontes e lidar com pesquisa na web por meio da Oxylabs Web API usando o seguinte comando de terminal:

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

Agora seu agente sabe tudo o que há para saber sobre a Oxylabs Web API e como usá-la. Para saber mais sobre as habilidades de agente do Web API, veja nosso [documentação](https://developers.oxylabs.io/ai-workflows/agent-skills).
{% endtab %}

{% tab title="Servidor MCP" icon="server" %}
**Servidor MCP – ferramentas tipadas para busca, raspagem e raspadores dedicados para qualquer cliente MCP.**

Hospede nosso servidor MCP oficial para expor as ferramentas de busca, raspagem e extração do Web API diretamente ao Claude Code, Cursor ou ao seu agente de IA personalizado:

```bash
uv tool install git+https://github.com/oxylabs/web-api-mcp
```

Para saber mais sobre a integração MCP do Web API, veja [servidor MCP](https://developers.oxylabs.io/ai-workflows/mcp).
{% endtab %}
{% endtabs %}

### Parâmetros essenciais

#### /search <a href="#docs-internal-guid-5786cd1b-7fff-0a37-d2dd-abcf76c7e3ef" id="docs-internal-guid-5786cd1b-7fff-0a37-d2dd-abcf76c7e3ef"></a>

<table><thead><tr><th width="121">Parâmetro</th><th width="86">Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>consulta</code></td><td>texto</td><td>Palavra-chave ou frase de pesquisa</td></tr><tr><td><code>max_results</code></td><td>inteiro</td><td>Número de resultados orgânicos de pesquisa a retornar (<code>1-20</code>)</td></tr><tr><td><code>location</code></td><td>texto</td><td>Código de país de 2 letras (por exemplo, <code>"DE"</code>, <code>"US"</code>) para pesquisa localizada</td></tr></tbody></table>

#### /scrape

<table><thead><tr><th width="111">Parâmetro</th><th width="99">Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>url</code></td><td>texto</td><td>URL para fazer scrape</td></tr><tr><td><code>output</code></td><td>lista</td><td>Formatos para retornar: <code>"html"</code> (padrão), <code>"markdown"</code>, <code>"json"</code>, <code>"screenshot"</code></td></tr><tr><td><code>json</code></td><td>objeto</td><td>Usado para análise personalizada com IA por meio de prompt ou esquema</td></tr><tr><td><code>location</code></td><td>texto</td><td>Código de país de 2 letras (por exemplo, <code>"DE"</code>, <code>"US"</code>). Alguns scrapers dedicados usam um formato diferente. Veja <a href="/products/pt-br/api-web/scrape/scrapers-dedicados.md">Scrapers Dedicados</a>.</td></tr><tr><td><code>run_js</code></td><td>booleano</td><td>Renderiza a página em um navegador real antes de capturar o conteúdo. Mais lento, use um timeout do cliente de <code>150</code>s ou mais.</td></tr><tr><td><code>device</code></td><td>texto</td><td>Emulação de dispositivo: <code>"desktop"</code> (padrão) ou <code>"mobile"</code>.</td></tr></tbody></table>

### Códigos de resposta comuns

<table><thead><tr><th width="112">Status</th><th width="322">Significado</th><th>Tentar novamente?</th></tr></thead><tbody><tr><td><code>200</code> / <code>202</code></td><td>Sucesso. Realtime / job assíncrono aceito</td><td>–</td></tr><tr><td><code>400</code></td><td>Solicitação malformada</td><td>Não, corrija o campo indicado em <code>errors[].pointer</code>.</td></tr><tr><td><code>401</code></td><td>Erro de autenticação (API key inválida ou ausente).</td><td>Não, verifique a chave na sua instância do Web API</td></tr><tr><td><code>429</code></td><td>Limite de taxa ou cota esgotada</td><td>Limite de taxa: sim, com backoff. Cota: não.</td></tr><tr><td><code>5xx</code></td><td>Falha upstream ou falha ao fazer scrape</td><td>Sim, até ~3 tentativas com backoff.</td></tr></tbody></table>

Veja todos os [códigos de resposta](https://developers.oxylabs.io/products/web-api/troubleshooting) para saber sobre todos os códigos de status e encontrar dicas de solução de problemas.

## Próximos passos

* **Quer a visão completa do produto?** Veja a [documentação da Web API](https://developers.oxylabs.io/products/web-api).
* **Construindo suas primeiras requisições personalizadas?** Prototipe mais rápido com [Web API Playground](https://developers.oxylabs.io/products/web-api/playground).
* **Precisa de dados de um site específico?** Confira todos os recursos da Web API [Scrapers Dedicados](https://developers.oxylabs.io/products/web-api/scrape/dedicated-scrapers).
* **Quer JSON estruturado de qualquer página?** Experimente o recurso integrado do Web API [Análise com IA](https://developers.oxylabs.io/products/web-api/scrape/ai-parsing).
* **Raspagem em volume ou entrega para armazenamento em nuvem?** Saiba mais sobre os modos disponíveis [Modos de entrega](https://developers.oxylabs.io/products/web-api/scrape/delivery-modes).
* **Quer que um agente de IA use o Web API sem você escrever código?** Experimente os recursos oficiais da Oxylabs [servidor MCP](https://developers.oxylabs.io/ai-workflows/mcp) ou [Habilidades de agente](https://developers.oxylabs.io/ai-workflows/agent-skills).


---

# 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/documentation/pt-br/comecar/inicio-rapido-web-api.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.