# ExploriGen para desenvolvedores (developer documentation)

> Documentação (documentation) das superfícies para agentes e desenvolvedores (developers) de explorigen.io: dois servidores MCP, API REST v1 com autenticação de agentes (agent auth) e sandbox (test mode), busca /ask (NLWeb), OpenAPI 3.1, skills e catálogos. Tudo somente leitura (read-only) e sem pacote para instalar: só HTTP.

Índice raiz: https://explorigen.io/llms.txt. Vista completa com início rápido (quickstart): https://explorigen.io/agentes (também em /?mode=agent, /developers e /docs).

## Início rápido (quickstart)

Sem token, agora:

- GET https://explorigen.io/api — índice público da API: endpoints, escopos, política de versão.
- GET https://explorigen.io/api/v1/sandbox/precos — a mesma forma da v1, dados fixos, sem token (sandbox).
- POST https://explorigen.io/mcp com `{"jsonrpc":"2.0","id":1,"method":"tools/list"}` — as ferramentas do produto.
- POST https://explorigen.io/ask com `{"query":{"text":"seo local"}}` — busca lexical (keyword search) nas páginas.

Com token (duas chamadas, sem conta — self-serve API key): POST https://explorigen.io/agent/identity com `{"type":"anonymous"}`, depois POST https://explorigen.io/agent/token com `grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=<identity_assertion>`, e então `Authorization: Bearer <access_token>` em GET https://explorigen.io/api/v1/busca?q=seo. O roteiro inteiro, com erros e limites: [auth.md](https://explorigen.io/auth.md).

## MCP (Model Context Protocol)

Dois servidores, JSON-RPC 2.0 sobre HTTP (Streamable HTTP, sem sessão, sem stream do servidor para o cliente), sem autenticação:

- Produto: POST https://explorigen.io/mcp — ferramentas get_readiness_score, search_site, get_page, list_services, get_pricing, how_to_hire; recursos explorigen://catalogo e explorigen://precos. Cartão: server-card.json — https://explorigen.io/.well-known/mcp/server-card.json.
- Documentação (docs): POST https://explorigen.io/mcp/docs — ferramentas list_docs, get_doc, search_docs, get_llms_txt; um recurso explorigen://docs/<rota> por página e explorigen://docs/llms.txt. Cartão: docs/server-card.json — https://explorigen.io/.well-known/mcp/docs/server-card.json.
- Manifesto com os dois servidores — https://explorigen.io/.well-known/mcp.json — o mesmo objeto responde em https://explorigen.io/.well-known/mcp (GET), que também aceita POST JSON-RPC do produto.
- Cliente: `{"type":"http","url":"https://explorigen.io/mcp"}`. Método `initialize` devolve protocolVersion 2025-06-18; `GET` nesses caminhos responde 405.

## API REST v1

- Índice público — https://explorigen.io/api (GET, 200 sem token).
- Política de versão e de depreciação (versioning and deprecation policy): a
  versão vai no caminho, /api/v1/. Mudança incompatível nasce em /api/v2/, e a
  v1 continua no ar por pelo menos 90 dias depois do aviso. O aviso vem nos
  cabeçalhos Deprecation e Sunset (RFC 9745 e RFC 8594) das respostas da rota
  que sai, e nesta página. Hoje nada está depreciado: nenhuma resposta carrega
  esses cabeçalhos, e a v1 não tem data de fim.
- Rotas (GET, bearer obrigatório, 401 com WWW-Authenticate sem ele): https://explorigen.io/api/v1/ (índice), https://explorigen.io/api/v1/paginas (paginação por limite/cursor/total/proximo), https://explorigen.io/api/v1/paginas/<rota> (markdown de uma página do índice), https://explorigen.io/api/v1/busca?q= (busca lexical), https://explorigen.io/api/v1/solucoes, https://explorigen.io/api/v1/precos, https://explorigen.io/api/v1/prontidao/<dominio> (escopo prontidao.read; leitura gravada, nunca mede).
- Escopos: site.read — ler páginas, busca e catálogo (read pages, search, catalog); prontidao.read — consultar leituras de prontidão gravadas (read recorded readiness scores).
- Autenticação: [auth.md](https://explorigen.io/auth.md); registro anônimo em POST https://explorigen.io/agent/identity, troca em POST https://explorigen.io/agent/token. Metadata: recurso protegido (RFC 9728) — https://explorigen.io/.well-known/oauth-protected-resource e servidor de autorização (RFC 8414) — https://explorigen.io/.well-known/oauth-authorization-server.
- Sandbox (test mode), sem token, dados fixos, nunca toca armazenamento nem o instrumento: páginas — https://explorigen.io/api/v1/sandbox/paginas, busca — https://explorigen.io/api/v1/sandbox/busca?q=seo, soluções — https://explorigen.io/api/v1/sandbox/solucoes, preços — https://explorigen.io/api/v1/sandbox/precos, prontidão — https://explorigen.io/api/v1/sandbox/prontidao/explorigen.io.
- Erros sempre em JSON: `{ "error", "error_description" }`. Limite de corpo 64 KB (413). Sem cabeçalhos RateLimit-*: não há limitador por agente; o único portão é o do instrumento de leitura (503/429 com Retry-After).

## Busca em linguagem natural (NLWeb)

- POST https://explorigen.io/ask com `{"query":{"text":"..."}}` (também `{"query":"..."}`) ou GET https://explorigen.io/ask?query=...&streaming=false. Resposta NLWeb 0.55: `_meta.response_type` list, `results[]` de WebPage com `schema_object`, `summary`.
- SSE com `prefer.streaming: true`, `streaming=true` ou `Accept: text/event-stream`: eventos start, result, complete, done.
- É busca lexical (keyword search) sobre o índice das páginas, sem modelo de linguagem.

## Descrições, catálogos e descoberta

- OpenAPI 3.1 — https://explorigen.io/api/openapi.json — toda operação com operationId, toda resposta com esquema. Redirecionamento permanente de /openapi.json.
- Catálogo de APIs (RFC 9727) — https://explorigen.io/.well-known/api-catalog — content-type application/linkset+json.
- Cartão A2A — https://explorigen.io/.well-known/agent-card.json — identidade, contato e as ferramentas como skills; não há endpoint A2A JSON-RPC nem agente autônomo.
- Índice de skills (Agent Skills v0.2.0) — https://explorigen.io/.well-known/agent-skills/index.json — SKILL.md com digest sha256.
- Catálogo para agentes — https://explorigen.io/agentes/catalogo.json — marca, produtos, preços, soluções, artigos, páginas com lastmod, FAQ, caminhos e ferramentas num JSON. Índice de busca — https://explorigen.io/agentes/indice.json — as páginas com texto.
- [Preços (pricing)](https://explorigen.io/pricing.md) — markdown.
- Schema Map (NLWeb) — https://explorigen.io/schemamap.xml e feeds JSON Lines: soluções — https://explorigen.io/feeds/solucoes.jsonl, artigos — https://explorigen.io/feeds/artigos.jsonl.
- Diretório de chaves Web Bot Auth (RFC 9421) — https://explorigen.io/.well-known/http-message-signatures-directory — chave publicada; nenhuma requisição é assinada ainda (o próprio documento diz).
- ARD / ai-catalog — https://explorigen.io/.well-known/ard.json e sitemap — https://explorigen.io/sitemap.xml com lastmod.
- WebMCP: as cinco ferramentas em /webmcp.js — https://explorigen.io/webmcp.js, registradas em document.modelContext em toda página; formulário com toolname em https://explorigen.io/diagnostico-de-visibilidade-cognitiva.

## Markdown por rota

Toda página responde em markdown: acrescente .md ao caminho ([exemplo](https://explorigen.io/solucoes/seo-tecnico.md); a home é https://explorigen.io/index.md) ou peça `Accept: text/markdown` (Vary: Accept). Bots de IA identificados pelo User-Agent recebem o markdown mesmo pedindo HTML. Rota inexistente responde 404 com corpo markdown curto e links de recuperação.

## Índices por seção

- Soluções — https://explorigen.io/solucoes/llms.txt · Blog — https://explorigen.io/blog/llms.txt · Diagnóstico e preços — https://explorigen.io/diagnostico-de-visibilidade/llms.txt