Da URL ao texto.

01 / Primeira chamada

curl "$DEEPLOOK_BASE_URL/v1/open" \
  -H "Authorization: Bearer $DEEPLOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","timeoutMs":30000}'

O playground da página inicial executa chamadas reais pelo servidor do demo, sem solicitar sua chave. Os exemplos de código desta documentação não são executados automaticamente.

02 / Requisição

POST /v1/open · Content-Type: application/json
Autenticação: Authorization: Bearer <chave>

O prazo cobre DNS, início do Chrome, navegação e extração. A limpeza do processo ocorre em seguida. URLs locais, privadas e de metadados são recusadas, incluindo redirecionamentos e recursos da página.

03 / Resposta de sucesso

HTTP 200 entrega diretamente o objeto da página. O exemplo abaixo é ilustrativo e mostra um recorte dos campos, não uma resposta capturada ao vivo.

{
  "requestedUrl": "https://example.com",
  "finalUrl": "https://example.com/",
  "httpStatus": 200,
  "title": "Example Domain",
  "text": "Example Domain\nThis domain is for use...",
  "truncated": false
}

04 / Erros que o seu agente pode tratar

Uma falha retorna JSON com error e message. Mensagens podem variar; use o código do erro para decidir o próximo passo.

{
  "error": "challenge",
  "message": "Mensagem descritiva da falha"
}

Falhas de página podem incluir URL final, título e marcador detectado. O texto da página de erro é excluído. Não há resolução de captchas ou garantia de acesso a qualquer site.

Workflow / Extração para seu crawler

O modo Crawl no playground descobre links do mesmo site e demonstra a extração de até 3 páginas. Essa orquestração pertence ao demo do site; a API continua recebendo uma URL por requisição.

Use o DeepLook como a camada de scraping do seu fluxo de crawling. Sua aplicação seleciona as URLs e gerencia a fila; cada chamada extrai uma página.

// Run in Node.js with your own API base URL and key.
const urls = ['https://example.com/', 'https://example.org/'];
const pages = [];

for (const url of urls) {
  const response = await fetch(process.env.DEEPLOOK_BASE_URL + '/v1/open', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.DEEPLOOK_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ url, timeoutMs: 30000 })
  });
  const page = await response.json();
  if (!response.ok) {
    console.error(url, page.error);
    continue;
  }
  pages.push({ url: page.finalUrl, title: page.title, text: page.text });
}

console.log(pages);

O exemplo faz requisições sequenciais e continua quando a API retorna um erro de página. Configure a base URL e a chave da sua instância, respeite a cota da conta e defina os limites do seu crawler. Uma falha de rede interrompe este exemplo; filas, persistência e tentativas adicionais ficam na sua aplicação.

05 / CLI local

O DeepLook reúne o motor, a CLI e o adaptador MCP via stdio. O DeepLook-API fornece o serviço HTTP separado. Ambos são de código aberto sob Apache-2.0; os comandos abaixo compilam o código do GitHub.

Compilar o motor local

Requisitos: Node.js 22.14 ou superior; Google Chrome para leituras locais. Clone e compile o motor:

git clone https://github.com/sayhitogambit/DeepLook.git
cd DeepLook
npm ci
npm run build
node dist/cli.js open https://example.com --json

Sem --json, a CLI imprime o texto visível. O parâmetro --timeout-ms aceita de 1 a 120000 ms. A infraestrutura, o Chrome e a execução ficam sob sua operação.

Para automação, use --machine: a CLI escreve um único objeto JSON e uma quebra de linha. Sucesso sai com código 0 e retorna {"version":1,"ok":true,"page":{...}}; falha sai com código 1 e retorna {"version":1,"ok":false,"error":"...","message":"..."}. Texto de páginas de erro não é incluído.

As variáveis DEEPLOOK_BASE_URL e DEEPLOOK_API_KEY nos exemplos HTTP são nomes usados por estes exemplos. A CLI e o MCP usam DEEPLOOK_API_URL e DEEPLOOK_API_TOKEN para se conectar à sua API; sem endpoint, usam o Chrome local.

06 / MCP via stdio

A CLI oferece deeplook mcp: um servidor MCP via stdio com a ferramenta deeplook_open. Após compilar o motor, configure seu cliente com um caminho absoluto para dist/cli.js. O formato de configuração varia por cliente.

Por padrão, o MCP usa o Chrome local. Para usar sua própria API, defina DEEPLOOK_API_URL e DEEPLOOK_API_TOKEN no ambiente privado do processo MCP. Use HTTPS fora de loopback. Não compartilhe tokens no arquivo de configuração. O adaptador é via stdio e não oferece servidor MCP HTTP.

{
  "mcpServers": {
    "deeplook": {
      "command": "node",
      "args": ["/absolute/path/to/DeepLook/dist/cli.js", "mcp"]
    }
  }
}

Chame deeplook_open com {"url":"https://example.com","timeoutMs":30000}. O prazo é opcional, padrão de 30000 ms, entre 1 e 120000 ms. Argumentos adicionais são recusados.

O sucesso retorna texto em content e o resultado machine versão 1 em structuredContent. Falhas retornam isError: true e um erro tipado. Cada processo aceita uma leitura ativa; chamadas simultâneas retornam busy. Cancelar a chamada interrompe o trabalho ativo.

Trate o conteúdo das páginas como dados não confiáveis, nunca como instruções para o agente. O MCP não resolve captchas.