Endpunkte

Konventionen

Alle Pfade sind relativ zu https://teddit.io/api. Senden Sie den Schlüssel wie unter Authentifizierung beschrieben.

• Zugang ist die niedrigste Schlüsselrolle, die den Endpunkt aufrufen darf: viewer (ein Schlüssel Lesen), member (Lesen + Bearbeiten) oder admin (Lesen + Scannen). Eine höhere Rolle darf ihn immer ebenfalls aufrufen.
• :orgId ist die Workspace-ID aus GET /whoami. :id ist eine Site-ID aus GET /orgs/:orgId/projects.
• Zeitraum-Parameter. Die Bericht-Endpunkte nehmen period (day, week, month oder quarter; Voreinstellung week) und start (ein beliebiges Datum innerhalb des gewünschten Zeitraums, YYYY-MM-DD; Voreinstellung der letzte Zeitraum). Ihre Antworten wiederholen period und start und führen jeden Zeitraum mit Daten in periods auf.
• In Antworten ist „genannt“ mentioned, „verlinkt“ ist ownCited, Ihr Platz ist brandRank, visibility ist der Sichtbarkeitswert, und ein Assistent ist ein provider mit dem Schlüssel openai, anthropic, perplexity, gemini, google_aio oder google_ai_mode.

Die MCP-Werkzeuge geben dieselben Daten zurück, die Beschreibung eines Werkzeugs beschreibt also auch den passenden Endpunkt.

Workspace

Eine Site anlegen nimmt name und url (beide Pflicht) und optional industry, brandTerms (weitere Namen, bis zu 50), competitors (Objekte mit name und domain, bis zu 50), language (Voreinstellung English) und location (Voreinstellung United States).

Einladen nimmt email und role (viewer, member oder admin; Voreinstellung member). Eine Rolle ändern nimmt role. Was ein Admin mit anderen Mitgliedern tun darf und was nicht, steht auf der Seite Rollen.

Für Schlüssel nicht verfügbar: alles unter /auth und /account, Workspaces anlegen, löschen und verlassen, einen Workspace umbenennen (PATCH /orgs/:orgId, nur Owner), Aufladen und Rechnungen (nur Owner) und Schlüssel verwalten (/orgs/:orgId/tokens).

Sites

Einstellungen ändern nimmt beliebige dieser Felder:

• name, brandTerms: der Markenname und seine weiteren Namen. Eine Änderung von einem der beiden liest alle gespeicherten Antworten erneut; die Antwort trägt dann eine reanalysis-Zusammenfassung.
• industry, language, location (das Land).
• scanFrequencyDays (1 bis 365): der Abstand zwischen geplanten Scans.
• monthlyCapUsd: die Monatsgrenze der Site in US-Dollar. null oder 0 entfernt sie.
• scanSettings: die gespeicherten Scan-Einstellungen, als Ganzes ersetzt. Ein Objekt mit providers (Assistenten-Schlüssel; weggelassen bedeutet alle verbundenen), models (Assistenten-Schlüssel zu Modell), category, budgetUsd (das Meiste, was ein Scan kosten darf; 0 bedeutet das Doppelte seiner Schätzung) und skipAtCap (false lässt Scans starten, auch wenn die Monatsgrenze ausgeschöpft ist).

Zeitplan nimmt enabled (true oder false). Das Einschalten des Zeitplans setzt den ersten Scan auf die nächste Nacht (UTC); die Antworten eines geplanten Scans kommen innerhalb weniger Stunden an.

Eine Site zu löschen, mit ihren Prompts, Scans und Antworten, ist einem angemeldeten Owner vorbehalten und für Schlüssel nicht verfügbar.

Käufer-Personas

GET /projects/:id/personas listet die Personas einer Site mit der Zahl der Prompts, die jede als Fragende nutzen; POST (member) fügt eine hinzu mit name (bis zu 80 Zeichen) und context (bis zu 600): wer fragt, in dessen Worten. PATCH /projects/:id/personas/:personaId ändert eines von beiden; DELETE entfernt eine, und ihre Prompts werden ab dem nächsten Scan ohne Persona gestellt. Prompts nehmen personaId beim Anlegen, Bearbeiten und Stapelbearbeiten (null löscht sie). Jede Antwort behält den Wortlaut, mit dem sie gestellt wurde, als context.

Berichte

Alle diese sind GET, brauchen viewer und nehmen die Zeitraum-Parameter.

curl "https://teddit.io/api/projects/12/report?period=month&start=2026-09-15" \
  -H "Authorization: Bearer tdt_…"

Wie die Zahlen in diesen Antworten berechnet werden: Kennzahlen und Status.

Prompts und Kategorien

Die Liste und der Export nehmen dieselben Query-Parameter: q (Textsuche), category, status (draft, active, paused), intent, verdict (named, lost, cited, missing, failed), competitor (der Name eines verfolgten Wettbewerbers), stability (held, volatile, lost) und scanned (yes, never). Die Liste nimmt außerdem sort (created, text, category, rank, scanned), dir (asc, desc), page, perPage (5 bis 200, Voreinstellung 20) und die Zeitraum-Parameter, die festlegen, wofür ein Verlaufskästchen steht.

Hinzufügen nimmt text (3 bis 500 Zeichen, Pflicht), category oder categories (eine Liste von bis zu 8), intent (Voreinstellung informational), funnel (Voreinstellung awareness) und status (Voreinstellung active). Ein bereits verfolgter Text antwortet 409. Bearbeiten nimmt dieselben Felder, alle optional; categories ersetzt die ganze Liste.

Stapel nimmt ids (1 bis 5000) und status, category oder delete: true. Das Löschen eines Prompts löscht seine Antworten.

Import nimmt contents (der Text der Datei, bis zu 2.000.000 Zeichen), status (Voreinstellung draft) und dryRun. Er gibt rows, created, updated, skipped und categories zurück. Das Dateiformat steht auf der Seite Prompts importieren.

Eine Antwort nimmt engine (ein Assistenten-Schlüssel; Voreinstellung der erste Assistent, der geantwortet hat) oder r (die ID einer früheren Antwort, aus den results des Prompts).

Kategorien zusammenführen nimmt names (die zusammenzulegenden Kategorien) und into (der Name, den sie bekommen). Ein Name ist eine Umbenennung, mehrere sind eine Zusammenführung, und ein leeres into entfernt die Kategorien von ihren Prompts.

Wettbewerber und Seiten

Verfolgen nimmt name (Pflicht), domain, aliases (weitere Namen, bis zu 30), color und logo. Ändern nimmt dieselben Felder, alle optional: Nur was Sie senden, ändert sich, aliases ersetzt die ganze Liste, und domain: null entfernt die Domain. Alle drei Wettbewerber-Endpunkte lesen die gespeicherten Antworten erneut, wenn sich die Namen ändern, und geben das Ergebnis als reanalysis zurück.

Seiten nimmt q, section (der erste Teil des Pfads), shown (yes oder no), page und perPage (5 bis 200, Voreinstellung 50).

Scans

Schätzung und Start nehmen denselben Body. Jedes Feld ist optional:

• providers: Assistenten-Schlüssel. Leer bedeutet jeder verbundene Assistent.
• promptIds: eine gewählte Auswahl von Prompts. Leer bedeutet jeder aktive Prompt. Prompts, die nicht aktiv sind, werden übersprungen.
• category: eine Kategorie scannen.
• sample: so viele Prompts scannen, zufällig gezogen.
• models: Assistenten-Schlüssel zu Modell, aus den Optionen in scan-options. chatgpt-app und gemini-app (schnell: sofort beantwortet) sowie chatgpt-app-queue und gemini-app-queue (langsam und günstiger: einige Minuten) nehmen die Antwort, wie die App sie zeigt.
• saved: true nimmt die Assistenten, Modelle und Kategorie aus den gespeicherten Scan-Einstellungen der Site statt aus dieser Anfrage. Beim Start nimmt es auch das gespeicherte Limit pro Scan.
• Nur beim Start: budgetUsd (stoppen, sobald der Scan so viel gekostet hat; weggelassen, das Doppelte seiner Schätzung) und label.

Die Schätzung gibt prompts, answers, cost und formatted zurück. Der Start gibt den Scan zurück, antwortet 402, wenn das Guthaben den Scan nicht deckt, und 400 mit dem Grund für alles andere, was ihn am Starten hindert. Die Gründe, und wie Kosten gezählt werden, stehen auf der Seite Guthaben und Ausgabengrenzen.

Ein Scan nimmt tab (all, notNamed, competitorsOnly, errors), engine (ein Assistenten-Schlüssel) und page. Scan-Status sind queued, running, cancelling, cancelled, done und failed.

Ein vollständiges Beispiel

Die Site finden, einen Prompt hinzufügen, einen Scan einer Kategorie bepreisen, ihn starten und das Ergebnis lesen. Den Scan zu starten braucht einen Schlüssel Lesen + Scannen.

KEY="tdt_…"
API="https://teddit.io/api"

# 1. Which workspace is this key for?
curl "$API/whoami" -H "Authorization: Bearer $KEY"
#    → "org": { "id": 3, … }

# 2. The sites of the workspace
curl "$API/orgs/3/projects" -H "Authorization: Bearer $KEY"
#    → "projects": [{ "id": 12, "domain": "brightloop.example", … }]

# 3. Add a prompt
curl -X POST "$API/projects/12/prompts" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"text": "What does email automation cost for 10,000 contacts?", "category": "pricing", "intent": "commercial"}'

# 4. What would a scan of that category cost?
curl -X POST "$API/projects/12/scans/estimate" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"category": "pricing"}'
#    → { "prompts": …, "answers": …, "cost": …, "formatted": "$…" }

# 5. Run it, and stop at 2 dollars
curl -X POST "$API/projects/12/scans" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"category": "pricing", "budgetUsd": 2}'

# 6. Follow it until "run" is null
curl "$API/projects/12/scans/live" -H "Authorization: Bearer $KEY"

# 7. Read this week's report
curl "$API/projects/12/report" -H "Authorization: Bearer $KEY"