Strukturierte Daten und Intelligence Tokens

15 Min Lesezeit

TLDR

Jeder Surmado-Bericht enthält strukturiertes JSON für den programmatischen Zugriff. AI-Visibility-Tokens enthalten Sichtbarkeitskennzahlen und Wettbewerberdaten. Site-Audit-Tokens enthalten Performance-Werte und technische Probleme. Strategy-Tokens enthalten strategische Empfehlungen und Finanzmodelle. Binden Sie Notion, Airtable, Google Sheets, Zapier oder eigene Tools an. Verfolgen Sie Kennzahlen im Zeitverlauf, automatisieren Sie Berichte, bauen Sie Berichtsansichten oder lösen Sie Warnungen aus, wenn die Sichtbarkeit sinkt.

Sie suchen die REST-API? Im API-Integrationsleitfaden erfahren Sie, wie Sie Berichte erstellen, Marken verwalten und Webhooks programmatisch empfangen.

Jeder Surmado-Bericht enthält strukturiertes JSON für den programmatischen Zugriff.

Was sind Intelligence Tokens?

Intelligence Tokens sind eindeutige Kennungen für jeden abgeschlossenen Bericht (z. B. SIG-2025-11-A7K3Q). Der Token wird in der REST-API-Antwort zurückgegeben, wenn ein Bericht fertig ist. Bei Berichten zu AI Visibility und Site Audit schaltet er eine strukturierte public_intelligence-JSON-Nutzlast frei, die Sie einbinden können in:

Berichtsansichten (Notion, Airtable, Retool, eigene React-Apps)
Automatisierungs-Workflows (Zapier, Make, n8n)
Interne Tools (CRMs, Projektmanagement, BI-Plattformen)
Eigene Agenten (KI-Assistenten, Monitoring-Bots, Slack-Integrationen)

Wo Sie sie finden: Rufen Sie GET /v1/reports/{report_id} auf, sobald Ihr Bericht completed ist. Antworten zu AI Visibility und Site Audit enthalten ein public_intelligence-Objekt mit aufbereiteten, maschinenlesbaren Feldern. Strategy-Berichte geben den Token bei Abschluss zurück, stellen public_intelligence aber derzeit nicht bereit. Nutzen Sie für die Strategy-Ausgabe das erzeugte PDF. Authentifizierung und Endpunkte finden Sie im API-Integrationsleitfaden.

Format: Standard-JSON. Es können im Lauf der Zeit Felder hinzukommen, wir wollen bestehende Felder aber stabil halten.

Intelligence Token für AI Visibility

Token-Präfix: SIG-* (Produkt-Slug in API-Pfaden: signal) Zweck: Kennzahlen zur KI-Sichtbarkeit, Wettbewerbspositionierung und Messung von Ghost Influence.

Schemastruktur (AI Visibility)

{
  "token": "SIG-2025-11-A7K3Q",
  "schema_type": "signal",
  "generated_at": "2025-11-08T23:45:12.456789+00:00",
  "summary": {
    "business_name": "Acme Coffee Roasters",
    "industry": "Food & Beverage",
    "location": "Portland, OR",
    "presence_score": 34.2,
    "authority_score": 42.7,
    "competitive_rank": 4,
    "total_competitors": 12,
    "top_competitor": "Blue Bottle",
    "insights_summary": [
      "Presence score: 34.2 (↑5.5 from last report)",
      "Ghost influence: 48.3% of relevant mentions don't name you",
      "Competitive rank: #4 of 12 in category"
    ]
  },
  "data": {
    "entity_context": {
      "entity_name": "Acme Coffee Roasters",
      "category": "Food & Beverage",
      "location": "Portland, OR",
      "value_proposition": "Single-origin, small-batch specialty coffee",
      "competitive_set": ["Starbucks", "Blue Bottle", "Intelligentsia"]
    },
    "visibility_metrics": {
      "presence_score": 34.2,
      "ghost_influence_percentage": 48.3,
      "attributed_mentions": 12,
      "unattributed_mentions": 17,
      "category_share": 8.1
    },
    "competitive_position": {
      "rank": 4,
      "total_competitors": 12,
      "tier": "challenger",
      "top_competitor": "Blue Bottle"
    },
    "platform_variance": {
      "chatgpt": {
        "presence_score": 42.1,
        "attributed_mentions": 5,
        "unattributed_mentions": 7,
        "sample_responses": ["..."]
      },
      "claude": {
        "presence_score": 38.5,
        "attributed_mentions": 3,
        "unattributed_mentions": 4
      },
      "gemini": { "...": "..." },
      "deepseek": { "...": "..." },
      "meta_ai": { "...": "..." },
      "grok": { "...": "..." }
    },
    "perception_analysis": {
      "primary_associations": ["specialty coffee", "local roasting", "sustainable sourcing"],
      "sentiment_distribution": {
        "positive": 67.4,
        "neutral": 28.3,
        "negative": 4.3
      },
      "strength_signals": ["ethical sourcing", "small batch quality"],
      "weakness_signals": ["limited retail presence", "higher price point"]
    },
    "strategic_signals": {
      "visibility_opportunities": [
        {
          "platform": "chatgpt",
          "gap": "Location-based queries underrepresented",
          "recommendation": "Optimize Google Business Profile with neighborhood keywords",
          "estimated_impact": "high"
        }
      ],
      "competitive_threats": [
        {
          "competitor": "Blue Bottle",
          "platform": "claude",
          "advantage": "Brand recognition in 'premium coffee' queries",
          "mitigation": "Emphasize direct trade relationships and roast-date freshness"
        }
      ]
    },
    "evidence_samples": [
      {
        "platform": "chatgpt",
        "query": "best specialty coffee roasters in Portland",
        "response_excerpt": "...",
        "attribution_type": "named",
        "rank": 3
      }
    ],
    "market_context": {
      "industry_trends": ["direct trade transparency", "micro-lot offerings"],
      "seasonal_factors": "Testing conducted during peak holiday gifting season",
      "competitive_intensity": "high",
      "total_competitors_found": 12
    },
    "baseline_metrics": {
      "previous_presence_score": 28.7,
      "change_since_last_report": "+5.5",
      "trend": "improving",
      "authority_score": 42.7
    },
    "preview_content": {
      "tldr_bullets_list": [
        "Presence score: 34.2 (↑5.5 from last report)",
        "Ghost influence: 48.3% of relevant mentions don't name you",
        "Competitive rank: #4 of 12 in category",
        "Strongest platform: ChatGPT (42.1 presence)",
        "Top opportunity: Location-based query optimization"
      ]
    }
  }
}

Das aufbereitete summary-Objekt oben wird von der API für den schnellen Zugriff befüllt. Die tieferen Kennzahlen liegen unter data.*. Interne Felder wie persona_details und test_queries stehen auf der Sperrliste und erscheinen nie in public_intelligence.

Wichtige Felder erklärt (AI Visibility)

summary.presence_score (und data.visibility_metrics.presence_score): Wert von 0 bis 100, der misst, wie oft Ihr Unternehmen in KI-Antworten auf relevante Fragen vorkommt. Höher = sichtbarer.

data.visibility_metrics.ghost_influence_percentage: Prozentsatz der relevanten Erwähnungen, in denen die KI Ihr Wertversprechen oder Ihre Leistungen beschreibt, ohne Sie zu nennen. Hoher Ghost Influence = Sie bilden den Markt aus, aber Wettbewerber erhalten die Zuordnung.

summary.competitive_rank (und data.competitive_position.rank): Ihre Position im Vergleich zu Wettbewerbern in derselben Kategorie. Rang 1 = am häufigsten erwähnt.

data.platform_variance: Aufschlüsselung nach KI-Plattform (ChatGPT, Claude, Gemini usw.), die zeigt, wo Sie am stärksten und am schwächsten sind.

data.strategic_signals.visibility_opportunities: Umsetzbare Empfehlungen, nach geschätzter Wirkung geordnet.

Häufige Anwendungsfälle (AI Visibility)

Integration in Berichtsansichten: Ziehen Sie summary.presence_score, data.visibility_metrics.ghost_influence_percentage und summary.competitive_rank, um die KI-Sichtbarkeit im Zeitverlauf zu verfolgen.

Warnungen: Beobachten Sie data.baseline_metrics.trend und lösen Sie Warnungen aus, wenn der Presence Score um mehr als 10 Punkte fällt.

Wettbewerbsanalyse: Vergleichen Sie Ihre data.platform_variance mit den AI-Visibility-Berichten von Wettbewerbern, um plattformspezifische Lücken zu finden.

Content-Strategie: Nutzen Sie data.perception_analysis.weakness_signals, um die Inhaltserstellung und die FAQ-Optimierung zu steuern.

Intelligence Token für Site Audit

Token-Präfix: SCN-* (Produkt-Slug in API-Pfaden: scan) Zweck: Daten zum technischen SEO-Audit, Performance-Kennzahlen, Barrierefreiheitswerte und priorisierte Maßnahmen.

Schemastruktur (Site Audit)

{
  "schema_type": "scan",
  "scan_schema_types_count": 3,
  "scan_critical_issues_count": 8,
  "summary": {
    "seo_score": 95,
    "performance_score": 87,
    "accessibility_score": 92,
    "total_pages": 48,
    "schema_types_count": 3,
    "critical_issues_count": 8,
    "content_coverage_percentage": 87,
    "page_analysis_summary": "Homepage LCP is 2.8s (above target). Three pages have thin content.",
    "link_analysis_summary": "Internal link distribution uneven. Two orphaned pages detected.",
    "schema_strategy_summary": "FAQPage and LocalBusiness schemas missing on key pages.",
    "content_gaps_summary": "Competitors rank for brewing method and single-origin guides you don't cover.",
    "quick_wins": {
      "link_analysis": "Add internal links from homepage to two orphaned product pages.",
      "schema_strategy": "Add FAQPage schema to the top 5 traffic pages.",
      "content_gaps": "Publish a brewing-methods comparison guide."
    }
  },
  "data": {
    "metadata": {
      "url": "https://www.example.com",
      "run_id": "scan-20251108-143022",
      "product": "scan",
      "version": "1.0",
      "created_at": "2025-11-08T14:30:22.445Z"
    },
    "audit_data": {
      "site_metrics": {
      "total_pages": 48,
      "crawled_pages": 48,
      "avg_word_count": 1247,
      "pages_with_schema": 42,
      "missing_titles": 0,
      "duplicate_titles": 3,
      "images_without_alt": 15,
      "broken_links": 2,
      "redirect_chains": 1
    },
    "lighthouse": {
      "performance_score": 87,
      "seo_score": 95,
      "accessibility_score": 92,
      "best_practices_score": 88,
      "first_contentful_paint": 1.2,
      "largest_contentful_paint": 2.1,
      "cumulative_layout_shift": 0.05,
      "total_blocking_time": 150
    },
    "accessibility": {
      "pa11y_errors": 8,
      "pa11y_warnings": 23,
      "combined_score": 86,
      "critical_issues": [
        {
          "code": "WCAG2AA.Principle1.Guideline1_3.1_3_1.H49.I",
          "message": "<i> element used for icon, should use aria-label",
          "selector": ".nav-icon",
          "impact": "moderate"
        }
      ]
    },
    "enrichment": {
      "page_analysis": {
        "high_priority_pages": [
          {
            "url": "/",
            "title": "Homepage",
            "recommendations": [
              "Add FAQ schema to address common queries",
              "Optimize hero image LCP (currently 2.8s)"
            ]
          }
        ]
      },
      "link_analysis": {
        "internal_link_distribution": "uneven",
        "orphaned_pages": 2,
        "deep_pages_low_authority": 5
      },
      "schema_strategist": {
        "schemas_found": ["Organization", "WebSite", "BreadcrumbList"],
        "schemas_missing": ["FAQPage", "LocalBusiness"],
        "validation_errors": [
          {
            "type": "Organization",
            "field": "logo",
            "error": "Invalid URL format"
          }
        ]
      },
      "content_inventory": {
        "thin_content_pages": 3,
        "keyword_cannibalization": [
          {
            "keyword": "best coffee beans",
            "competing_pages": ["/shop/beans", "/blog/coffee-guide"],
            "recommendation": "Consolidate or differentiate targeting"
          }
        ]
      },
      "competitor_analysis": {
        "competitors_analyzed": ["bluebottle.com", "intelligentsia.com"],
        "your_advantages": ["Faster load times", "Better mobile UX"],
        "their_advantages": ["more thorough with 150+ checks schema", "Higher blog frequency"]
      },
      "upstream_research": {
        "industry_benchmarks": {
          "avg_performance_score": 72,
          "avg_accessibility_score": 78,
          "your_vs_average": {
            "performance": "+15",
            "accessibility": "+14"
          }
        }
      },
      "content_gap_analysis": {
        "suggested_topics": [
          "Coffee brewing methods comparison",
          "Single-origin vs blend guide",
          "Roast profile differences explained"
        ],
        "rationale": "Competitors rank for these queries but you have no content"
      }
    },
    "pages": [
      {
        "url": "https://www.example.com/",
        "title": "Homepage",
        "status_code": 200,
        "word_count": 1850,
        "meta_description": "...",
        "h1_tags": ["Acme Coffee Roasters"],
        "schema_types": ["Organization", "WebSite"],
        "performance": {
          "lcp": 2.1,
          "cls": 0.05
        },
        "issues": [
          {
            "severity": "medium",
            "type": "image_optimization",
            "message": "Hero image not lazy-loaded",
            "recommendation": "Add loading='lazy' attribute"
          }
        ]
      }
    ]
    }
  }
}

summary ist die aufbereitete Zusammenfassung, die Kunden für die Automatisierung nutzen. Tiefere Daten liegen unter data.audit_data.*. Das vollständige Array audit_data.pages[] ist in der public_intelligence-Antwort enthalten, aber lang. Greifen Sie auf summary.quick_wins zu, um die wichtigsten priorisierten Empfehlungen zu erhalten.

Wichtige Felder erklärt (Site Audit)

summary.seo_score (und data.audit_data.site_metrics.seo_score): SEO-Wert von 0 bis 100, der technische Faktoren und Faktoren auf der Seite zusammenfasst.

summary.performance_score (und data.audit_data.lighthouse.performance_score): Lighthouse-Performance-Wert von 0 bis 100. Branchendurchschnitt: 65-75 für E-Commerce-Websites.

data.audit_data.site_metrics.images_without_alt: Anzahl der Bilder ohne Alt-Text (SEO- und Barrierefreiheitsproblem).

data.audit_data.enrichment.schema_strategist: Schema.org-Validierung und Empfehlungen für strukturierte Daten.

data.audit_data.enrichment.content_gap_analysis: Themen, für die Wettbewerber ranken, Sie aber nicht abdecken. SEO-Chancen.

data.audit_data.pages[].issues: Detaillierte Probleme pro Seite mit Schweregrad und umsetzbaren Empfehlungen.

summary.quick_wins: Priorisierte Empfehlungen in einfacher Sprache, nach Bereich geordnet (link_analysis, schema_strategy, content_gaps).

Häufige Anwendungsfälle (Site Audit)

CI/CD-Integration: Führen Sie ein Site Audit in Ihrer Deployment-Pipeline aus und lassen Sie Builds fehlschlagen, wenn summary.performance_score < 80.

Monitoring: Verfolgen Sie summary.seo_score, summary.performance_score und summary.accessibility_score im Zeitverlauf in einer Zeitreihendatenbank.

Issue-Tracking: Werten Sie data.audit_data.pages[].issues aus und legen Sie automatisch Jira-/Linear-Tickets für das Entwicklungsteam an.

Berichtswesen: Ziehen Sie das summary-Objekt für Management-Berichtsansichten zur SEO-Gesundheit.

Intelligence Token für Strategy

Token-Präfix: SOL-* (Produkt-Slug in API-Pfaden: solutions) Zweck: Ergebnisse der strategischen Planung, priorisierte Maßnahmen, Synthese der Streitgespräche zwischen Gegenpositionen und Entscheidungsrahmen.

Strategy-Berichte stellen über die REST-API derzeit kein public_intelligence-Objekt bereit. Die Struktur unten beschreibt, was im erzeugten PDF erscheint, und dient als Referenz. Programmatische Nutzer sollten die PDF-Download-URL verwenden, die der Status-Endpunkt zurückgibt.

Schemastruktur (Strategy)

{
  "token": "SOL-2025-11-A7K3Q",
  "generated_at": "2025-11-08T23:45:12.456789+00:00",
  "business_name": "Acme Coffee Roasters",
  "decision": "Should we expand from local farmers markets to e-commerce?",
  "todo_list": [
    {
      "priority": 1,
      "action": "Validate e-commerce demand with 2-week pre-order test",
      "rationale": "CFO AI flagged cash flow risk of inventory investment. Test market demand before committing capital.",
      "estimated_effort": "1-3 days",
      "impact": "high",
      "owner_role": "Marketing",
      "dependencies": [],
      "success_criteria": "Achieve 50+ pre-orders to justify inventory investment"
    },
    {
      "priority": 2,
      "action": "Calculate true unit economics including shipping costs",
      "rationale": "Market Realist AI noted competitors use free shipping thresholds. Need to model margin impact.",
      "estimated_effort": "1 day",
      "impact": "high",
      "owner_role": "Finance",
      "dependencies": [],
      "success_criteria": "Confirm >30% margin after shipping at $35+ order value"
    },
    {
      "priority": 3,
      "action": "Research coffee subscription platform integrations (Trade, Driftaway)",
      "rationale": "Game Theorist AI suggested partnering vs competing. Explore white-label options.",
      "estimated_effort": "2-3 days",
      "impact": "medium",
      "owner_role": "Partnerships",
      "dependencies": [],
      "success_criteria": "Identify 2-3 viable platform partnerships with <15% commission"
    },
    {
      "priority": 4,
      "action": "Audit fulfillment capacity: Can we ship 100 orders/week?",
      "rationale": "COO AI raised operational risk of overwhelming current team during peak season.",
      "estimated_effort": "1 day",
      "impact": "high",
      "owner_role": "Operations",
      "dependencies": [],
      "success_criteria": "Document current capacity + identify bottlenecks"
    },
    {
      "priority": 5,
      "action": "Create content strategy for 'coffee education' blog",
      "rationale": "Upstream research showed competitors win on educational content. Build SEO moat.",
      "estimated_effort": "1 week",
      "impact": "medium",
      "owner_role": "Marketing",
      "dependencies": [1],
      "success_criteria": "Publish 3 comprehensive guides (brewing methods, origins, roast profiles)"
    },
    {
      "priority": 6,
      "action": "Build Minimum Viable Storefront (Shopify or WooCommerce)",
      "rationale": "After validating demand (Priority 1), launch simple store. Avoid custom dev.",
      "estimated_effort": "2 weeks",
      "impact": "high",
      "owner_role": "Engineering",
      "dependencies": [1, 2],
      "success_criteria": "Live storefront with 5 SKUs, payment processing, shipping integration"
    },
    {
      "priority": 7,
      "action": "Model customer acquisition cost (CAC) for paid ads",
      "rationale": "CFO AI noted farmers market CAC is $0 (foot traffic). Need to budget for online ads.",
      "estimated_effort": "2-3 days",
      "impact": "medium",
      "owner_role": "Marketing",
      "dependencies": [2],
      "success_criteria": "Target CAC <$25 with LTV >$75 (3x ratio)"
    },
    {
      "priority": 8,
      "action": "Set decision checkpoint: Launch vs pivot based on pre-order results",
      "rationale": "Chief Strategist AI synthesis: Use Priority 1 results to decide go/no-go.",
      "estimated_effort": "1 day",
      "impact": "critical",
      "owner_role": "Leadership",
      "dependencies": [1, 2, 4],
      "success_criteria": "Decision made by [specific date] based on pre-order data"
    }
  ],
  "summary": {
    "total_actions": 8,
    "high_priority": 4,
    "medium_priority": 3,
    "critical_priority": 1,
    "has_financial_analysis": true,
    "has_risk_mitigation": true,
    "estimated_total_effort": "4-6 weeks",
    "decision_framework": "Staged validation approach with clear go/no-go gates"
  },
  "adversarial_debate_summary": {
    "cfo_concerns": [
      "Inventory cash flow risk without demand validation",
      "Shipping costs erode margins below 30% threshold",
      "Customer acquisition cost unknown for paid channels"
    ],
    "coo_concerns": [
      "Current team capacity maxed at 100 orders/week",
      "Peak season overlap with farmers market commitments",
      "Fulfillment process not documented or systemized"
    ],
    "market_realist_concerns": [
      "Competitors offer free shipping (you can't at current scale)",
      "Educational content gap vs established brands",
      "Price positioning unclear (premium vs accessible)"
    ],
    "game_theorist_insights": [
      "Partnering with existing platforms reduces upfront investment",
      "Competitors may respond with farmers market presence if you succeed online",
      "First-mover advantage in 'local + online' hybrid model"
    ],
    "chief_strategist_synthesis": "Launch is feasible but only after validating demand and unit economics. Staged approach reduces risk: (1) Pre-order test, (2) MVP storefront, (3) Scale based on results. Avoid premature inventory investment."
  },
  "monte_carlo_scenarios": {
    "methodology": "10,000 simulations varying demand, CAC, and margin assumptions",
    "outcomes": {
      "success_rate": 62,
      "breakeven_12mo": 62,
      "breakeven_18mo": 28,
      "failure_24mo": 10
    },
    "key_risk_factors": [
      "Customer acquisition cost variance (if CAC >$40, failure risk jumps to 35%)",
      "Shipping cost assumptions (free shipping threshold impacts margin by 12-18%)",
      "Fulfillment bottleneck (unable to scale beyond 100 orders/week without hiring)"
    ],
    "recommendation": "Secure 18-month runway, not 12-month. Model includes 28% of scenarios requiring extended breakeven timeline."
  },
  "evidence_citations": [
    {
      "claim": "Competitors use free shipping thresholds",
      "source": "Analysis of Blue Bottle, Intelligentsia, and Stumptown pricing",
      "data": "Free shipping at $40+, $35+, and $50+ respectively"
    },
    {
      "claim": "Educational content drives SEO for coffee brands",
      "source": "SEMrush analysis of top 10 specialty coffee sites",
      "data": "Average 12 educational blog posts ranking for 'how to brew' queries"
    }
  ]
}

Wichtige Felder erklärt (Strategy)

todo_list[].priority: 1 = höchste Priorität. Die Reihenfolge entspricht der logischen Abfolge und den Abhängigkeiten.

todo_list[].dependencies: Array der Prioritätsnummern, von denen diese Maßnahme abhängt. Wird für die Reihenfolge im Projektmanagement genutzt.

adversarial_debate_summary: Verdichtete Übersicht der Bedenken, die jede KI-Perspektive (CFO, COO, Market Realist, Game Theorist) geäußert hat, und der abschließenden Synthese.

monte_carlo_scenarios: Ergebnisse probabilistischer Belastungstests, die die Wahrscheinlichkeit von Erfolg und Misserfolg unter wechselnden Annahmen zeigen.

evidence_citations: Quellen, die zentrale Aussagen und Empfehlungen belegen. Transparenz über die Begründung.

Häufige Anwendungsfälle (Strategy)

public_intelligence für Strategy wird heute nicht über die REST-API bereitgestellt. Die Felder unten beschreiben die PDF-Ausgabe. Programmatische Nutzer sollten aus dem PDF extrahieren oder den zugrunde liegenden Bericht zu AI Visibility / Site Audit erneut ausführen und mit dessen public_intelligence arbeiten.

Projektmanagement: Importieren Sie todo_list mit vorab zugeordneten Prioritäten und Abhängigkeiten in Linear, Asana oder Notion.

Entscheidungsdokumentation: Speichern Sie Strategy-Tokens in Ihrem Strategie-Repository, um festzuhalten, warum Entscheidungen getroffen wurden.

Berichte an die Geschäftsleitung: Ziehen Sie summary und monte_carlo_scenarios, um dem Führungsteam zu zeigen, wie die Strategie einem Belastungstest unterzogen wurde.

Wissensmanagement: Indexieren Sie evidence_citations, um ein institutionelles Gedächtnis der strategischen Recherche aufzubauen.

Auf Intelligence Tokens zugreifen

Über die REST-API

Der Hauptweg. Rufen Sie GET /v1/reports/{report_id} auf, sobald ein Bericht den Status completed erreicht. Die Antwort enthält das Feld token und bei Berichten zu AI Visibility und Site Audit ein public_intelligence-Objekt mit strukturierten Kennzahlen. Authentifizierung, Webhooks und alle Endpunkt-Details finden Sie im API-Integrationsleitfaden.

Per E-Mail

Wenn Ihr Bericht fertig ist, erhalten Sie eine E-Mail mit einer Magic-Link-Schaltfläche zum Ansehen des PDFs. Der Link ist etwa 30 Tage gültig.

Über die Surmado-App

Gehen Sie zu Berichte → wählen Sie Ihren Bericht → der Token und die Download-Links sind in der Detailansicht des Berichts sichtbar.

Schemas der Intelligence Tokens

Die Schemas der public_intelligence-Nutzlasten für AI Visibility und Site Audit sind oben dokumentiert. Die Strategy-Ausgabe wird als PDF geliefert. Eine strukturierte public_intelligence-Nutzlast wird für Strategy-Berichte derzeit nicht über die REST-API bereitgestellt.

Integrationsbeispiele

In allen Beispielen unten wird public_intelligence über GET /v1/reports/{report_id} aus der REST-API abgerufen (siehe API-Integrationsleitfaden).

Notion-Berichtsansicht

// Fetch a completed AI Visibility report and create a Notion database entry
const res = await fetch(`https://api.surmado.com/v1/reports/${reportId}`, {
  headers: { 'Authorization': `Bearer ${process.env.SURMADO_API_KEY}` }
});
const report = await res.json();
const signalData = report.public_intelligence;

await notion.pages.create({
  parent: { database_id: 'YOUR_DATABASE_ID' },
  properties: {
    'Business Name': { title: [{ text: { content: signalData.summary.business_name } }] },
    'Presence Score': { number: signalData.summary.presence_score },
    'Competitive Rank': { number: signalData.summary.competitive_rank },
    'Report Date': { date: { start: report.completed_at } },
    'Token': { rich_text: [{ text: { content: report.token } }] }
  }
});

Zapier-Webhook

// Trigger Zapier workflow when presence score drops
const currentScore = signalData.summary.presence_score;
const previousScore = signalData.data?.baseline_metrics?.previous_presence_score;

if (previousScore && currentScore < previousScore - 10) {
  await fetch('https://hooks.zapier.com/hooks/catch/YOUR_WEBHOOK/', {
    method: 'POST',
    body: JSON.stringify({
      alert: 'Presence score dropped significantly',
      business: signalData.summary.business_name,
      current_score: currentScore,
      previous_score: previousScore,
      drop: previousScore - currentScore
    })
  });
}

Linear-Issues anlegen (Site Audit)

// Fetch a completed Site Audit report and auto-create Linear issues from quick wins
const res = await fetch(`https://api.surmado.com/v1/reports/${reportId}`, {
  headers: { 'Authorization': `Bearer ${process.env.SURMADO_API_KEY}` }
});
const report = await res.json();
const scanData = report.public_intelligence;

for (const [area, recommendation] of Object.entries(scanData.summary.quick_wins ?? {})) {
  await linearClient.createIssue({
    teamId: 'YOUR_TEAM_ID',
    title: `[SEO] ${area}: ${recommendation.slice(0, 60)}`,
    description: recommendation,
    priority: 1,
    labels: ['seo', 'technical-debt']
  });
}

Google-Sheets-Zeitreihen-Tracking

// Append AI Visibility scores to Google Sheets for time-series tracking
const { GoogleSpreadsheet } = require('google-spreadsheet');
const doc = new GoogleSpreadsheet('YOUR_SHEET_ID');

await doc.useServiceAccountAuth(credentials);
await doc.loadInfo();

const sheet = doc.sheetsByIndex[0];
await sheet.addRow({
  'Date': report.completed_at,
  'Business': signalData.summary.business_name,
  'Presence Score': signalData.summary.presence_score,
  'Authority Score': signalData.summary.authority_score,
  'Rank': signalData.summary.competitive_rank,
  'ChatGPT Score': signalData.data?.platform_variance?.chatgpt?.presence_score,
  'Claude Score': signalData.data?.platform_variance?.claude?.presence_score
});

Kurze Antworten

Was ist ein Intelligence Token?

Intelligence Token = Ihre eindeutige Kennung für einen abgeschlossenen Bericht (Format: SIG-2025-11-XXXXX, SCN-2025-11-XXXXX oder SOL-2025-11-XXXXX). Der Token wird in der Status-Antwort der API zurückgegeben und ist der Schlüssel, den Sie beim Verketten von Berichten übergeben (z. B. um einen Strategy-Bericht aus einem bestehenden AI-Visibility-Bericht aufzubauen).

Warum er wertvoll ist:

Programmatischer Zugriff: Lesen Sie public_intelligence in Ihre Tools ein (Notion, Linear, Google Sheets)
Automatisierung: Bauen Sie Workflows, die bei neuen Berichten starten
Zeitreihen-Tracking: Speichern Sie historische Daten für die Trendanalyse
Berichte verketten: Übergeben Sie ihn als signal_token oder scan_token, wenn Sie einen Strategy-Bericht erstellen

Wo Sie ihn erhalten: Zurückgegeben von GET /v1/reports/{report_id} bei Abschluss, enthalten in Abschluss-Webhooks und angezeigt auf der Detailseite des Berichts in der Surmado-App.

Wie greife ich auf meinen Intelligence Token zu?

3 Wege, Ihren Token zu erhalten:

REST-API: Rufen Sie GET /v1/reports/{report_id} auf, sobald der Bericht completed ist. Das Feld token enthält den Wert.
Webhook: Wenn Sie beim Erstellen des Berichts eine webhook_url angeben, enthält die Abschluss-Nutzlast den Token unter report.token.
PDF-Bericht: Der Token steht auf der ersten Seite (Format: Token: SIG-2025-11-A7K3Q).

Intelligence Tokens sind stabile Kennungen für den abgeschlossenen Bericht und laufen nicht ab. Die Magic-Link-URL für das PDF in den Abschluss-E-Mails ist etwa 30 Tage gültig. Danach können Sie jederzeit eine neue signierte Download-URL vom Status-Endpunkt abrufen.

Kann ich Intelligence Tokens mit Zapier nutzen?

Ja! Beispiel für einen Zapier-Workflow mit dem Surmado-Abschluss-Webhook:

Trigger: Surmado-Webhook (Ereignis report.completed), webhook_url beim Erstellen des Berichts konfigurieren Aktion 1: Rufen Sie GET /v1/reports/{report.id} mit Ihrem API-Schlüssel auf, um public_intelligence abzurufen Aktion 2: Werten Sie public_intelligence.summary.presence_score aus Aktion 3: Legen Sie einen Notion-Datenbankeintrag mit den Werten an Aktion 4: Senden Sie eine Slack-Benachrichtigung, wenn presence_score < 10

Häufige Integrationen:

Notion: Marketing-Berichtsansicht automatisch befüllen
Linear: Aufgaben für schlecht bewertete Probleme anlegen
Google Sheets: Zeitreihen-Tracking
Slack: Team bei Sichtbarkeitsänderungen warnen

Eine Schritt-für-Schritt-Einrichtung finden Sie im Zapier-Integrationsleitfaden oder im Beispiel für Google-Sheets-Zeitreihen weiter unten.

Laufen Intelligence Tokens ab?

Nein. Tokens sind stabile Kennungen für einen abgeschlossenen Bericht und bleiben als historische Referenz gültig.

Was sich im Lauf der Zeit ändert:

Die Magic-Link-PDF-URL aus der E-Mail ist ca. 30 Tage gültig. Danach rufen Sie über GET /v1/reports/{report_id} eine neue signierte Download-URL ab.
Signierte Download-URLs, die der Status-Endpunkt zurückgibt, laufen nach etwa 15 Minuten ab. Laden Sie die Datei herunter und speichern Sie sie bei sich, wenn Sie sie langfristig brauchen.
Werte verschieben sich, wenn sich KI-Plattformen und die Positionierung von Wettbewerbern ändern. Führen Sie Berichte regelmäßig erneut aus (vierteljährlich ist ein üblicher Rhythmus), um frische Daten zu erhalten.

Was ist der Unterschied zwischen SIG-, SCN- und SOL-Tokens?

Unterschiedliche Schemas für unterschiedliche Produkte:

SIG-* (AI-Visibility-Tokens):

Schema: Sichtbarkeitskennzahlen (presence_score, ghost_influence, platform_variance)
Anwendungsfall: KI-Auffindbarkeit im Zeitverlauf verfolgen
Beispiel: SIG-2025-11-A7K3Q

SCN-* (Site-Audit-Tokens):

Schema: Technische SEO-Kennzahlen (lighthouse, schema_validation, accessibility)
Anwendungsfall: Website-Gesundheit überwachen, Core Web Vitals verfolgen
Beispiel: SCN-2025-11-A7K9P

SOL-* (Strategy-Tokens):

Schema: Strategische Empfehlungen (todo_list, priority, rationale), als PDF geliefert und nicht als public_intelligence bereitgestellt
Anwendungsfall: Dokumentation strategischer Entscheidungen, Weitergabe an Projektmanagement-Tools
Beispiel: SOL-2025-11-A7K3Q

Alle Tokens: stabile Kennungen, die bei Abschluss des Berichts zurückgegeben werden.

Schema-Dokumentation ansehen →

Hat Surmado eine REST-API?

Ja. Mit der Surmado-REST-API können Sie:

Berichte zu AI Visibility, Site Audit und Strategy programmatisch erstellen
Marken mit dem idempotenten POST /v1/brands/ensure verwalten
Den Berichtsstatus prüfen und PDFs/PPTX herunterladen
Webhook-Benachrichtigungen erhalten, wenn Berichte fertig sind

Authentifizieren Sie sich mit Ihrem API-Schlüssel (sur_live_...) per Bearer-Token oder X-API-Key-Header. Jeder Bericht kostet 1 Job.

Den vollständigen API-Integrationsleitfaden ansehen →

Kann ich AI-Visibility-Berichte automatisieren?

Ja. Nutzen Sie die REST-API, um AI-Visibility-Berichte programmatisch zu erstellen:

POST /v1/reports/signal

Kombinieren Sie sie mit Webhooks für vollautomatische Workflows. Erstellen Sie einen Bericht, erhalten Sie einen Webhook, wenn er fertig ist, und werten Sie dann die Ergebnisse aus. Pflichtfelder und Beispiele finden Sie im API-Integrationsleitfaden.

Sie können auch No-Code-Tools wie Zapier, Make oder n8n nutzen, um die Berichtserstellung über die API auszulösen. Eine Schritt-für-Schritt-Anleitung finden Sie im Zapier-Integrationsleitfaden.

Brauchen Sie Hilfe?

Fragen zu Schemafeldern? Lesen Sie unsere häufigen Fragen oder schreiben Sie an support@surmado.com.

Sie bauen eine Integration? Wir würden gern davon hören! Teilen Sie Ihren Anwendungsfall unter hi@surmado.com.

Jetzt starten: Surmado testen | Mit Scout arbeiten

→ Verwandt: API-Integrationsleitfaden | Zapier-Integrationsleitfaden | Make-Integrationsleitfaden | n8n-Integrationsleitfaden