> 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-web.md). # API Web Aprenda a usar e integrar a API Web da Oxylabs – uma API REST completa para busca na web e coleta de dados de páginas. A API Web da Oxylabs oferece a aplicativos e agentes de IA acesso em tempo real à web aberta por meio de uma interface REST unificada. Ela lida com renderização de JavaScript, desafios de tráfego de bots, rotação de proxies e geo-targeting por meio de endpoints separados para diferentes etapas de aquisição de dados da web:
EndpointUsado paraEntrada
/searchDescobrir e classificar resultados orgânicos da web.Palavra-chave / Consulta
/scrapeRenderizar e extrair dados da página como Markdown, HTML, JSON ou captura de tela.URL da página
{% hint style="success" %} Os endpoints da Web API foram projetados para serem usados em conjunto: **search para encontrar, scrape para ler.** `/search` as descrições são trechos, então qualquer coisa sobre a qual você precise de precisão vem de um `/scrape`. {% endhint %} ## Como usar ### Obtenha uma chave de API No [painel da Oxylabs](https://dashboard.oxylabs.io), crie uma **Web API** instância, obtenha a chave de API da instância do produto e exporte-a para o ambiente do seu projeto (por exemplo, seu terminal do SO ou o terminal da CLI no workspace do projeto): ```bash export OXYLABS_WEB_API_KEY=your_api_key_here ``` Veja [Autenticação](/products/pt-br/api-web/autenticacao.md) para gerenciamento e rotação de chaves. ### Escolha o método de integração * **Conectando isto a um agente de IA (Claude Code, Cursor ou seu próprio agente)?**\ Confira as [integrações de agentes de IA](#ai-agent-integration) para começar a usá-lo com um comando. * **Construindo sua própria integração?**\ Siga os passos abaixo para integrar diretamente usando endpoints REST. ### Integração manual {% stepper %} {% step %} #### Pesquisa {% 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": "Cronograma de implementação | Lei de Inteligência Artificial da UE", "outline": [ "Data 2 de agosto de 2025 Fornecedores: precisam estar em conformidade com a AI Act até 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" } } ``` Veja [/search](/products/pt-br/api-web/search.md) para parâmetros da solicitação e dicionário de saída. {% endstep %} {% step %} #### Coleta 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 %} Veja [/scrape](/products/pt-br/api-web/scrape.md) para parâmetros da solicitação, dicionário de saída, modos de entrega. {% endstep %} {% step %} #### Combinação: search-to-scrape Trechos de pesquisa (`outline`) são truncados e insuficientes para análise profunda ou pipelines de LLM. O padrão de integração padrão consulta `/v1/search` para descobrir links confiáveis, depois encaminha esses URLs para `/v1/scrape` solicitando saída em Markdown para remover artefatos HTML desnecessários. O exemplo em Python abaixo mostra ambos os 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. Descobrir 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. Extrair 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 %} ### Integração de agente 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 de IA (Claude Code, Cursor, Copilot) para instruí-lo a criar uma integração personalizada seguindo nossa especificação técnica: {% code expandable="true" %} ``` Integre a Web API da Oxylabs a este projeto para pesquisa web em tempo real e leitura de páginas. Leia https://developers.oxylabs.io/products/web-api/for-agents.md e siga isso. Ele tem a URL base, autenticação, ambos os esquemas de endpoint, código de referência, as regras de erro e retry, e a checklist 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 chamará a API em tempo de execução? -> 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 para o código do projeto? -> instale o servidor MCP e as habilidades, da forma como 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, pergunte-me. Nunca imprima a chave: nem no código, logs, testes ou suas respostas para mim. Comprove que funciona antes de escrever testes: faça uma pesquisa real, extraia uma URL dos resultados e me mostre ambos os IDs da solicitação. Se uma chamada retornar 401, pare e me avise. Quando uma extração voltar vazia ou esquelética, tente novamente uma vez com run_js: true. Se ainda estiver vazia 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, depois reporte a página como ilegível. Depois adicione um teste para o retry e o mapeamento de erros contra um transporte mockado e execute-o. Se você não puder executar comandos neste ambiente, diga isso uma vez e me forneça os comandos exatos para executar em vez disso. Reporte de volta: o caminho que você seguiu, cada item da checklist na página marcado como concluído ou não, o que ainda preciso fazer sozinho e qualquer coisa que você não conseguiu terminar. Não me pergunte se deve prosseguir; faça o trabalho. ``` {% endcode %} O prompt aponta o agente para uma única página com uma fonte única de verdade completa do produto: URL base, autorização, ambos os esquemas de endpoint, código de referência, regras de erro e retry e uma checklist do agente. Você pode encontrar a referência completa da especificação do agente na [Para Agentes](/products/pt-br/api-web/for-agents.md) página. {% hint style="info" %} **Se o agente não conseguir buscar URLs**, forneça a página inteira em vez disso. `for-agents.md` é Markdown puro e autocontido, então salve-o ou cole-o acima do prompt e remova o parágrafo que nomeia a URL. Mantenha a especificação fora do prompt: as duas regras de retry são repetidas ali porque um agente as aplica no meio da tarefa; todo o resto pertence à página para que não saia do alinhamento. {% endhint %} #### Opção 2: skills do agente Instale as skills oficiais do agente para ensinar ao seu agente de IA metodologias de pesquisa, regras de citação de fontes e execução de search-to-scrape: ```bash npx skills add oxylabs/web-api-skills ``` Para mais opções de instalação, veja [Oxylabs Agent Skills](https://developers.oxylabs.io/ai-workflows/agent-skills). #### Opção 3: servidor MCP Para uma implementação mais minimalista e controlada, auto-hospede nosso servidor MCP oficial para expor **search**, **scrape**, e **extração** ferramentas para qualquer cliente compatível com MCP: ```bash uv tool install git+https://github.com/oxylabs/web-api-mcp ``` Para detalhes de configuração e definições das ferramentas, veja [Servidor MCP](https://developers.oxylabs.io/ai-workflows/mcp). #### Skills ou MCP?
Skillsservidor MCP
Oferece ao agenteJulgamento: quando pesquisar, quais fontes confiar, como citarFerramentas tipadas que ele pode chamar diretamente
Precisa de um processo em execuçãoNãoSim
Funciona emAgentes que carregam diretórios de skillsQualquer cliente MCP
Instalar ambos é uma opção. O servidor agrupa `oxylabs-web-api` e o disponibiliza como o `oxylabs://skill/web-api` recurso, então conectá-lo sozinho dá ao agente as duas partes. Instale os skills separadamente quando quiser usá-los sem um servidor em execução, ou quando quiser migrar sua base de código para a Oxylabs. ## Saiba mais
AutenticaçãoGerenciamento de chaves, requisitos de cabeçalho e solução de problemas de autenticação.
PesquisaParâmetros completos da solicitação e esquemas de resposta para /v1/search.
ColetaParâmetros da solicitação e dicionário de saída para /v1/scrape.
Scrapers dedicadosEndpoints analisados específicos para cada destino (Google, Amazon, YouTube, Walmart, etc.).
Modos de entregaChamadas Realtime, polling/webhooks assíncronos de tarefa única e filas de lotes em massa.
Análise de IAExtração de JSON estruturado usando prompts em linguagem natural ou JSON Schemas.
Solução de problemasCódigos de status HTTP, lógica de retry e dicas de solução 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/pt-br/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.