Documentação da API StoryLenses

O StoryLenses oferece geração de cartas de apresentação com IA por meio de 5 ferramentas MCP compostas e endpoints REST. Crie agentes de carreira, bots de candidatura a emprego ou integre cartas de apresentação baseadas em narrativas à sua plataforma.

URL base para todos os endpoints REST:

https://www.storylenses.app/api

Autenticação

Todas as requisições autenticadas usam autenticação Bearer token com uma API key do StoryLenses. Alguns endpoints (como análise de vaga) funcionam sem chave, porém com limites de taxa mais restritos.

Formato da Chave

As API keys usam o prefixo sl_live_ seguido de 32 caracteres alfanuméricos:

sl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Uso

Inclua sua chave no header Authorization:

Authorization: Bearer sl_live_YOUR_API_KEY

Obtenha sua API key no Portal do Desenvolvedor

Início Rápido

Comece em menos de 2 minutos. Escolha seu cliente e cole a configuração.

{
  "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"
  }'

Integração MCP

O StoryLenses suporta transportes Stdio e HTTP para clientes MCP. Use o que melhor se adaptar à sua arquitetura.

Transporte Stdio (npm)

Instale e execute via npx — ideal para agentes locais e ferramentas CLI:

npx -y @storylenses/mcp-server

Defina estas variáveis de ambiente:

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

Transporte HTTP (Streamable HTTP)

Envie requisições JSON-RPC 2.0 diretamente — ideal para agentes hospedados na nuvem e integrações server-side:

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

Métodos Suportados

O endpoint MCP suporta os seguintes métodos JSON-RPC:

Referência de Ferramentas

Todas as 5 ferramentas disponíveis através do protocolo MCP. Os schemas de parâmetros são extraídos diretamente das definições das ferramentas.

REST API

Endpoints HTTP diretos para quando você não precisa do protocolo MCP completo. Mesma lógica subjacente das ferramentas MCP.

{ "status": "ok" }

Erros e Limites de Taxa

Todos os erros seguem um formato consistente. Limites de taxa são aplicados por IP para requisições não autenticadas e por API key para requisições autenticadas.

Códigos de Status HTTP

Formato de Resposta de Erro

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

Limites de Taxa

Os limites de taxa variam por endpoint e método de autenticação. Usuários com API key recebem limites maiores de acordo com seu plano.

Exemplos de Código

Exemplos completos, prontos para copiar e colar, para padrões comuns de integração.

TypeScript — Fluxo MCP Completo

Geração de carta de apresentação de ponta a ponta usando o MCP SDK:

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 — Requisições JSON-RPC

Inicializar, listar ferramentas e chamar uma ferramenta via 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 chamar os endpoints REST diretamente:

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")

Planos e Cobrança

Todos os planos incluem acesso a todas as 5 ferramentas em todos os 4 idiomas. Apenas a geração de carta de apresentação conta para o seu limite de uso.

Suporte

Precisa de ajuda com a integração? Aqui estão os melhores lugares para começar.

Para suporte técnico, envie e-mail para support@storylenses.app