TechArtikel · REST v1

Foliade API-documentatie

Kennismakings-API: 5 geslaagde conversies in 30 dagen, één tegelijk; 50 MB en 100 pagina’s per PDF, 250 MB aan bewaarde API-pakketten.

MCP is inbegrepen vanaf het gratis abonnement. De volledige API, statistieken, bulkuploads en webhooks zijn inbegrepen vanaf Pro. Zelfstandige HTML-export is inbegrepen vanaf Business.

Open interactieve referentie OpenAPI downloaden

Drager-authenticatie

Maak een sleutel in Foliade → API en verzend deze vervolgens in de header Authorization. De sleutel geeft toegang tot de catalogi van zijn account: bewaar deze in een geheimenbeheerder en nooit in de broncode.

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

Belangrijke levenscyclus

creëer een speciale sleutel voor elke integratie;
kopieer de waarde ervan bij het maken ervan;
zijn laatste oproep volgen;
intrekken zodra het niet langer wordt gebruikt.

Er wordt gereageerd op een ontbrekende, onbekende of ingetrokken sleutel 401.

Eindpunten v1

Methode	Pad	Resultaat
`POST`	`/v1/catalogs`	Converteert een PDF, concept of gepubliceerde versie.
`POST`	`/v1/catalogs/bulk`	Accepteer een openbare bron en start een batch.
`GET`	`/v1/catalogs`	Geeft een overzicht van de catalogi van het account.
`GET`	`/v1/catalogs/{id}`	Geeft de catalogus en de status van de laatste conversie terug.
`POST`	`/v1/catalogs/{id}/publish`	Publiceert een bestaand concept zonder nieuwe conversie of wijziging van de link.
`GET`	`/v1/catalogs/{id}/stats?days=30`	Retourneert metingen, lezers, contacten en paginaweergaven.
`DELETE`	`/v1/catalogs/{id}`	Maakt de publicatie van de catalogus ongedaan zonder accountgegevens te verwijderen.
`GET`	`/v1/me`	Controleert de sleutel, het aanbod en het aantal catalogi.

Publiceer een PDF

Stuur een lichaam multipart/form-data. Alleen fichier is verplicht. publier=0 maakt een concept; publier=1 maakt de link openbaar. Met attendre=1, wacht de query maximaal 300 seconden op conversie voordat een 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"

Veld	Standaard	Beschrijving
`fichier`	—	Kennismakings-API: 50 MB en 100 pagina’s per PDF. Volledige API: 300 MB per PDF.
`remplace`	—	ID van een catalogus in dit account om te vervangen zonder link of beveiliging te wijzigen. Een geslaagde conversie verbruikt één eenheid van het kennismakingsquotum.
`titre`	bestandsnaam	Zichtbare titel van de catalogus.
`langue`	accounttaal	Taalcode ondersteund door de speler.
`publier`	`0`	`1` om de openbare link onmiddellijk te openen.
`attendre`	`1`	`0` om onmiddellijk asynchroon werk te ontvangen.

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

Massaverwerking

De volledige API is inbegrepen vanaf Pro.

Het bulkinvoerpunt ontvangt een openbare HTTP(S)-URL in een JSON-body. De webhook is optioneel. Het antwoord 202 bevat de identificatie van de geaccepteerde batch.

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"
  }'

De bron is een ZIP-archief van maximaal 2 GB, met maximaal 500 pdf's van elk 300 MB. Meldingen gebruiken een permanente wachtrij: na een HTTP-fout worden vijf nieuwe pogingen gepland na 1 minuut, 5 minuten, 15 minuten, 1 uur en 6 uur.

Elke melding bevat een stabiele identificatie en een HMAC-SHA256-handtekening. Haal het ondertekeningsgeheim van uw ruimte op via de Identity API. Controleer de onbewerkte handtekening van de HTTP-tekst, wijs tijdstempels ouder dan vijf minuten af en ontdubbel reeds verwerkte gebeurtenissen. Een rotatie van de applicatiesleutel vernieuwt de geheimen.

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)

Statistieken

Statistieken vereisen Pro.

De periode wordt verzonden met days. De REST API en de gehoste MCP-server accepteren een geheel getal van 1 tot 3650 dagen. Waarden buiten bereik worden geweigerd.

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

Antwoorden en fouten

Status	Betekenis	Actie
`201`	Conversie voltooid.	Gebruik `url` en `id`.
`202`	Conversie of batch geaccepteerd, nog in uitvoering.	Bewaar het geretourneerde identiteitsbewijs.
`400`	De bulkbron is geen geaccepteerde openbare URL.	Geef een toegankelijke HTTP(S)-URL op.
`401`	Sleutel ontbreekt, onbekend of ingetrokken.	Controleer de header of maak een sleutel aan.
`403`	Functie vereist een hoger plan of het account is geschorst.	Controleer de accountrechten.
`404`	Catalogus ontbreekt in geverifieerd account.	Controleer het identiteitsbewijs en de sleutel.
`409`	Conversie bezig, plekken bezet of opslag vol.	Wacht of maak een plek vrij in je account.
`413`	De PDF overschrijdt de limiet voor grootte of pagina’s van je plan.	Verklein of verdeel het document.
`422`	PDF beveiligd, beschadigd of conversie mislukt.	Exporteer een leesbare PDF opnieuw zonder wachtwoord.
`429`	API-quotum of beveiligingslimiet bereikt.	Controleer je quota voordat je opnieuw probeert.

Bescherming tegen misbruik: 60 API-aanroepen per minuut en 10 uploadpogingen per 24 uur, gedeeld met de website en MCP. Fouten tellen mee voor deze daglimiet, niet voor het maandquotum.

Verwijderen of offline halen geeft een geslaagde conversie niet terug. De 5 publicatieplekken worden gedeeld met webuploads. API-concepten en archieven tellen mee voor de 5 bewaarde API-catalogi en 250 MB opslag.

Haal na een 202-antwoord de catalogus op om de conversie te volgen. Het accountantwoord toont resterende kennismakingsquota; het webhookgeheim wordt alleen verstrekt aan Pro en hogere plannen.

API of MCP-server?

De API is geschikt voor een applicatie, backend of redactioneel kanaal. De MCP-server omvat dezelfde bewerkingen met tools die Codex en Claude Code kunnen aanroepen onder gebruikerscontrole.

Het verschil begrijpen tussen MCP en API

Uitvoerbare referentie

De Swagger-documentatie en het OpenAPI-schema worden gegenereerd op basis van de feitelijk geïmplementeerde routes.

Testen in Swagger UI

Wijzigingslog

Versie	Datum	Veranderingen
v1	28 augustus 2026	Openbare documentatie van conversie, batches, statistieken, depublicatie en accountidentiteit.