DocitAPI Reference
Get API key
Docit API Reference

Generate documents from templates with a server-side API.

List templates, generate PNG or PDF output, merge multiple templates into one PDF, and process row-based bulk jobs using a Docit API key.

Base path

/api/documents

Authentication

Bearer API key

Outputs

PNG · PDF

Quick start

Make your first request

Set the deployment URL and API key, confirm template access, then generate a document.

1. Environment
export DOCIT_BASE_URL="https://docit.gatekod.com/"
export DOCIT_API_KEY="dmnt_YOUR_API_KEY"
2. List templates
curl --request GET \
  "$DOCIT_BASE_URL/api/documents/templates?page=1&limit=10" \
  --header "Authorization: Bearer $DOCIT_API_KEY"
3. Generate a PDF
curl --request POST \
  "$DOCIT_BASE_URL/api/documents/generate" \
  --header "Authorization: Bearer $DOCIT_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "templateId": "64f1c2a9b8e7d6c5a4b3c2d1",
    "output": "pdf",
    "payload": {
      "client": {
        "name": "Ada Lovelace"
      },
      "course": "Analytical Engines"
    }
  }'
Authentication

Send one API key with every request

API keys begin with dmnt_ and should be treated like passwords. Keep them on a trusted server and never expose them in browser code, logs, URLs, or public repositories.

Recommended
Authorization: Bearer dmnt_YOUR_API_KEY
Compatible
x-api-key: dmnt_YOUR_API_KEY
Compatible
api-key: dmnt_YOUR_API_KEY
Conventions

Requests, identifiers, and response envelopes

All customer-facing routes are available under /api/documents. Send request bodies as application/json and use the returned fileUrl to download generated files.

Dates use ISO 8601 UTC format. Treat template and generation-job identifiers as opaque strings.

  • JSON and URL-encoded request bodies have a maximum size of 25 MB.
  • Every response includes success and message; data is included when details are available.
  • Use HTTP status codes and structured response fields for application logic. Do not match message text.
  • Replace the example hostname with the base URL for your deployment.
Placeholder data

Map template placeholders to payload values

Templates can contain placeholders such as {client.name}. Provide replacement values in payload; data remains available as a compatibility alias.

For single-document and bulk generation, dotted top-level keys are converted to nested values automatically.

  • When payload and data are both present, payload takes precedence.
  • A required value is considered missing when it is absent, null, undefined, empty, or whitespace-only.
  • Numeric 0 and boolean false are valid placeholder values.
  • Signature, QR-code, and image-placeholder objects use specialized rendering and may not participate in standard text-placeholder validation.
Schema example
{
  "payload": {
    "client.name": "Ada Lovelace",
    "course": "Analytical Engines"
  }
}
Endpoints

HTTP endpoints

Use the same response envelope across template discovery, single generation, combined PDFs, and bulk generation.

HEADER

Authenticate API requests

Authorization

Send a Docit API key with every document API request. Keys begin with dmnt_ and must be protected like passwords.

  • Use Authorization: Bearer dmnt_YOUR_API_KEY whenever possible.
  • The x-api-key and api-key headers are supported for compatibility.
  • When multiple credentials are sent, the server checks x-api-key first, then a dmnt_ Bearer token, then api-key.
  • Send exactly one API-key header with each request.
  • A missing, malformed, unknown, or revoked key returns HTTP 401.
  • Keep keys in trusted server-side code. Never expose them in URLs, browser code, logs, screenshots, or public repositories.
Request
GET /api/documents/templates HTTP/1.1
Authorization: Bearer dmnt_YOUR_API_KEY
Response
{
  "success": true,
  "message": "Templates fetched successfully",
  "data": {
    "templates": []
  }
}
GET

List document templates

/api/documents/templates

Returns the API-key user's active templates, ordered by most recently updated.

  • page accepts a positive integer and defaults to 1.
  • limit accepts a positive integer, defaults to 10, and cannot exceed 100.
  • Invalid or non-positive page and limit values use their defaults.
  • search performs a case-insensitive substring match against template names.
  • q is an alias for search. When both are supplied, search takes precedence.
  • When neither page nor limit is supplied, all matching templates are returned and pagination is omitted.
  • Set includeTemplateJson to the literal value true to include full template JSON in each result.
Request
GET /api/documents/templates?page=1&limit=10&search=certificate HTTP/1.1
Authorization: Bearer dmnt_YOUR_API_KEY
Response
{
  "success": true,
  "message": "Templates fetched successfully",
  "data": {
    "templates": [
      {
        "id": "64f1c2a9b8e7d6c5a4b3c2d1",
        "name": "Course certificate",
        "status": "active",
        "isPublic": false,
        "isAiGenerated": false,
        "placeholders": [
          "client.name",
          "course"
        ],
        "previewDataUrl": "https://cdn.example.com/preview.png",
        "previewUrls": [
          "https://cdn.example.com/preview.png"
        ],
        "pageCount": 1,
        "createdAt": "2026-09-01T12:00:00.000Z",
        "updatedAt": "2026-09-04T12:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 1,
      "totalPages": 1,
      "hasNextPage": false,
      "hasPreviousPage": false
    }
  }
}
GET

Fetch one template

/api/documents/templates/:templateId

Returns a complete template owned by the API-key user or a template marked as public.

  • Treat templateId as an opaque 24-character identifier.
  • Private templates are accessible only to their owner.
  • API-key users can fetch public templates owned by another user.
  • Invalid, deleted, inaccessible, and unknown template IDs return HTTP 404.
  • A public template owned by another user cannot currently be generated using its templateId.
  • When authorized to do so, pass the returned templateJson as an inline template instead.
Request
GET /api/documents/templates/64f1c2a9b8e7d6c5a4b3c2d1 HTTP/1.1
Authorization: Bearer dmnt_YOUR_API_KEY
Response
{
  "success": true,
  "message": "Template fetched successfully",
  "data": {
    "template": {
      "id": "64f1c2a9b8e7d6c5a4b3c2d1",
      "name": "Course certificate",
      "status": "active",
      "isPublic": false,
      "isAiGenerated": false,
      "templateJson": {
        "name": "Course certificate",
        "version": "1.0",
        "editor": "fabric",
        "page": {
          "width": 1123,
          "height": 794,
          "orientation": "landscape",
          "unit": "px"
        },
        "fabricJson": {
          "version": "7.3.1",
          "objects": []
        },
        "pages": [],
        "placeholders": [
          "client.name",
          "course"
        ],
        "assets": []
      },
      "placeholders": [
        "client.name",
        "course"
      ],
      "createdAt": "2026-09-01T12:00:00.000Z",
      "updatedAt": "2026-09-04T12:00:00.000Z"
    }
  }
}
POST

Generate one document

/api/documents/generate

Renders a saved or inline template as PNG or PDF using the supplied placeholder values.

  • Provide either templateId or template.
  • When both templateId and template are supplied, templateId takes precedence.
  • output accepts png or pdf and defaults to png.
  • Use payload for placeholder values; data is supported as a compatibility alias.
  • When payload and data are both supplied, payload takes precedence.
  • Dotted top-level payload keys are normalized into nested values.
  • POST /api/documents/generation is a compatibility alias; new clients should use /api/documents/generate.
  • Missing required values return HTTP 422 with requiredPlaceholders and missingFields.
  • Download the finished document from certificate.fileUrl.
Request
POST /api/documents/generate HTTP/1.1
Authorization: Bearer dmnt_YOUR_API_KEY
Content-Type: application/json
Body
{
  "templateId": "64f1c2a9b8e7d6c5a4b3c2d1",
  "output": "pdf",
  "payload": {
    "client.name": "Ada Lovelace",
    "course": "Analytical Engines"
  }
}
Response
{
  "success": true,
  "message": "Certificate generated",
  "data": {
    "certificate": {
      "id": "66d2c2a9b8e7d6c5a4b3c2d1",
      "output": "pdf",
      "fileName": "documint-cert-a1b2c3d4e5f6.pdf",
      "fileUrl": "https://cdn.example.com/documents/generated.pdf",
      "mimeType": "application/pdf",
      "mimeType": "application/pdf",
      "recipientName": "Ada Lovelace",
      "createdAt": "2026-09-05T12:00:00.000Z",
      "resolvedTemplate": {},
      "htmlPreview": "<!doctype html>..."
    }
  }
}
POST

Generate from inline template JSON

/api/documents/generate

Renders trusted template JSON for one request without saving it as a template.

  • Inline templates apply only to the current request and are not saved.
  • Most integrations should prefer saved templateId values.
  • page.width and page.height must be positive numbers when provided.
  • A template may contain top-level fabricJson, pages, or both.
  • Fabric object properties and custom Docit metadata are preserved by request validation.
  • Construct and submit inline templates only from trusted server-side code.
Request
POST /api/documents/generate HTTP/1.1
Authorization: Bearer dmnt_YOUR_API_KEY
Content-Type: application/json
Body
{
  "output": "png",
  "template": {
    "name": "Inline certificate",
    "version": "1.0",
    "editor": "fabric",
    "page": {
      "width": 1123,
      "height": 794,
      "orientation": "landscape",
      "unit": "px"
    },
    "fabricJson": {
      "version": "7.3.1",
      "background": "#ffffff",
      "objects": [
        {
          "type": "textbox",
          "left": 100,
          "top": 100,
          "width": 900,
          "fontSize": 42,
          "text": "Awarded to {client.name}"
        }
      ]
    },
    "pages": [],
    "placeholders": [
      "client.name"
    ],
    "assets": []
  },
  "payload": {
    "client.name": "Ada Lovelace"
  }
}
Response
{
  "success": true,
  "message": "Certificate generated",
  "data": {
    "certificate": {
      "id": "66d2c2a9b8e7d6c5a4b3c2d2",
      "output": "png",
      "fileUrl": "https://cdn.example.com/documents/generated.png",
      "mimeType": "image/png"
    }
  }
}
POST

Merge multiple templates into one PDF

/api/documents/generate

Combines multiple template-and-payload pairs into a single PDF.

  • documents is the preferred request shape.
  • A top-level array, templates array, or items array is also accepted for compatibility.
  • At least one item is required.
  • Each item requires templateId or template and payload or data.
  • Per-item output formats are not supported.
  • The endpoint always returns one combined PDF.
  • certificate and document contain the same generated-document data.
  • If any item is missing required values, the entire request returns HTTP 422.
  • For validation errors, data.errors identifies each invalid item by its zero-based index.
Request
POST /api/documents/generate HTTP/1.1
Authorization: Bearer dmnt_YOUR_API_KEY
Content-Type: application/json
Body
{
  "output": "pdf",
  "documents": [
    {
      "templateId": "64f1c2a9b8e7d6c5a4b3c2d1",
      "payload": {
        "client.name": "Ada Lovelace"
      }
    },
    {
      "templateId": "64f1c2a9b8e7d6c5a4b3c2d2",
      "payload": {
        "invoice.number": "INV-1001"
      }
    }
  ]
}
Response
{
  "success": true,
  "message": "Certificate generated",
  "data": {
    "document": {
      "id": "66d2c2a9b8e7d6c5a4b3c2d1",
      "output": "pdf",
      "fileName": "documint-document-doc-a1b2c3d4e5f6.pdf",
      "fileUrl": "https://cdn.example.com/documents/combined.pdf",
      "mimeType": "application/pdf",
      "recipientName": "Ada Lovelace",
      "createdAt": "2026-09-05T12:00:00.000Z",
      "documentCount": 2,
      "pageCount": 2,
      "htmlPreview": "<!doctype html>..."
    },
    "certificate": {
      "id": "66d2c2a9b8e7d6c5a4b3c2d1",
      "output": "pdf",
      "fileUrl": "https://cdn.example.com/documents/combined.pdf"
    }
  }
}
POST

Generate documents from rows

/api/documents/generate-bulk

Generates one document per row unless repeating-table grouping combines rows into fewer documents.

  • rows must contain at least one data object.
  • Provide either templateId or template.
  • output accepts png or pdf and defaults to png.
  • Up to 10 resulting documents are processed synchronously.
  • An individual row failure does not fail the entire HTTP request.
  • Always inspect summary.failed and errors in synchronous bulk responses.
  • More than 10 resulting documents are queued; the response includes queued, jobId, status, totalDocuments, and pollUrl.
  • The queue threshold applies after repeating-table grouping.
  • The current job-polling route requires an application session and does not accept API-key authentication.
  • API-key-only integrations should keep bulk requests at 10 resulting documents or fewer.
Request
POST /api/documents/generate-bulk HTTP/1.1
Authorization: Bearer dmnt_YOUR_API_KEY
Content-Type: application/json
Body
{
  "templateId": "64f1c2a9b8e7d6c5a4b3c2d1",
  "output": "pdf",
  "rows": [
    {
      "client.name": "Ada Lovelace",
      "course": "Mathematics"
    },
    {
      "client.name": "Grace Hopper",
      "course": "Computer Science"
    }
  ]
}
Response
{
  "success": true,
  "message": "Bulk certificate generation completed",
  "data": {
    "queued": false,
    "grouped": false,
    "groupBy": "",
    "sourceRows": 2,
    "summary": {
      "total": 2,
      "generated": 2,
      "failed": 0
    },
    "certificates": [
      {
        "id": "66d2c2a9b8e7d6c5a4b3c2d1",
        "output": "pdf",
        "fileUrl": "https://cdn.example.com/documents/ada-lovelace.pdf"
      },
      {
        "id": "66d2c2a9b8e7d6c5a4b3c2d2",
        "output": "pdf",
        "fileUrl": "https://cdn.example.com/documents/grace-hopper.pdf"
      }
    ],
    "errors": []
  }
}
POST

Generate grouped table documents

/api/documents/generate-bulk

Groups repeating-table rows using an explicit group column or one detected from the template and row data.

  • csvOptions.groupBy must exactly match a key in the first row.
  • Without groupBy, the server checks the template's configured key and common invoice or order column names.
  • Each group produces one document payload.
  • The first row supplies document-level fields.
  • Every row in the group populates the repeating source, normally lineItems.
  • Common subtotal, tax, and total fields are computed when absent.
  • If no valid grouping column is available, the API returns HTTP 400 with data.missingColumns.
  • Rows with an empty grouping value are skipped.
  • Compare sourceRows with summary.total when auditing grouped input.
Request
POST /api/documents/generate-bulk HTTP/1.1
Authorization: Bearer dmnt_YOUR_API_KEY
Content-Type: application/json
Body
{
  "templateId": "64f1c2a9b8e7d6c5a4b3c2d1",
  "output": "pdf",
  "csvOptions": {
    "groupBy": "invoice.number"
  },
  "rows": [
    {
      "invoice.number": "INV-1001",
      "customer.name": "Northwind Studio",
      "items.description": "Design consultation",
      "items.amount": "400"
    },
    {
      "invoice.number": "INV-1001",
      "customer.name": "Northwind Studio",
      "items.description": "Implementation",
      "items.amount": "840"
    }
  ]
}
Response
{
  "success": true,
  "message": "Bulk certificate generation completed",
  "data": {
    "queued": false,
    "grouped": true,
    "groupBy": "invoice.number",
    "sourceRows": 2,
    "summary": {
      "total": 1,
      "generated": 1,
      "failed": 0
    },
    "certificates": [
      {
        "id": "66d2c2a9b8e7d6c5a4b3c2d3",
        "output": "pdf",
        "fileUrl": "https://cdn.example.com/documents/inv-1001.pdf"
      }
    ],
    "errors": []
  }
}
Request fields

Common generation fields

These fields are shared across single, combined, and bulk generation shapes.

NameTypeDescription
templateIdstringSaved template identifier. Required unless template is supplied.
templateobjectTrusted inline template JSON. Required unless templateId is supplied.
outputpng | pdfOutput format. Defaults to png; combined document generation always returns PDF.
payloadobjectPreferred field for document placeholder values.
dataobjectCompatibility alias for payload; payload takes precedence.
documentsobject[]Template-and-payload pairs to combine into one PDF.
rowsobject[]One or more flat or nested data objects for bulk generation.
csvOptions.groupBystringExact row key used to group repeating-table rows into documents.
Responses

Handle responses using HTTP status and structured data

Every documented endpoint returns JSON. PNG and PDF files are not returned in the response body; download them from the returned fileUrl.

The message field is intended for people and may change. Client logic should rely on the HTTP status and fields such as success, missingFields, errors, and queued.

  • success is true for HTTP 2xx responses and false for error responses.
  • message provides a human-readable result.
  • data contains endpoint-specific results or error details and may be omitted.
  • Generation responses can be large because they may include resolvedTemplate and htmlPreview.
Schema example
{
  "success": true,
  "message": "Certificate generated",
  "data": {}
}
Errors

HTTP status conventions

Error text can change. Build client logic around HTTP status and stable structured fields such as missingFields, errors, and queued.

StatusMeaningCommon cause
400Invalid requestThe request schema is invalid, rows are empty, or a required grouping column is unavailable.
401Not authenticatedThe API key is missing, malformed, invalid, or revoked.
404Not foundThe requested template is invalid, deleted, inaccessible, or unknown.
422Semantically invalid dataOne or more required placeholder values are missing.
500Server failureAn unexpected rendering, persistence, or service error occurred.
Schema validation error
{
  "success": false,
  "message": "Invalid request body",
  "data": {
    "error": "Invalid request body",
    "details": [
      { "path": "output", "message": "Invalid option: expected one of \"png\"|\"pdf\"" }
    ]
  }
}
Client examples

Server-side integration examples

Rendering can take longer than ordinary JSON requests. Configure a suitable timeout and retry only failures that are safe for your workflow.

JavaScript · Node.js 18+
const baseUrl = process.env.DOCIT_BASE_URL;
const apiKey = process.env.DOCIT_API_KEY;

const response = await fetch(`${baseUrl}/api/documents/generate`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    templateId: "64f1c2a9b8e7d6c5a4b3c2d1",
    output: "pdf",
    payload: {
      "client.name": "Ada Lovelace",
    },
  }),
});

const result = await response.json();

if (!response.ok) {
  throw new Error(`${response.status}: ${result.message}`);
}


console.log(result.data.certificate.fileUrl);
Python
import os
import requests

base_url = os.environ["DOCIT_BASE_URL"]
api_key = os.environ["DOCIT_API_KEY"]

response = requests.post(
    f"{base_url}/api/documents/generate",
    headers={
        "Authorization": f"Bearer {api_key}"
    },
    json={
        "templateId": "64f1c2a9b8e7d6c5a4b3c2d1",
        "output": "pdf",
        "payload": {
            "client.name": "Ada Lovelace"
        },
    },
    timeout=120,
)

response.raise_for_status()

result = response.json()
file_url = result["data"]["certificate"]["fileUrl"]
print(file_url)
Operations

Operational behavior to design around

  • Rate limits and traffic controls depend on the deployment. Handle HTTP 429 responses with bounded exponential backoff.
  • Generation endpoints do not support idempotency keys. Retrying an ambiguous request can create a duplicate document.
  • Retry a timed-out generation request only when duplicate documents are acceptable.
  • Current API routes do not include a version segment.
  • Test documented compatibility aliases against the deployment release used by your integration.
  • API-key requests access only the key owner's data, except for templates explicitly marked public.
  • A saved templateId used for generation must belong to the API-key user.
  • Successful generation stores the document and returns a fileUrl.
  • Generated-file retention and URL lifetime depend on deployment policy.
  • Use API keys only from trusted server-side code.
For API-key-only bulk integrations, keep requests at 10 resulting documents or fewer until the generation-job polling route accepts API keys.
Checklist

Production integration checklist

  1. 1Store the API key in a secrets manager or protected server-side environment variable.
  2. 2Use HTTPS with the Authorization: Bearer header.
  3. 3List templates first, then cache the selected templateId and expected placeholders.
  4. 4Validate payload values locally, including missing, null, empty, and whitespace-only strings.
  5. 5Check both the HTTP status and success in every response.
  6. 6Inspect summary and errors for row-level failures in synchronous bulk responses.
  7. 7Limit API-key-only bulk requests to 10 resulting documents until job polling supports API keys.
  8. 8Assume retries can create duplicate documents.
  9. 9Download or retain fileUrl according to your deployment's retention policy.