Quickstart#

The DokKraft public API is a JSON REST API authenticated by a workspace key. Goal of this page: your first PDF in five minutes.

1. Create an API key#

In DokKraft: Settings → API keys (manager/admin role required). The key is displayed once — copy it right away:

dfk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The key carries its workspace scope: it only sees the templates and folders of that workspace.

2. First call: generate a PDF#

Grab a template public_id (studio address bar) then:

curl -X POST "https://dokkraft.blocsland.com/api/v1/templates/{public_id}/pdf" \
  -H "Authorization: Bearer dfk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": {"client.name": "ACME Corp"}}'

Response: the PDF as a stream (inline by default, attachment with "download": true).

3. Archive a numbered document#

To create a document in the workspace (numbering + archiving), use instead:

curl -X POST "https://dokkraft.blocsland.com/api/v1/templates/{public_id}/documents" \
  -H "Authorization: Bearer dfk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "ACME invoice", "data": {"client.name": "ACME Corp"}}'

201 response with the document record (status, number, PDF URL). Two possible rejections: 422 when a template required field is missing ({message, errors} format), 503 pdf_busy when synchronous rendering is saturated (Retry-After header — retry or switch to async=true). Every code is detailed in Errors.

4. Create several documents at once#

As soon as you need more than a few documents, use batches: a single request, asynchronous execution, per-item tracking.

curl -X POST "https://dokkraft.blocsland.com/api/v1/templates/{public_id}/documents/batch" \
  -H "Authorization: Bearer dfk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"name": "Invoice A"}, {"name": "Invoice B"}]}'

202 response with a batch id, then GET /api/v1/batches/{batch_id} to track progress and fetch the PDFs. In production, a webhook can notify you when the batch finishes instead of polling.

Next step#

• Full reference of every endpoint.
• Error codes and quota handling.
• Webhooks: get notified as soon as a PDF is ready, instead of polling.
• Try it live in your workspace's API integration page (the sandbox's "Batch" mode).