TechArtikel · REST v1

Foliade API-Dokumentation

Einstiegs-API: 5 erfolgreiche Konvertierungen in 30 Tagen, jeweils eine gleichzeitig; 50 MB und 100 Seiten pro PDF, 250 MB gespeicherte API-Pakete.

MCP ist bereits im kostenlosen Tarif enthalten. Vollständige API, Statistiken, Massen-Uploads und Webhooks sind ab Pro enthalten. Eigenständiger HTML-Export ist ab Business enthalten.

Interaktive Referenz öffnen Laden Sie OpenAPI herunter

Inhaberauthentifizierung

Erstellen Sie einen Schlüssel in der Foliade → API und senden Sie ihn dann im Header Authorization. Der Schlüssel ermöglicht den Zugriff auf die Kataloge seines Kontos: Bewahren Sie ihn in einem Secrets-Manager und niemals im Quellcode auf.

export FOLIADE_API_KEY="fl_live_your_key"
curl https://foliade.gekkode.com/v1/me \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}"

Schlüssellebenszyklus

Erstellen Sie für jede Integration einen eigenen Schlüssel.
Kopieren Sie seinen Wert, wenn Sie ihn erstellen.
seinen letzten Anruf überwachen;
widerrufen, sobald es nicht mehr verwendet wird.

Auf einen fehlenden, unbekannten oder widerrufenen Schlüssel wird reagiert 401.

Endpunkte v1

Methode	Pfad	Ergebnis
`POST`	`/v1/catalogs`	Konvertiert ein PDF, einen Entwurf oder eine veröffentlichte Datei.
`POST`	`/v1/catalogs/bulk`	Akzeptieren Sie eine öffentliche Quelle und starten Sie einen Batch.
`GET`	`/v1/catalogs`	Listet die Kataloge des Kontos auf.
`GET`	`/v1/catalogs/{id}`	Gibt den Katalog und den Status seiner letzten Konvertierung zurück.
`POST`	`/v1/catalogs/{id}/publish`	Veröffentlicht einen vorhandenen Entwurf ohne erneute Konvertierung oder Änderung des Links.
`GET`	`/v1/catalogs/{id}/stats?days=30`	Gibt Messwerte, Leser, Kontakte und Seitenaufrufe zurück.
`DELETE`	`/v1/catalogs/{id}`	Hebt die Veröffentlichung des Katalogs auf, ohne die Kontodaten zu löschen.
`GET`	`/v1/me`	Prüft den Schlüssel, das Angebot und die Anzahl der Kataloge.

Veröffentlichen Sie ein PDF

Schicken Sie eine Leiche multipart/form-data. Allein fichier ist Pflicht. publier=0 erstellt einen Entwurf; publier=1 macht den Link öffentlich. Mit attendre=1, wartet die Abfrage bis zu 300 Sekunden auf die Konvertierung, bevor sie a rendert 202.

curl -X POST https://foliade.gekkode.com/v1/catalogs \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}" \
  -F "[email protected];type=application/pdf" \
  -F "titre=Catalogue été 2026" \
  -F "langue=fr" \
  -F "publier=1" \
  -F "attendre=1"

Feld	Standard	Beschreibung
`fichier`	—	Einstiegs-API: 50 MB und 100 Seiten pro PDF. Vollständige API: 300 MB pro PDF.
`remplace`	—	Kennung eines zu ersetzenden Katalogs dieses Kontos, ohne Link oder Schutz zu ändern. Eine erfolgreiche Konvertierung verbraucht eine Einheit des Einstiegskontingents.
`titre`	Dateiname	Sichtbarer Titel des Katalogs.
`langue`	Kontosprache	Vom Player unterstützter Sprachcode.
`publier`	`0`	`1` um den öffentlichen Link sofort zu öffnen.
`attendre`	`1`	`0` um sofort asynchrone Arbeit zu erhalten.

{
  "id": "abc123",
  "url": "https://foliade.gekkode.com/c/abc123",
  "etat": "public",
  "pages": 24,
  "duree_s": 8.4,
  "texte_indexe": true
}

Massenverarbeitung

Die vollständige API ist ab Pro enthalten.

Der Masseneinstiegspunkt empfängt eine öffentliche HTTP(S)-URL in einem JSON-Body. Der Webhook ist optional. Die Antwort 202 enthält die Kennung der akzeptierten Charge.

curl -X POST https://foliade.gekkode.com/v1/catalogs/bulk \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "https://exemple.fr/catalogues.zip",
    "webhook": "https://exemple.fr/webhooks/foliade"
  }'

Als Quelle dient ein ZIP-Archiv von bis zu 2 GB, mit maximal 500 PDFs à 300 MB. Benachrichtigungen verwenden eine dauerhafte Warteschlange: Nach einem HTTP-Fehler sind fünf Wiederholungsversuche nach 1 Minute, 5 Minuten, 15 Minuten, 1 Stunde und 6 Stunden geplant.

Jede Benachrichtigung enthält eine stabile Kennung und eine HMAC-SHA256-Signatur. Rufen Sie das Signaturgeheimnis Ihres Spaces über die Identity API ab. Überprüfen Sie die rohe HTTP-Body-Signatur, lehnen Sie Zeitstempel ab, die älter als fünf Minuten sind, und deduplizieren Sie bereits verarbeitete Ereignisse. Eine Rotation des Anwendungsschlüssels erneuert die Geheimnisse.

GET /v1/me → webhook_signing_secret
X-Foliade-Event-Id: event_id
X-Foliade-Signature: t=timestamp,v1=signature
signature = HMAC-SHA256(webhook_signing_secret, timestamp + "." + raw_body)

Statistiken

Statistiken erfordern Pro.

Der Zeitraum wird mit übermittelt days. Die REST-API und der gehostete MCP-Server akzeptieren eine Ganzzahl von 1 bis 3650 Tagen. Werte außerhalb des Bereichs werden abgelehnt.

curl "https://foliade.gekkode.com/v1/catalogs/abc123/stats?days=30" \
  -H "Authorization: Bearer ${FOLIADE_API_KEY}"

Antworten und Fehler

Status	Bedeutung	Aktion
`201`	Konvertierung abgeschlossen.	Benutzen `url` und `id`.
`202`	Konvertierung oder Batch akzeptiert, noch in Bearbeitung.	Bewahren Sie den zurückgegebenen Ausweis auf.
`400`	Die Massenquelle ist keine akzeptierte öffentliche URL.	Geben Sie eine zugängliche HTTP(S)-URL an.
`401`	Schlüssel fehlt, ist unbekannt oder widerrufen.	Überprüfen Sie den Header oder erstellen Sie einen Schlüssel.
`403`	Funktion erfordert einen höheren Plan oder das Konto ist gesperrt.	Prüfen Sie die Kontoberechtigungen.
`404`	Katalog fehlt im authentifizierten Konto.	Überprüfen Sie den Ausweis und den Schlüssel.
`409`	Konvertierung läuft, Plätze belegt oder Speicher voll.	Warten Sie oder geben Sie einen Platz im Konto frei.
`413`	Die PDF überschreitet das Größen- oder Seitenlimit Ihres Plans.	Verkleinern oder teilen Sie das Dokument.
`422`	PDF geschützt, beschädigt oder Konvertierung fehlgeschlagen.	Exportieren Sie ein lesbares PDF ohne Passwort erneut.
`429`	API-Kontingent oder Schutzlimit erreicht.	Prüfen Sie vor dem nächsten Versuch Ihre Kontingente.

Missbrauchsschutz: 60 API-Aufrufe pro Minute und 10 Uploadversuche pro 24 Stunden, gemeinsam mit Website und MCP. Fehler zählen zum Tageslimit, nicht zum monatlichen Kontingent.

Löschen oder Depublizieren erstattet keine erfolgreiche Konvertierung. Die 5 Veröffentlichungsplätze werden mit Web-Uploads geteilt. API-Entwürfe und Archive zählen zu den 5 gespeicherten API-Katalogen und 250 MB Speicher.

Rufen Sie nach einer 202-Antwort den Katalog ab, um die Konvertierung zu verfolgen. Die Kontoantwort zeigt verbleibende Einstiegskontingente; das Webhook-Geheimnis erhalten nur Pro und höhere Pläne.

API oder MCP-Server?

Die API eignet sich für eine Anwendung, ein Backend oder einen Redaktionskanal. Der MCP-Server umschließt dieselben Vorgänge mit Tools, die Codex und Claude Code unter Benutzersteuerung aufrufen können.

Den Unterschied zwischen MCP und API verstehen

Ausführbare Referenz

Die Swagger-Dokumentation und das OpenAPI-Schema werden aus den tatsächlich bereitgestellten Routen generiert.

Testen Sie in Swagger UI

Änderungsprotokoll

Version	Datum	Änderungen
v1	28. August 2026	Öffentliche Dokumentation von Konvertierung, Batches, Statistiken, Aufheben der Veröffentlichung und Kontoidentität.