TechArticle · REST v1

Foliade API Documentation

Discovery API: 5 successful conversions in 30 days, one at a time; 50 MB and 100 pages per PDF, 250 MB of stored API packages.

MCP is included from the free plan. The full API, analytics, bulk uploads and webhooks are included from Pro. Standalone HTML export is included from Business.

Open interactive reference Download OpenAPI

Bearer Authentication

Create a key in Foliade → API, then send it in the Authorization header. The key grants access to the account's catalogues: keep it in a secrets manager, never in source code.

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

Key life cycle

create a dedicated key for each integration;
copy its value when creating it;
monitor its most recent use;
revoke it as soon as it is no longer used.

A missing, unknown, or revoked key receives a 401.

Endpoints v1

Method	Path	Result
`POST`	`/v1/catalogs`	Converts a PDF, draft or published.
`POST`	`/v1/catalogs/bulk`	Accept a public source and start a batch.
`GET`	`/v1/catalogs`	Lists the account's catalogs.
`GET`	`/v1/catalogs/{id}`	Returns the catalogue and its latest conversion status.
`POST`	`/v1/catalogs/{id}/publish`	Publishes an existing draft without reconverting it or changing its link.
`GET`	`/v1/catalogs/{id}/stats?days=30`	Returns readings, readers, contacts and page views.
`DELETE`	`/v1/catalogs/{id}`	Unpublishes the catalog without deleting account data.
`GET`	`/v1/me`	Checks the key, the offer and the number of catalogs.

Publish a PDF

Send a multipart/form-data body. Only fichier is required. publier=0 creates a draft; publier=1 makes the link public. With attendre=1, the query waits for conversion for up to 300 seconds before rendering a 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"

Field	Default	Description
`fichier`	—	Discovery API: 50 MB and 100 pages per PDF. Full API: 300 MB per PDF.
`remplace`	—	ID of a catalogue in this account to replace without changing its link or protection. A successful conversion uses one discovery quota unit.
`titre`	file name	Visible title of the catalog.
`langue`	account language	Language code supported by the player.
`publier`	`0`	`1` to immediately open the public link.
`attendre`	`1`	`0` to immediately receive asynchronous work.

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

Mass processing

The full API is included from Pro.

The batch endpoint receives a public HTTP(S) URL in a JSON body. The webhook is optional. The 202 response contains the accepted batch ID.

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

The source is a ZIP archive of up to 2 GB, with at most 500 PDFs of 300 MB each. Notifications use a persistent queue: after an HTTP failure, five retries are scheduled after 1 minute, 5 minutes, 15 minutes, 1 hour and 6 hours.

Each notification includes a stable identifier and an HMAC-SHA256 signature. Retrieve your space's signing secret via the Identity API. Verify the raw HTTP body signature, reject timestamps older than five minutes, and deduplicate already processed events. A rotation of the application key renews the secrets.

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)

Statistics

Analytics require Pro.

The period is transmitted with days. The REST API and hosted MCP server accept an integer from 1 to 3650 days. Values out of range are refused.

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

Responses and errors

Status	Meaning	Action
`201`	Conversion complete.	Use `url` and `id`.
`202`	Conversion or batch accepted, still in progress.	Keep the returned ID.
`400`	The bulk source is not an accepted public URL.	Provide an accessible HTTP(S) URL.
`401`	Key missing, unknown or revoked.	Check the header or create a key.
`403`	Feature requires a higher plan or the account is suspended.	Check the account permissions.
`404`	Catalog missing from authenticated account.	Check the ID and key.
`409`	Conversion in progress, slots occupied or storage full.	Wait or free a slot in your account.
`413`	The PDF exceeds your plan's size or page limit.	Reduce or divide the document.
`422`	PDF protected, corrupted or conversion failed.	Re-export a readable PDF without a password.
`429`	API quota or protection limit reached.	Check your quotas before retrying.

Abuse protection: 60 API calls per minute and 10 upload attempts per 24 hours, shared with the website and MCP. Failures count towards this daily limit, not the monthly quota.

Deleting or unpublishing does not refund a successful conversion. The 5 publication slots are shared with web uploads. API drafts and archives count towards the 5 stored API catalogues and 250 MB of storage.

After a 202 response, retrieve the catalogue to track conversion. The account identity response shows remaining discovery quotas; the webhook secret is only provided for Pro and higher plans.

API or MCP server?

The API suits an application, backend, or publishing workflow. The MCP server wraps the same operations in tools that Codex and Claude Code can call under user control.

Understanding the difference between MCP and API

Executable reference

The Swagger documentation and OpenAPI schema are generated from the routes currently deployed.

Test in Swagger UI

Changelog

Version	Date	Changes
v1	August 28, 2026	Public documentation of conversion, batches, statistics, unpublishing, and account identity.