Der MCP-Server bekommt die Aufmerksamkeit, aber darunter liegt eine schlichte REST-API, und alles, was der Assistent tun kann, kann auch ein Skript. Dieser Beitrag geht die Endpoints in der Reihenfolge durch, in der du sie wahrscheinlich brauchst, mit einem curl-Befehl für jeden. Willst du lieber über Claude mit ihr sprechen, beginne stattdessen mit dem Launch-Beitrag.
Basis-URL und Authentifizierung
Base URL: https://provedly.app/api/v1
Header: Authorization: Bearer provedly_…
Der Schlüssel ist ein Account-API-Schlüssel, erstellt unter Settings im Bereich API keys. Er beginnt mit provedly_, wird einmal angezeigt und kann jederzeit widerrufen werden. Wähle Read only für Skripte, die nur berichten, und Read and write für alles, was einen Zustand ändert. Den Unterschied erklärt einen API-Schlüssel wählen.
Für die Beispiele legst du den Schlüssel in eine Umgebungsvariable, damit er nicht in deiner Shell-History landet:
export PROVEDLY_KEY="provedly_your_key_here"
Schlüssel gehören auf Server und in dein eigenes Terminal. Liefere nie einen in Browser-JavaScript aus.
Dein Konto auslesen
Beginne mit dem Account-Endpoint. Er gibt deinen Plan, seine Limits und den aktuellen Verbrauch zurück, also den Kontext für alles andere.
curl https://provedly.app/api/v1/account \
-H "Authorization: Bearer $PROVEDLY_KEY"
Dann die Dinge im Konto:
curl https://provedly.app/api/v1/sites -H "Authorization: Bearer $PROVEDLY_KEY"
curl https://provedly.app/api/v1/widgets -H "Authorization: Bearer $PROVEDLY_KEY"
curl https://provedly.app/api/v1/bars -H "Authorization: Bearer $PROVEDLY_KEY"
Einzelne Elemente liegen unter /widgets/{id} und /bars/{id}. Widgets, Leisten und Websites lassen sich über ihre ID, eine UUID, oder über ihren Token ansprechen, je nachdem, was du gerade zur Hand hast. Ein Skript, das schon einen Widget-Token aus deinem Installations-Snippet hat, muss nicht erst die UUID nachschlagen.
Statistiken
curl "https://provedly.app/api/v1/stats?days=30" \
-H "Authorization: Bearer $PROVEDLY_KEY"
Die Antwort umfasst Impressionen, Klicks, verifizierte Bestellungen und durch Proof unterstützte Bestellungen mit ihrem Umsatz, für die Anzahl Tage, die du angibst. „Durch Proof unterstützt“ heißt, dass der Käufer vor dem Kauf eine Benachrichtigung gesehen hat, pro Besucher zugeordnet innerhalb eines 30-Tage-Fensters. Das ist dieselbe Definition wie im Dashboard, erklärt in durch Proof unterstützte Bestellungen messen. Setz days auf 7 für einen Wochenbericht.
Widgets und Leisten ändern
Alles in diesem Abschnitt braucht einen Schlüssel mit Lese- und Schreibzugriff. Ein Widget zu pausieren oder fortzusetzen ist ein PATCH:
curl -X PATCH https://provedly.app/api/v1/widgets/WIDGET_ID \
-H "Authorization: Bearer $PROVEDLY_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "paused"}'
Sende "active", um fortzusetzen. Beim Fortsetzen zeigen sich die Plan-Limits: Erlaubt der Plan eine feste Zahl aktiver Widgets und hast du sie schon erreicht, wird die Anfrage mit Begründung abgelehnt, statt still darüber hinauszugehen. Ein Lese-Schlüssel wird bei jedem Schreibvorgang abgelehnt, egal was im Body steht.
Eine Leiste anzulegen ist ein POST an /bars. Leg den Body in eine Datei, damit er sich leicht prüfen lässt:
curl -X POST https://provedly.app/api/v1/bars \
-H "Authorization: Bearer $PROVEDLY_KEY" \
-H "Content-Type: application/json" \
-d @winter-launch.json
Eine neue, über die API angelegte Leiste startet pausiert. Das ist Absicht: Niemand sieht sie, bevor du sie geprüft hast, und ein Tippfehler in einem Skript kann keine halbfertige Leiste vor Besucher stellen. Der Livegang ist ein zweiter Aufruf:
curl -X PATCH https://provedly.app/api/v1/bars/BAR_ID \
-H "Authorization: Bearer $PROVEDLY_KEY" \
-H "Content-Type: application/json" \
-d '{"status": "active"}'
Die Aktivierung beachtet das Leistenlimit deines Plans genauso wie das Fortsetzen von Widgets.
Derselbe PATCH-Endpoint bearbeitet Name, Nachricht und Enddatum einer Leiste und pausiert sie oder setzt sie fort. Für Enddaten akzeptiert ends_at entweder eine lokale Zeit wie "2026-12-01 09:00", gelesen in der eigenen Zeitzone der Leiste, oder einen vollständigen ISO-8601-Zeitstempel:
curl -X PATCH https://provedly.app/api/v1/bars/BAR_ID \
-H "Authorization: Bearer $PROVEDLY_KEY" \
-H "Content-Type: application/json" \
-d '{"ends_at": "2026-12-01 09:00"}'
Die lokale Form ist für einen Launch meist das, was du willst, denn „9 Uhr“ heißt 9 Uhr dort, wo die Leiste eingestellt ist, nicht dort, wo dein Server zufällig läuft. Mehr zu Daten in Launch-Countdowns planen.
Einträge hinzufügen
Die Records-API, POST /widgets/{token}/records, ist in ihrer Form unverändert und akzeptiert jetzt auch einen Account-Schlüssel. Ein Schlüssel kann also jedes Widget im Konto versorgen, statt für jedes einen eigenen Widget-Schlüssel zu pflegen. Die Felder und Idempotenzregeln stehen in der Referenz zur Records-API, und die Variante mit Account-Schlüssel wird in Einträge mit einem Account-Schlüssel senden Schritt für Schritt erklärt.
So angelegte Einträge behalten die Quelle API und erscheinen im Widget mit einem sichtbaren „Imported“-Label, ohne die Kennzeichnung „Verifiziert“. Die API hat kein Feld, das einen Eintrag als verifiziert markiert, und keine Schlüsselstufe fügt eines hinzu. Nur signierte Webhooks von Stripe, Shopify und WooCommerce erzeugen verifizierte Einträge.
Ablehnungen lesen
Die meisten Fehler fallen in wenige Gruppen:
| Situation | Was du bekommst |
|---|---|
| Fehlender, falscher oder widerrufener Schlüssel | Einen Authentifizierungsfehler |
| Lese-Schlüssel an einem Schreib-Endpoint | Eine Ablehnung mit dem Hinweis, dass der Schlüssel nur lesen darf |
| Änderung würde ein Plan-Limit überschreiten | Eine Ablehnung, die das Limit nennt |
| Ungültiges Feld, etwa ein falsches Datum | Einen Validierungsfehler für dieses Feld |
Skripte sollten Ablehnungen wegen Plan-Limits als Information für einen Menschen behandeln, nicht als etwas, das man erneut versucht.
Häufige Fragen
Ist die API dasselbe, was der MCP-Server nutzt?
Die MCP-Tools decken dieselben Aktionen mit denselben Regeln ab: dieselben Schlüssel, dieselben Plan-Limits, dieselbe Weigerung, Einträge zu verifizieren. Nimm, was zur Aufgabe passt.
Kann ich eine Leiste anlegen, die sofort live geht?
Nicht mit einem Aufruf. Über die API angelegte Leisten starten pausiert, und du aktivierst sie mit einer zweiten Anfrage. Das ist eine zusätzliche Zeile in einem Skript und verhindert Überraschungen.
Welche Pläne enthalten die API?
Alle, auch Free. Die Plan-Limits für Widgets, Leisten und Impressionen gelten wie üblich.
Was jeder Plan erlaubt, siehst du auf der Preisseite.