REST-API

Authentifizierung

Die REST-API gibt Skripten und Dashboards dieselben Daten wie die App. Ein Skript erreicht sie mit einem Workspace-API-Schlüssel, der als Bearer-Token gesendet wird. Diese Seite behandelt Schlüssel, ihre Zugangsstufen und die Fehler, die zurückkommen können.

Basisadresse und Format

https://teddit.io/api

Anfragen und Antworten sind JSON. Senden Sie Content-Type: application/json mit jedem Body. Ein Anfrage-Body darf bis zu 4 MB groß sein.
IDs sind Zahlen. Die API nennt einen Workspace Organisation (/orgs/:orgId) und eine Site Projekt (/projects/:id).
Zeiten sind ISO 8601 in UTC. Wochen und andere Zeiträume werden als Datum angegeben, YYYY-MM-DD.

Die Liste der Adressen steht auf der Seite Endpunkte.

API-Schlüssel

Erstellen Sie einen Schlüssel in der App: Zahnrad-Symbol → API & MCP → Schlüssel erstellen. Jede Rolle kann das; der Schlüssel bekommt höchstens den Zugang Ihrer eigenen.

Ein Schlüssel sieht aus wie tdt_, gefolgt von 40 Buchstaben, Ziffern, - und _.
Er wird einmal angezeigt, beim Erstellen. Teddit speichert einen Hash davon, nicht den Schlüssel, ein verlorener Schlüssel lässt sich also nicht wiederherstellen. Erstellen Sie stattdessen einen neuen.
Ein Schlüssel gehört zu einem Workspace und erreicht jede Site darin.
Die Schlüsselliste zeigt für jeden Schlüssel seinen Namen, seine ersten Zeichen, seinen Zugang, wer ihn erstellt hat und wann er zuletzt verwendet wurde. „Zuletzt verwendet“ wird höchstens alle fünf Minuten aktualisiert.
Ein Schlüssel läuft nicht ab. Widerrufen Sie ihn mit dem Papierkorb-Symbol; er funktioniert ab der nächsten Anfrage nicht mehr.

Dieselben Schlüssel öffnen den MCP-Server.

Den Schlüssel senden

Setzen Sie den Schlüssel in den Header Authorization jeder Anfrage:

curl https://teddit.io/api/whoami \
  -H "Authorization: Bearer tdt_…"

GET /api/whoami ist der Aufruf, mit dem Sie beginnen sollten. Er sagt, zu welchem Workspace der Schlüssel gehört und was er darf:

{
  "kind": "token",
  "tokenName": "Reporting script",
  "user": { "id": 7, "name": "Dana Whitfield", "email": "dana@brightloop.example" },
  "org": { "id": 3, "name": "Brightloop", "plan": "free" },
  "role": "viewer"
}

Verwenden Sie org.id in den Adressen /orgs/:orgId/…. user ist die Person, die den Schlüssel erstellt hat: Aktionen mit dem Schlüssel, etwa das Starten eines Scans, werden unter diesem Namen erfasst.

Der Schlüssel ist das ganze Zugangsmittel. Halten Sie ihn aus Webseiten, Repositories und Chatnachrichten heraus, und geben Sie jedem Skript einen eigenen Schlüssel, damit einer widerrufen werden kann, ohne die anderen zu stoppen.

Zugangsstufen von Schlüsseln

Ein Schlüssel hat eine von drei Zugangsstufen. Jede ist eine Workspace-Rolle, und jede schließt die darüber ein.

Zugang in der App	`role`	Darf aufrufen
Lesen	`viewer`	Alles, was liest: Berichte, Prompts, Antworten, Wettbewerber, Seiten, Scans, Mitglieder. Außerdem die Kostenschätzung eines Scans.
Lesen + Bearbeiten	`member`	Außerdem: Prompts, Kategorien und Wettbewerber anlegen, ändern und löschen; importieren; Namen, Sprache und Land einer Site ändern.
Lesen + Scannen	`admin`	Außerdem: Scans starten und abbrechen, den Zeitplan ein- und ausschalten, Monatsgrenze und Scan-Einstellungen ändern, Sites anlegen, Mitglieder einladen und entfernen.

Es gibt keine Schlüssel mit der Rolle Owner. Aufladen, eine Site löschen und einen Workspace umbenennen bleiben einem angemeldeten Owner vorbehalten.
Sie können keinen Schlüssel mit mehr Zugang erstellen, als Ihre eigene Rolle Ihnen gibt.
Ein Schlüssel folgt der Person, die ihn erstellt hat: herabgestuft mit ihrer Rolle, gestoppt, wenn sie den Workspace verlässt.

Was ein Schlüssel nicht kann

Manche Aktionen brauchen eine Person, die in der App im Browser angemeldet ist. Mit einem Schlüssel aufgerufen, antworten sie 403 mit „This action needs a signed-in person, not an API token.“

API-Schlüssel erstellen, auflisten und widerrufen.
Namen, E-Mail-Adresse oder Passwort ändern und das Konto löschen.
Einen Workspace anlegen, einen löschen, zwischen Workspaces wechseln und einen verlassen.
Eine Einladung annehmen.

Ein Schlüssel sieht auch nichts außerhalb seines Workspace. Eine Site- oder Workspace-ID, die jemand anderem gehört, antwortet 404, genau wie eine ID, die nicht existiert.

Fehler

Jeder Fehler hat denselben Body: eine Meldung für eine Person in error, und fields mit einer Meldung pro Feld, wenn das Problem in der Eingabe liegt, sonst null.

HTTP/1.1 409 Conflict

{
  "error": "This prompt already exists in the project.",
  "fields": { "text": "Already tracked" }
}

Status	Wann
400	Die Anfrage ist wohlgeformt, wird aber verweigert: Ein Workspace-Limit ist erreicht, ein Scan kann nicht starten (ein anderer läuft, keine aktiven Prompts, das Guthaben deckt ihn nicht, die Monatsgrenze ist ausgeschöpft), oder eine Adresse ist keine Domain. Die Meldung sagt, was es ist.
401	Kein Schlüssel, ein Schlüssel in falscher Form oder ein widerrufener Schlüssel. Die Meldung ist „Sign in to continue.“
403	Die Zugangsstufe des Schlüssels ist für die Aktion zu niedrig, oder die Aktion braucht eine angemeldete Person.
404	Die Adresse oder die ID existiert nicht oder gehört zu einem anderen Workspace.
409	Ein Duplikat: ein Prompt mit demselben Text, ein Wettbewerber oder eine Kategorie mit demselben Namen, eine Einladung für jemanden, der bereits Mitglied ist.
422	Der Body oder der Query-String hat die Validierung nicht bestanden. `fields` nennt jedes Feld, das falsch ist.
429	Zu viele Anfragen an eine Adresse mit eigenem Limit, etwa Anmeldung, Einladungen oder das Lesen der Sitemap. Warten Sie und versuchen Sie es erneut.
500, 502	Etwas ist auf unserer Seite fehlgeschlagen, oder ein Assistent ist fehlgeschlagen, während die Anfrage bearbeitet wurde.

Erfolgreiche Aufrufe antworten 200 mit JSON. Das Löschen einer Site, eines Mitglieds oder einer Einladung antwortet 204 ohne Body.

Raten- und Workspace-Limits

Die meisten Anfragen mit einem Schlüssel haben kein Ratenlimit. Einige Aktionen haben ein eigenes: Personen einladen, die Sitemap erneut lesen und Anfragen umschreiben. Eine Überschreitung antwortet 429.
Die Workspace-Limits gelten für die API genau wie in der App: Sites, Prompts pro Site, Scans pro Monat und Mitglieder. Ein Aufruf, der ein Limit überschreiten würde, antwortet 400 mit dem Limit in der Meldung.
Listenadressen sind seitenweise. Die Prompt-Liste nimmt page und perPage (5 bis 200); mehr zu verlangen antwortet 422.

Zurück‹ Beispielfragen WeiterEndpunkte ›