Usar Kensa

Guía práctica para crear una cuenta y usar la API, el CLI y MCP.

1. Crear una cuenta con Google

Kensa admite inicio de sesión con Google (OIDC). Al iniciar sesión por primera vez se crea una cuenta y se le otorgan créditos de prueba (OAUTH_TRIAL_CREDITS, 50 por defecto); la cuenta queda vinculada a tu identidad de Google y cada inicio posterior devuelve la misma cuenta.

El flujo es un "authorization code" con verificación local del id_token (RS256 contra las claves de Google). No se guarda una contraseña de Google. Kensa conserva el identificador de Google, el nombre/correo del perfil y el hash de la clave de API. El flujo usa cookie de diez minutos, PKCE y nonce, y funciona entre instancias.

2. Clave de API y saldo

Todas las operaciones autentican con la cabecera Authorization: Bearer kns_live_…. La clave se obtiene al iniciar sesión con Google (o desde la consola de administración local).

curl https://kensa-api-5bvrdyse2a-uc.a.run.app/v1/usage -H "Authorization: Bearer $KENSA_API_KEY"

/v1/usage devuelve credits (saldo disponible), credits_reserved (reservados por trabajos en curso) y el desglose por proyecto/sesión.

Tarifas de créditos

Fast devuelve la reserva si queda parcial, vacío o falla. Deep cobra solo con ≥75% de secciones completas con texto; en otro caso devuelve la reserva. Las búsquedas que terminan sin fuentes devuelven la reserva completa.

3. API REST

Base: https://kensa-api-5bvrdyse2a-uc.a.run.app.

Búsqueda

curl https://kensa-api-5bvrdyse2a-uc.a.run.app/v1/search \
  -H "Authorization: Bearer $KENSA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ejemplo-001" \
  -d '{"query":"Cómo medir el ROI del marketing digital","depth":"advanced","domain":"general","max_results":5,"include_answer":true}'

• depth: basic | advanced.
• domain: auto | general | technology | science_health | economy_legal | culture | news.
• include_answer: sintetiza una respuesta con las fuentes.
• Respuesta: sources[], search_diagnostics (rechazos, fallos de lectura, funnel), indexing_queued y credits_charged.

Extracción

curl https://kensa-api-5bvrdyse2a-uc.a.run.app/v1/extract \
  -H "Authorization: Bearer $KENSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.org/doc","https://example.org/paper.pdf"]}'

Devuelve results[] con status (ok/failed), markdown y truncated. Acepta HTML y PDF.

Investigación

curl https://kensa-api-5bvrdyse2a-uc.a.run.app/v1/research \
  -H "Authorization: Bearer $KENSA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: research-001" \
  -d '{"query":"¿Qué canales de marketing digital generan más retorno para una pyme?","domain":"general","mode":"deep"}'

Devuelve interaction_id. Luego:

curl https://kensa-api-5bvrdyse2a-uc.a.run.app/v1/research/INTERACTION_ID -H "Authorization: Bearer $KENSA_API_KEY"

• mode: basic (Fast, una ronda) | deep (planificación y hasta 4 secciones).
• Eventos SSE: GET /v1/research/INTERACTION_ID/events con Last-Event-ID.

4. CLI

export KENSA_API_KEY="kns_live_…"
export KENSA_BASE_URL="https://kensa-api-5bvrdyse2a-uc.a.run.app"
node packages/cli/dist/main.js search "pregunta" --depth advanced --answer --json
node packages/cli/dist/main.js extract https://example.org/doc
node packages/cli/dist/main.js research "pregunta" --mode deep --output informe.md
node packages/cli/dist/main.js usage

La CLI no sobrescribe archivos existentes y envía el progreso a stderr. Consulta --help para todas las opciones.

5. MCP

Conecta un cliente que soporte Streamable HTTP con cabecera Bearer manual:

{
  "mcpServers": {
    "kensa": {
      "url": "https://kensa-api-5bvrdyse2a-uc.a.run.app/mcp",
      "headers": { "Authorization": "Bearer YOUR_KENSA_API_KEY" }
    }
  }
}

Herramientas disponibles:

• kensa_quick_search — búsqueda rápida con fuentes.
• kensa_extract_urls — extrae varias URLs a Markdown.
• kensa_deep_research — inicia con query o recupera con interaction_id.

6. Demo

Abre la demo e inicia sesión con Google para ver tu saldo y probar una búsqueda. La clave de tu cuenta se conserva durante la sesión de esa pestaña.