StoryLenses API-Dokumentation

StoryLenses bietet KI-gestützte Anschreiben-Generierung über 5 kombinierbare MCP Tools und REST-Endpunkte. Erstelle Karriere-Agenten, Bewerbungs-Bots oder integriere story-basierte Anschreiben in deine Plattform.

Basis-URL für alle REST-Endpunkte:

https://www.storylenses.app/api

Authentifizierung

Alle authentifizierten Anfragen verwenden Bearer-Token-Authentifizierung mit einem StoryLenses API Key. Einige Endpunkte (wie die Stellenanalyse) funktionieren ohne Key, aber mit strengeren Rate Limits.

Key-Format

API Keys verwenden das Präfix sl_live_ gefolgt von 32 alphanumerischen Zeichen:

sl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Verwendung

Füge deinen Key im Authorization-Header ein:

Authorization: Bearer sl_live_YOUR_API_KEY

Hole deinen API Key im Entwicklerportal

Schnellstart

Starte in unter 2 Minuten. Wähle deinen Client und füge die Konfiguration ein.

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

MCP-Integration

StoryLenses unterstützt sowohl Stdio- als auch HTTP-Transport für MCP-Clients. Verwende den, der zu deiner Architektur passt.

Stdio-Transport (npm)

Installation und Ausführung über npx — ideal für lokale Agenten und CLI-Tools:

npx -y @storylenses/mcp-server

Setze diese Umgebungsvariablen:

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

HTTP-Transport (Streamable HTTP)

Sende JSON-RPC 2.0-Anfragen direkt — ideal für Cloud-gehostete Agenten und serverseitige Integrationen:

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

Unterstützte Methoden

Der MCP-Endpunkt unterstützt die folgenden JSON-RPC-Methoden:

Tools-Referenz

Alle 5 Tools, die über das MCP-Protokoll verfügbar sind. Parameter-Schemas werden direkt aus den Tool-Definitionen übernommen.

REST API

Direkte HTTP-Endpunkte für den Fall, dass du nicht das vollständige MCP-Protokoll benötigst. Dieselbe zugrunde liegende Logik wie die MCP Tools.

{ "status": "ok" }

Fehler & Rate Limits

Alle Fehler folgen einem einheitlichen Format. Rate Limits werden pro IP für nicht authentifizierte Anfragen und pro API Key für authentifizierte Anfragen angewandt.

HTTP-Statuscodes

Fehlerantwort-Format

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

Rate Limits

Rate Limits variieren je nach Endpunkt und Authentifizierungsmethode. API-Key-Nutzer erhalten höhere Limits basierend auf ihrem Tarif.

Code-Beispiele

Vollständige, kopierbare Beispiele für gängige Integrationsmuster.

TypeScript — Vollständiger MCP-Workflow

Ende-zu-Ende Anschreiben-Generierung mit dem 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 — JSON-RPC-Anfragen

Initialisieren, Tools auflisten und ein Tool über den HTTP-Endpunkt aufrufen:

# 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

Mit httpx die REST-Endpunkte direkt aufrufen:

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

Tarife & Abrechnung

Alle Tarife beinhalten Zugang zu allen 5 Tools in allen 4 Sprachen. Nur die Anschreiben-Generierung zählt zum Nutzungslimit.

Support

Brauchst du Hilfe bei der Integration? Hier sind die besten Anlaufstellen.

Für technischen Support, schreibe eine E-Mail an support@storylenses.app