> 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 a [documentação da Web API](https://developers.oxylabs.io/products/pt-br/api-da-web.md).
{% endhint %}

[**A Web API da Oxylabs**](https://oxylabs.io/products/web-api) oferece duas coisas ao seu aplicativo ou agente de IA que são surpreendentemente difíceis de obter na web aberta: **encontrar páginas relevantes e atualizadas e extrair seus dados com confiabilidade**. Um endpoint pesquisa na web em tempo real; o outro extrai dados de qualquer página (renderiza JavaScript e lida com desafios de acesso) e retorna dados limpos, prontos para uso.

<table><thead><tr><th width="159">Endpoint</th><th>O que oferece</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 classificados por relevância: título, descrição e 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 em Markdown, HTML, JSON ou captura de tela</td><td>Você sabe a URL e precisa obter o conteúdo da página</td></tr></tbody></table>

Eles foram projetados para serem usados em conjunto: **pesquise para encontrar, extraia para obter os dados.** Este guia de início rápido aborda:

* **Integração manual** – seu próprio código chamando a API diretamente.
* **Integração simplificada com IA** – uso da Web API por meio de um agente de IA proprietário ou personalizado.

{% hint style="success" %}
Quer testar a Web API em uma interface simples antes da implementação completa? Confira o [Playground da Web API](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 [Painel da Oxylabs](https://dashboard.oxylabs.io/).
2. **Adicione uma instância de produto:** Clique em **+ Add product instance** e selecione Web API na categoria Web access.
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 da 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 sistema operacional ou o terminal CLI no espaço de trabalho do projeto):

```bash
export OXYLABS_WEB_API_KEY=your_api_key_here
```

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

## Integração com a Web API

#### Vai integrar isso a um agente de IA?

Acesse [Integrações com agentes de IA](#ai-agent-integration) para começar a usar com um único comando.

#### Está desenvolvendo sua própria integração personalizada?

Comece pela integração manual abaixo.

### Integração manual

De acordo com suas necessidades de dados, você pode usar os endpoints da Web API separadamente para pesquisa na web, extração de dados ou como um pipeline completo de coleta e entrega de dados.

{% stepper %}
{% step %}

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

Encontre as páginas que contêm a resposta à sua `query`:

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

#### Extrair uma página (`/scrape`)

Extraia o conteúdo completo de qualquer página de um site público informando a `url` de destino e o formato de saída desejado (`markdown`, `html`, `json`, `screenshot`). Veja uma solicitação de conteúdo de 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 completo (da pesquisa à extração)

`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 `query` e passe a URL do resultado para `/scrape` para recuperar os dados. Veja um exemplo completo e funcional em Python:

{% 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. Descobrir 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 é retornado na resposta.** Para coleta de dados em grande volume, recomendamos executar os scrapers como jobs em `/v1/async/scrape` e receber os resultados por polling, callback ou diretamente no seu bucket. Consulte [Modos de entrega](https://developers.oxylabs.io/products/web-api/scrape/delivery-modes).
{% endhint %}

### Integração com agentes de IA

A Oxylabs Web API foi projetada para facilitar fluxos de trabalho com agentes de IA usando **Agent Skills**, **MCP** (Model Context Protocol) ou integrações simples **com um único prompt**. Depois de obter 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 de uma página – cole um prompt em um agente de programação para que ele crie uma integração personalizada para você.**

Se você quiser que um assistente de programaçã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 realizar pesquisas na web e ler páginas em tempo real.

Leia https://developers.oxylabs.io/products/web-api/for-agents.md e siga
as instruções. A página contém a URL base, a autenticação, os esquemas dos dois endpoints, o código de referência, as regras
de erro e novas tentativas 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 qual caminho seguir e me informe antes de escrever qualquer coisa:
- O próprio código deste projeto chamará a API em tempo de execução? -> escreva o cliente que a página
  especifica, seguindo a forma como este código já faz chamadas HTTP de saída.
- O acesso à web é para você usar durante esta sessão, e não para o código do projeto?
  -> instale o servidor MCP e as skills, conforme descrito na página.

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

Comprove que funciona antes de escrever testes: faça uma pesquisa real, extraia uma URL dos
resultados e mostre-me os IDs das duas requisições. Se uma chamada retornar 401, pare e me avise.

Quando uma raspagem retorna vazia ou com poucos dados, tente novamente uma vez com run_js: true. Se continuar
vazia e o site usar um TLD de país (.lt, .es, .co.uk), tente mais uma vez com run_js e
com a localização definida para esse país e, em seguida, informe que a página não pôde ser lida.

Em seguida, adicione um teste para a nova tentativa 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 seguido, cada item da checklist 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 %}

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

{% tab title="Habilidades para agentes" icon="head-side-gear" %}
**Habilidades para agentes – instalam o conhecimento necessário para usar a API; não é preciso executar nenhum servidor.**

Adicione habilidades oficiais para agentes que ensinam seu agente de IA a pesquisar, fazer raspagens, citar fontes e realizar pesquisas na Web com a Web API da Oxylabs usando o seguinte comando no terminal:

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

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

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

Conecte-se ao nosso servidor MCP oficial ou hospede-o por conta própria para disponibilizar as ferramentas de pesquisa, raspagem e extração da Web API diretamente no Claude Code, no Cursor ou no seu agente de IA personalizado.

Para implementar com mais facilidade, adicione o servidor ao seu cliente direcionando seu agente para 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 que aceitam cabeçalhos personalizados)</summary>

Para qualquer cliente compatível com servidores MCP remotos com 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 a integração MCP da Web API ou sobre como hospedar por conta própria o servidor oficial da Oxylabs, consulte [Servidores 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>query</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 de pesquisa orgânica 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 a extrair</td></tr><tr><td><code>output</code></td><td>array</td><td>Formatos a 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 especializados usam um formato diferente. Consulte <a href="https://developers.oxylabs.io/products/pt-br/api-da-web/scrape/raspadores-dedicados.md">Scrapers especializados</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 tempo limite de 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. Trabalho Realtime/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 (chave de API inválida ou ausente).</td><td>Não, verifique a chave na sua instância da Web API</td></tr><tr><td><code>429</code></td><td>Limite de taxa atingido ou cota esgotada</td><td>Limite de taxa: sim, com espera progressiva. Cota: não.</td></tr><tr><td><code>5xx</code></td><td>Falha no servidor upstream ou falha na raspagem</td><td>Sim, até ~3 tentativas com espera progressiva.</td></tr></tbody></table>

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

## Próximas etapas

* **Criando suas primeiras solicitações personalizadas?** Faça protótipos mais rápido com o [Web API Playground](https://developers.oxylabs.io/products/web-api/playground).
* **Precisa de dados de um site específico?** Confira todos os [scrapers dedicados](https://developers.oxylabs.io/products/web-api/scrape/dedicated-scrapers).
* **Procurando dados de empresas?** Obtenha perfis estruturados de empresas a partir de uma palavra-chave com o [Company Search](https://developers.oxylabs.io/products/web-api/search/companies).
* **Quer JSON estruturado de qualquer página?** Experimente o recurso integrado de [análise com IA da Web API](https://developers.oxylabs.io/products/web-api/scrape/ai-parsing).
* **Raspando dados em grande escala ou enviando-os para um armazenamento na nuvem?** Saiba mais sobre os [modos de entrega](https://developers.oxylabs.io/products/web-api/scrape/delivery-modes).
* **Quer que um agente de IA use a Web API sem que você precise escrever código?** Experimente o servidor oficial da Oxylabs para [MCP](https://developers.oxylabs.io/ai-workflows/mcp) ou [Agent Skills](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.
