…

7 Min.

Agenten-Integration mit der visible4ai API

Ein API-Schlüssel macht visible4ai zu einem Tool, das Ihr Agent aufrufen kann. Erstellen Sie einen Schlüssel in Ihrem Account, richten Sie Ihren Agenten auf POST /api/v1/analyse und jedes Audit, das Sie im Web-UI ausführen, ist nur noch ein HTTP-Aufruf. Dieser Leitfaden führt Sie vom frischen Schlüssel zur funktionierenden Integration in Claude Code, Cursor, OpenAI Functions, LangChain oder einfachem fetch.

Was Sie aufbauen werden

Am Ende dieser Seite haben Sie:

Einen funktionierenden API-Schlüssel

Erstellt auf Ihrer Account-Seite, einmalig angezeigt, bereit für eine Env-Variable oder einen Secret-Manager.

Ein erstes Audit von der Kommandozeile

Ein curl-Aufruf liefert ein vollständiges Sichtbarkeits-Audit, in derselben Form, die das Web-UI verwendet.

Einen Agenten, der ihn nutzen kann

Eingebunden in Ihr Tool der Wahl mit copy-paste-fertigen Snippets für die vier gängigsten Runtimes.

API-Schlüssel erstellen

Schlüssel leben auf Ihrer Account-Seite. Jeder Schlüssel wird bei der Erstellung einmalig angezeigt, danach speichern wir nur noch das Präfix — verloren bedeutet widerrufen und neu erstellen. Nur für Pro- und Enterprise-Pläne.

API-Schlüssel verwalten →

Ihr erstes Audit

Zwei Wege für Ihren ersten Aufruf — wählen Sie, was zu Ihrem Workflow passt.

API-Playground öffnen →oder unten den curl-Befehl nutzen

Ersetzen Sie YOUR_KEY durch den eben erstellten Wert und führen Sie folgenden Befehl in einem beliebigen Terminal aus:

bash

curl -X POST https://visible4ai.com/api/v1/analyse \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Die Antwort ist dasselbe JSON, das auch das Web-UI nutzt — GEO-Score, Datei-Checks, E-E-A-T-Signale, Zitate, Empfehlungen. Gecachte Ergebnisse tragen _cached: true und einen _cacheExpiresAt-Zeitstempel; mit "fresh": true im Body erzwingen Sie einen erneuten Crawl.

json

{
  "url": "https://example.com",
  "domain": "example.com",
  "geoScore": 67,
  "summary": "...",
  "files": { "llmsTxt": { "present": true }, "aiTxt": { "present": false } },
  "eeat": { "experience": "...", "expertise": "..." },
  "citations": { "perplexity": [...], "chatgpt": [...] },
  "recommendations": [ { "title": "...", "priority": "high" } ],
  "_cached": false
}

In Ihren Agenten einbinden

Vier Wege, den Endpunkt aus Agenten-Runtimes aufzurufen, ungefähr in der Reihenfolge, wie oft unsere Kunden sie nutzen:

Claude Code (Env-Var + Skill)

Tragen Sie den Schlüssel in Ihr Shell-Profil ein, dann nimmt jedes Skill oder jeder Hook, das curl ausführt, ihn automatisch auf.

bash

# ~/.zshrc or ~/.bashrc
export VISIBLE4AI_API_KEY="v4a_live_..."

# Any skill or hook that runs curl will now pick it up:
curl -sS -X POST https://visible4ai.com/api/v1/analyse \
  -H "Authorization: Bearer $VISIBLE4AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"url\": \"$1\"}" | jq .

OpenAI Functions / Tool Calling

Deklarieren Sie ein einzelnes Tool, das das Modell aufrufen kann. Das Schema ist klein, weil der Endpunkt nur einen Parameter erwartet.

typescript

const tools = [{
  type: "function",
  function: {
    name: "analyse_url",
    description: "Run a visible4ai audit on a URL.",
    parameters: {
      type: "object",
      properties: {
        url: { type: "string", description: "Absolute URL to audit." },
      },
      required: ["url"],
    },
  },
}];

// When the model calls analyse_url with { url }:
const res = await fetch("https://visible4ai.com/api/v1/analyse", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VISIBLE4AI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: args.url }),
});

LangChain Tool

Verpacken Sie den Fetch in einem Tool und übergeben Sie es Ihrem Agenten — Python oder JS.

python

from langchain_core.tools import tool
import os, requests

@tool
def analyse_url(url: str) -> dict:
    """Run a visible4ai audit on the given URL."""
    r = requests.post(
        "https://visible4ai.com/api/v1/analyse",
        headers={"Authorization": f"Bearer {os.environ['VISIBLE4AI_API_KEY']}"},
        json={"url": url},
        timeout=120,
    )
    r.raise_for_status()
    return r.json()

Reines fetch (TypeScript oder Python)

Wenn kein Framework im Spiel ist, funktioniert der reine HTTP-Aufruf überall. Das ist auch der einfachste Weg zu prüfen, ob Ihr Schlüssel aktiv ist, bevor Sie ihn in einen grösseren Agenten einbauen.

typescript

async function analyseUrl(url: string) {
  const res = await fetch("https://visible4ai.com/api/v1/analyse", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VISIBLE4AI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ url }),
  });
  if (!res.ok) throw new Error(`visible4ai ${res.status}`);
  return res.json();
}

python

import os, requests

def analyse_url(url: str):
    r = requests.post(
        "https://visible4ai.com/api/v1/analyse",
        headers={"Authorization": f"Bearer {os.environ['VISIBLE4AI_API_KEY']}"},
        json={"url": url},
        timeout=120,
    )
    r.raise_for_status()
    return r.json()

Referenz

Endpunkt

POST /api/v1/analyse

Authentifizierung

Authorization: Bearer v4a_live_…

Rate Limit

100 Anfragen pro 15-Minuten-Fenster, 1000 pro 24-Stunden-Fenster, pro Schlüssel. 429 gibt einen Retry-After-Header in Sekunden zurück.

Body

{ "url": "https://example.com", "fresh"?: boolean } — max. 16 KB.

Fehlercodes

401 UNAUTHORIZED — fehlender, ungültiger oder widerrufener Schlüssel
403 PLAN_REQUIRED — Account ist auf Free oder wurde herabgestuft
400 INVALID_URL — URL fehlt, ist fehlerhaft oder blockiert
429 RATE_LIMITED — langsamer; Retry-After beachten
413 PAYLOAD_TOO_LARGE — Request-Body überschritt 16 KB
502 ENGINE_ERROR — vorübergehender Crawl- oder Analyse-Fehler; erneut versuchen

🔒Wir loggen Ihren Schlüssel nie

Jede serverseitige Log-Zeile läuft durch einen Bearer-Redaction-Helper, bevor sie in ein Log-Ziel geschrieben wird. Falls ein zukünftiger Code-Pfad versehentlich versucht, Ihren Token zu loggen, schlägt unsere Test-Suite den Build fehl. Das Einzige, was wir nach der Erstellung speichern, ist die sha256-gehashte Form Ihres Schlüssels.

Endpoint Context Protocol (ECP) integrieren

7 Min.

Agenten-Integration mit der visible4ai API

Was Sie aufbauen werden

Am Ende dieser Seite haben Sie:

Einen funktionierenden API-Schlüssel

Erstellt auf Ihrer Account-Seite, einmalig angezeigt, bereit für eine Env-Variable oder einen Secret-Manager.

Ein erstes Audit von der Kommandozeile

Ein curl-Aufruf liefert ein vollständiges Sichtbarkeits-Audit, in derselben Form, die das Web-UI verwendet.

Einen Agenten, der ihn nutzen kann

Eingebunden in Ihr Tool der Wahl mit copy-paste-fertigen Snippets für die vier gängigsten Runtimes.

API-Schlüssel erstellen

API-Schlüssel verwalten →

Ihr erstes Audit

Zwei Wege für Ihren ersten Aufruf — wählen Sie, was zu Ihrem Workflow passt.

API-Playground öffnen →oder unten den curl-Befehl nutzen

Ersetzen Sie YOUR_KEY durch den eben erstellten Wert und führen Sie folgenden Befehl in einem beliebigen Terminal aus:

bash

curl -X POST https://visible4ai.com/api/v1/analyse \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

json

{
  "url": "https://example.com",
  "domain": "example.com",
  "geoScore": 67,
  "summary": "...",
  "files": { "llmsTxt": { "present": true }, "aiTxt": { "present": false } },
  "eeat": { "experience": "...", "expertise": "..." },
  "citations": { "perplexity": [...], "chatgpt": [...] },
  "recommendations": [ { "title": "...", "priority": "high" } ],
  "_cached": false
}

In Ihren Agenten einbinden

Vier Wege, den Endpunkt aus Agenten-Runtimes aufzurufen, ungefähr in der Reihenfolge, wie oft unsere Kunden sie nutzen:

Claude Code (Env-Var + Skill)

Tragen Sie den Schlüssel in Ihr Shell-Profil ein, dann nimmt jedes Skill oder jeder Hook, das curl ausführt, ihn automatisch auf.

bash

# ~/.zshrc or ~/.bashrc
export VISIBLE4AI_API_KEY="v4a_live_..."

# Any skill or hook that runs curl will now pick it up:
curl -sS -X POST https://visible4ai.com/api/v1/analyse \
  -H "Authorization: Bearer $VISIBLE4AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"url\": \"$1\"}" | jq .

OpenAI Functions / Tool Calling

Deklarieren Sie ein einzelnes Tool, das das Modell aufrufen kann. Das Schema ist klein, weil der Endpunkt nur einen Parameter erwartet.

typescript

const tools = [{
  type: "function",
  function: {
    name: "analyse_url",
    description: "Run a visible4ai audit on a URL.",
    parameters: {
      type: "object",
      properties: {
        url: { type: "string", description: "Absolute URL to audit." },
      },
      required: ["url"],
    },
  },
}];

// When the model calls analyse_url with { url }:
const res = await fetch("https://visible4ai.com/api/v1/analyse", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VISIBLE4AI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: args.url }),
});

LangChain Tool

Verpacken Sie den Fetch in einem Tool und übergeben Sie es Ihrem Agenten — Python oder JS.

python

from langchain_core.tools import tool
import os, requests

@tool
def analyse_url(url: str) -> dict:
    """Run a visible4ai audit on the given URL."""
    r = requests.post(
        "https://visible4ai.com/api/v1/analyse",
        headers={"Authorization": f"Bearer {os.environ['VISIBLE4AI_API_KEY']}"},
        json={"url": url},
        timeout=120,
    )
    r.raise_for_status()
    return r.json()

Reines fetch (TypeScript oder Python)

typescript

async function analyseUrl(url: string) {
  const res = await fetch("https://visible4ai.com/api/v1/analyse", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VISIBLE4AI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ url }),
  });
  if (!res.ok) throw new Error(`visible4ai ${res.status}`);
  return res.json();
}

python

import os, requests

def analyse_url(url: str):
    r = requests.post(
        "https://visible4ai.com/api/v1/analyse",
        headers={"Authorization": f"Bearer {os.environ['VISIBLE4AI_API_KEY']}"},
        json={"url": url},
        timeout=120,
    )
    r.raise_for_status()
    return r.json()

Referenz

Endpunkt

POST /api/v1/analyse

Authentifizierung

Authorization: Bearer v4a_live_…

Rate Limit

100 Anfragen pro 15-Minuten-Fenster, 1000 pro 24-Stunden-Fenster, pro Schlüssel. 429 gibt einen Retry-After-Header in Sekunden zurück.

Body

{ "url": "https://example.com", "fresh"?: boolean } — max. 16 KB.

Fehlercodes

401 UNAUTHORIZED — fehlender, ungültiger oder widerrufener Schlüssel
403 PLAN_REQUIRED — Account ist auf Free oder wurde herabgestuft
400 INVALID_URL — URL fehlt, ist fehlerhaft oder blockiert
429 RATE_LIMITED — langsamer; Retry-After beachten
413 PAYLOAD_TOO_LARGE — Request-Body überschritt 16 KB
502 ENGINE_ERROR — vorübergehender Crawl- oder Analyse-Fehler; erneut versuchen

🔒Wir loggen Ihren Schlüssel nie

Endpoint Context Protocol (ECP) integrieren