Documentación de la API de StoryLenses

StoryLenses ofrece generación de cartas de presentación impulsada por IA a través de 5 herramientas MCP componibles y endpoints REST. Crea agentes de carrera, bots de solicitud de empleo o integra cartas de presentación narrativas en tu plataforma.

URL base para todos los endpoints REST:

https://www.storylenses.app/api

Autenticación

Todas las solicitudes autenticadas utilizan autenticación Bearer token con una API key de StoryLenses. Algunos endpoints (como el análisis de ofertas) funcionan sin clave, pero con límites de tasa más estrictos.

Formato de la clave

Las API keys usan el prefijo sl_live_ seguido de 32 caracteres alfanuméricos:

sl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Uso

Incluye tu clave en el encabezado Authorization:

Authorization: Bearer sl_live_YOUR_API_KEY

Obtén tu API key desde el Portal de Desarrolladores

Inicio rápido

Comienza en menos de 2 minutos. Elige tu cliente y pega la configuración.

{
  "mcpServers": {
    "storylenses": {
      "url": "https://mcp.storylenses.app/sse",
      "headers": {
        "Authorization": "Bearer sl_live_YOUR_API_KEY"
      }
    }
  }
}

{
  "mcp": {
    "servers": {
      "storylenses": {
        "url": "https://mcp.storylenses.app/sse",
        "headers": {
          "Authorization": "Bearer sl_live_YOUR_API_KEY"
        }
      }
    }
  }
}

curl -X POST https://www.storylenses.app/api/analyze-job-description \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sl_live_YOUR_API_KEY" \
  -d '{
    "jobDescription": "Senior Frontend Engineer at Stripe...",
    "locale": "en"
  }'

Integración MCP

StoryLenses soporta los transportes Stdio y HTTP para clientes MCP. Usa el que mejor se adapte a tu arquitectura.

Transporte Stdio (npm)

Instala y ejecuta vía npx — ideal para agentes locales y herramientas CLI:

npx -y @storylenses/mcp-server

Configura estas variables de entorno:

STORYLENSES_API_KEY=sl_live_YOUR_API_KEY
STORYLENSES_API_URL=https://www.storylenses.app

Transporte HTTP (Streamable HTTP)

Envía solicitudes JSON-RPC 2.0 directamente — ideal para agentes en la nube e integraciones del lado del servidor:

POST https://www.storylenses.app/api/mcp/endpoint
Content-Type: application/json
Authorization: Bearer sl_live_YOUR_API_KEY

Métodos soportados

El endpoint MCP soporta los siguientes métodos JSON-RPC:

Referencia de herramientas

Las 5 herramientas disponibles a través del protocolo MCP. Los esquemas de parámetros se obtienen directamente de las definiciones de las herramientas.

REST API

Endpoints HTTP directos para cuando no necesitas el protocolo MCP completo. Misma lógica subyacente que las herramientas MCP.

{ "status": "ok" }

Errores y límites de tasa

Todos los errores siguen un formato consistente. Los límites de tasa se aplican por IP para solicitudes no autenticadas y por API key para solicitudes autenticadas.

Códigos de estado HTTP

Formato de respuesta de error

{
  "error": "Human-readable error message"
}

Límites de tasa

Los límites de tasa varían según el endpoint y el método de autenticación. Los usuarios con API key obtienen límites más altos según su plan.

Ejemplos de código

Ejemplos completos, listos para copiar y pegar, para patrones de integración comunes.

TypeScript — Flujo MCP completo

Generación de carta de presentación de extremo a extremo usando el SDK MCP:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

// Connect to StoryLenses MCP
const transport = new SSEClientTransport(
  new URL("https://mcp.storylenses.app/sse"),
  { requestInit: { headers: { Authorization: "Bearer sl_live_YOUR_API_KEY" } } }
);
const client = new Client({ name: "my-agent", version: "1.0" });
await client.connect(transport);

// 1. Analyze the job posting
const jobResult = await client.callTool({
  name: "storylenses_analyze_job",
  arguments: { job_url: "https://linkedin.com/jobs/view/12345" }
});
const jobAnalysis = JSON.parse(jobResult.content[0].text);

// 2. Match candidate profile
const matchResult = await client.callTool({
  name: "storylenses_match_profile",
  arguments: {
    job_analysis: jobAnalysis,
    candidate_cv: "Jane Doe — 8 years frontend, React, TypeScript..."
  }
});
const matchData = JSON.parse(matchResult.content[0].text);

// 3. Generate cover letter
const letterResult = await client.callTool({
  name: "storylenses_generate_letter",
  arguments: {
    job_analysis: jobAnalysis,
    match_data: matchData,
    candidate_name: "Jane Doe",
    archetype: matchData.suggested_archetype || "golden-fleece",
    tone: "professional",
    length: "medium"
  }
});
const letter = JSON.parse(letterResult.content[0].text);

// 4. Quality check
const scoreResult = await client.callTool({
  name: "storylenses_quality_check",
  arguments: {
    letter_text: letter.letter_text,
    job_analysis: jobAnalysis
  }
});
const score = JSON.parse(scoreResult.content[0].text);

console.log(letter.letter_text);   // Story-driven cover letter
console.log(score.overall_score);  // 87/100

cURL — Solicitudes JSON-RPC

Inicializa, lista herramientas y ejecuta una herramienta vía el endpoint HTTP:

# Initialize MCP session
curl -X POST https://www.storylenses.app/api/mcp/endpoint \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sl_live_YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "1.0" }
    }
  }'

# List available tools
curl -X POST https://www.storylenses.app/api/mcp/endpoint \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sl_live_YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

# Call a tool
curl -X POST https://www.storylenses.app/api/mcp/endpoint \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sl_live_YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "storylenses_analyze_job",
      "arguments": {
        "job_url": "https://linkedin.com/jobs/view/12345",
        "locale": "en"
      }
    }
  }'

Python — REST API

Usando httpx para llamar a los endpoints REST directamente:

import httpx

API_KEY = "sl_live_YOUR_API_KEY"
BASE = "https://www.storylenses.app/api"

# Analyze a job posting
resp = httpx.post(
    f"{BASE}/analyze-job-description",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"jobDescription": "Senior Engineer at Acme...", "locale": "en"}
)
job = resp.json()

# Evaluate a cover letter
resp = httpx.post(
    f"{BASE}/evaluate-letter",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "letterText": "Dear Hiring Manager, ...",
        "jobAnalysis": job,
        "locale": "en"
    }
)
score = resp.json()
print(f"Score: {score['overall_score']}/100")

Planes y facturación

Todos los planes incluyen acceso a las 5 herramientas en los 4 idiomas. Solo la generación de cartas de presentación cuenta para tu límite de uso.

Soporte

¿Necesitas ayuda con la integración? Aquí tienes los mejores recursos para empezar.

Para soporte técnico, escribe a support@storylenses.app