Authentifizierung

Jede Anfrage an die Pedra-API authentifiziert sich mit einem API-Schlüssel im JSON-Body.

API-Schlüssel erhalten

1. Registrieren Sie sich auf app.pedra.ai.
2. Öffnen Sie Einstellungen → API.
3. Kopieren Sie Ihren Schlüssel. Er ist langlebig und an Ihr Konto gebunden.

Für höhere Quoten, dedizierte Kapazität oder Enterprise-Preise senden Sie eine E-Mail an felix@pedra.ai.

Sie bauen einen Agenten? Er kann per E-Mail einen Schlüssel für die Person bekommen, für die er arbeitet, mit deren Zustimmung — siehe Konten für KI-Agenten.

Schlüssel verwenden

Übergeben Sie den Schlüssel als apiKey im JSON-Request-Body für jeden Endpunkt. Es gibt keine Header-basierte Authentifizierung, keinen OAuth-Flow und kein Token-Refresh — Schlüssel sind langlebig und an Ihr Konto gebunden.

curl -X POST https://app.pedra.ai/api/enhance \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "imageUrl": "https://example.com/photo.jpg"
  }'

Schlüssel sicher aufbewahren

• Verteilen Sie Schlüssel niemals im Client-Code. Aufrufe müssen von Ihrem Backend ausgehen. Ein in einen Browser-Bundle oder eine Mobile-App eingebetteter Schlüssel ist faktisch öffentlich.
• Speichern Sie Schlüssel als Umgebungsvariablen. Nicht im Versionskontrollsystem.
• Rotieren Sie sofort bei Leak. Schreiben Sie uns — wir widerrufen den alten Schlüssel und stellen einen neuen aus.

Fehler

Fehlende oder ungültige Schlüssel geben HTTP 404 mit {"error": "User not found"} zurück — Pedra sucht den Schlüssel als Benutzer-Datensatz, daher erscheint ein unbekannter Schlüssel als fehlender Benutzer. Siehe Fehler und Limits für die vollständige Liste der Fehlermodi.

Konten für KI-Agenten

Ein KI-Agent kann einen API-Schlüssel für die Person bekommen, für die er arbeitet — und ihr ein Pedra-Konto anlegen, falls sie keins hat —, ohne dass einer von beiden die Einstellungen öffnet. Das ist für Agenten ohne Browser: Claude Code, ein Skript, der lokale MCP-Server, alles, was nur HTTP spricht. Die Person bestätigt aus ihrem Posteingang; der Agent sieht nie ein Passwort.

ChatGPT- und Claude-Connectoren brauchen das nicht. Wer Pedra dort verbindet, meldet sich per OAuth an, und neue Nutzer können ihr Konto im selben Anmelde-Tab anlegen. Siehe MCP-Server.

1. Der Agent ruft agent_signup mit der E-Mail-Adresse der Person auf. Pedra schickt ihr einen Bestätigungslink, 30 Minuten gültig.
2. Der Agent bittet die Person, ihre E-Mails zu prüfen. Sie öffnet den Link: Ein neues Konto gibt seinen Beruf an, wählt eine Sprache und ein Passwort (mindestens 8 Zeichen) und klickt auf Create account and allow; ein bestehendes Konto klickt auf Allow. Sie kann auch ablehnen. Vor dem Klick wird nichts angelegt.
3. In der Zwischenzeit fragt der Agent alle 5 Sekunden agent_signup_status ab. Nach der Freigabe enthält die Antwort den apiKey — 15 Minuten lang abrufbar, also speichern Sie ihn. Der Schlüssel selbst läuft nicht ab.

Damit darüber keine Gratiskonten massenhaft angelegt oder Postfächer zugespammt werden: Ohne Klick im Posteingang entsteht kein Konto, Wegwerf-E-Mail-Domains werden abgelehnt, Anfragen sind pro Adresse und pro IP begrenzt, und die Antwort ist dieselbe, ob die Adresse schon ein Konto hat oder nicht.

Der gesamte Ablauf mit einer Polling-Schleife:

# 1. Ask for access. Pedra emails the person a confirmation link.
curl -X POST https://app.pedra.ai/api/agent_signup \
  -H "Content-Type: application/json" \
  -d '{ "email": "maria@example.com", "agentName": "Claude Code" }'

# 2. Poll every 5 seconds until status is no longer "pending".
curl -X POST https://app.pedra.ai/api/agent_signup_status \
  -H "Content-Type: application/json" \
  -d '{ "requestId": "REQUEST_ID" }'

Zugriff anfordern

Kein apiKey nötig. Startet eine Anfrage und schickt der Person den Bestätigungslink. Gibt eine requestId zum Abfragen zurück.

400 — keine gültige E-Mail-Adresse, oder code: "disposable_email" (bitte eine dauerhafte Adresse verwenden). 429 rate_limited — 3 Anfragen pro Stunde pro Adresse, 10 pro Tag pro IP, plus eine globale Tagesgrenze; der bereits gesendete Link funktioniert weiter. 503 unavailable — die Registrierung per E-Mail ist nicht verfügbar; die Person kann sich auf app.pedra.ai registrieren und unter Einstellungen → API einen Schlüssel kopieren.

Antwort

{
  "requestId": "hT4kP9wZ2mQ7xR1vB8nC3sD6fG0jL5yE...",
  "status": "pending",
  "expiresAt": "2026-09-30T10:30:00.000Z",
  "pollAfterSeconds": 5,
  "message": "We emailed a link to maria@example.com. Ask the person to open it and confirm (new accounts set a password there). Then poll agent_signup_status with this requestId to get the API key."
}

Agent-Registrierung prüfen

Kein apiKey nötig. Gibt einen von vier Status zurück:

• pending — die Person hat noch nicht geklickt. In 5 Sekunden erneut abfragen.
• approved — mit apiKey, email, newAccount, plan, creditsRemaining und appUrl. Ein neues Konto startet mit Pedras kostenlosen Testcredits. Ist creditsRemaining 0, kommt zusätzlich eine note, dass die Person mit einem Tarif Credits bekommt; geben Sie das weiter. Kostenlose Aufrufe wie das Auflisten von Immobilien funktionieren immer.
• denied — die Person hat abgelehnt. Abfragen beenden.
• expired — niemand hat innerhalb von 30 Minuten geklickt, oder der Schlüssel wurde nicht innerhalb von 15 Minuten nach der Freigabe abgeholt. Beginnen Sie neu mit agent_signup. Eine unbekannte requestId liefert 404.

Antwort

{
  "status": "pending",
  "pollAfterSeconds": 5
}