Overview

Dockyfy is a template-based image and PDF generation platform. You design templates once in our visual drag-and-drop editor, then call the API with your JSON data to generate thousands of unique, branded assets programmatically.

Each template contains canvas objects (text, images, shapes) with named variable slots. When you call the API, you pass override values for those variables — the engine renders a pixel-perfect asset in milliseconds.

All requests and responses use application/json unless otherwise noted.

Authentication

Dockyfy supports two authentication methods depending on your use case.

API Key (Recommended for integrations)

Use your dk_-prefixed API key in the X-Api-Key header. Keys are created in your dashboard under API Keys and shown only once at creation time — store them securely.

X-Api-Key: dk_live_xxxxxxxxxxxxxxxx

Bearer JWT (Dashboard / OAuth flows)

For browser-based or OAuth flows, use the JWT token returned from POST /api/auth/login. This method is used automatically by the Dockyfy dashboard.

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Encrypted Payload Envelope (API Key routes only)

All requests and responses on X-Api-Key endpoints use AES-256-GCM encryption. Your raw JSON body must be encrypted and wrapped in this envelope:

{
  "v":    1,
  "uid":  "your-user-uuid",
  "iv":   "base64-encoded-12-byte-nonce",
  "tag":  "base64-encoded-16-byte-auth-tag",
  "data": "base64-encoded-ciphertext"
}

The encryption key is derived from your user ID and API key secret using HKDF-SHA256 — it is never stored. Official SDK helpers handle encryption automatically. See our SDK for implementation details.

Quick Start

Generate your first image in under 2 minutes.

curl -X POST https://api.dockyfy.com/api/templates/{templateId}/generate \
  -H "X-Api-Key: dk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "png",
    "overrides": [
      { "variableKey": "name", "text": "Jane Smith" },
      { "variableKey": "date", "text": "March 29, 2026" }
    ]
  }'

Response — 200 OK

{
  "generationId": "550e8400-e29b-41d4-a716-446655440000",
  "outputUrl":    "https://cdn.dockyfy.com/gen/2026/03/abc123.png",
  "format":       "png",
  "templateId":   "your-template-id",
  "creditsUsed":  1,
  "createdAt":    "2026-03-29T12:00:00Z"
}

Templates

Templates define the visual layout. Create and publish them in the Dockyfy editor, then reference them by ID in API calls.

Generate

The core production endpoint. Call it with a published template ID and your override data to receive a generated image or PDF URL.

Bulk Generation

Submit a JSON array of rows to generate hundreds of images or PDFs in a single API call. The job runs asynchronously — poll for status or use Webhooks to be notified on completion.

[
  { "name": "Alice Johnson",  "date": "March 29, 2026", "score": "92%" },
  { "name": "Bob Williams",   "date": "March 29, 2026", "score": "87%" },
  { "name": "Carol Martinez", "date": "March 29, 2026", "score": "95%" }
]

API Keys

Manage your dk_-prefixed API keys programmatically. A raw key is shown only once on creation — Dockyfy stores only a SHA-256 hash.

Webhooks

Receive real-time HTTP POST notifications when generation jobs complete, credits run low, or bulk jobs finish. Dockyfy delivers to your HTTPS endpoint with 3 automatic retry attempts on failure.

Available Events

HMAC Signature Verification

Every webhook delivery includes an X-Dockyfy-Signature header. Always verify this before processing the payload to ensure requests are authentic.

const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');
  // Constant-time comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signatureHeader)
  );
}

Webhook Endpoints

Credits & Billing

Every generation costs 1 credit. Credits are included in your plan and can be purchased as add-on packs at any time. Free accounts start with 50 credits.

Variables Guide

Variables let you inject dynamic content into templates at generation time. You define variable names in the template editor, then pass override values via the API.

How to Define Variables

1. Open the template editor and click any text, image, or shape object.
2. In the Properties panel, set a Variable Name (e.g. recipient_name).
3. The object's default content is used when no override is provided.
4. When calling the API, pass the variable name in overrides[].variableKey.

Override Properties by Object Type

Example Override Array

[
  { "variableKey": "recipient_name",  "text": "Jane Smith" },
  { "variableKey": "issue_date",      "text": "March 29, 2026" },
  { "variableKey": "badge_color",     "fill": "#6366f1" },
  { "variableKey": "profile_photo",   "src":  "https://cdn.example.com/jane.jpg" },
  { "variableKey": "score_text",      "text": "92%", "fontSize": 48, "fill": "#22c55e" }
]

Error Codes

All error responses return a structured JSON body:

{
  "type":    "https://tools.ietf.org/html/rfc9110",
  "title":   "Not Found",
  "status":  404,
  "detail":  "Template '550e8400-e29b-...' not found or not published.",
  "traceId": "00-abc123def456..."
}

Validation errors (400) include a field-level errors map:

{
  "status": 400,
  "title":  "One or more validation errors occurred.",
  "errors": {
    "format":     [ "'format' must be one of: png, jpg, pdf" ],
    "templateId": [ "'templateId' must not be empty." ]
  }
}

Code Examples

Full working examples for common use cases across popular languages and platforms.

Login + List Templates + Generate

// Node.js 18+ (built-in fetch)

const BASE    = 'https://api.dockyfy.com';
const API_KEY = 'dk_live_your_api_key';

// List templates (JWT)
async function listTemplates(accessToken) {
  const res = await fetch(`${BASE}/api/templates`, {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  });
  return res.json();
}

// Generate image (API key)
async function generate(templateId, overrides) {
  const res = await fetch(`${BASE}/api/templates/${templateId}/generate`, {
    method: 'POST',
    headers: { 'X-Api-Key': API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ format: 'png', overrides })
  });
  if (!res.ok) throw new Error(`Generate failed: ${res.status}`);
  return res.json();
}

// Submit bulk job (JWT)
async function submitBulk(accessToken, templateId, rows) {
  const res = await fetch(`${BASE}/api/bulk-jobs`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ templateId, format: 'png', rowsJson: JSON.stringify(rows) })
  });
  return res.json(); // { jobId, status: 'Queued' }
}

Overview

Dockyfy is a template-based image and PDF generation platform. You design templates once in our visual drag-and-drop editor, then call the API with your JSON data to generate thousands of unique, branded assets programmatically.

Each template contains canvas objects (text, images, shapes) with named variable slots. When you call the API, you pass override values for those variables — the engine renders a pixel-perfect asset in milliseconds.

All requests and responses use application/json unless otherwise noted.

Authentication

Dockyfy supports two authentication methods depending on your use case.

API Key (Recommended for integrations)

Use your dk_-prefixed API key in the X-Api-Key header. Keys are created in your dashboard under API Keys and shown only once at creation time — store them securely.

X-Api-Key: dk_live_xxxxxxxxxxxxxxxx

Bearer JWT (Dashboard / OAuth flows)

For browser-based or OAuth flows, use the JWT token returned from POST /api/auth/login. This method is used automatically by the Dockyfy dashboard.

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Encrypted Payload Envelope (API Key routes only)

All requests and responses on X-Api-Key endpoints use AES-256-GCM encryption. Your raw JSON body must be encrypted and wrapped in this envelope:

{
  "v":    1,
  "uid":  "your-user-uuid",
  "iv":   "base64-encoded-12-byte-nonce",
  "tag":  "base64-encoded-16-byte-auth-tag",
  "data": "base64-encoded-ciphertext"
}

The encryption key is derived from your user ID and API key secret using HKDF-SHA256 — it is never stored. Official SDK helpers handle encryption automatically. See our SDK for implementation details.

Quick Start

Generate your first image in under 2 minutes.

curl -X POST https://api.dockyfy.com/api/templates/{templateId}/generate \
  -H "X-Api-Key: dk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "png",
    "overrides": [
      { "variableKey": "name", "text": "Jane Smith" },
      { "variableKey": "date", "text": "March 29, 2026" }
    ]
  }'

Response — 200 OK

{
  "generationId": "550e8400-e29b-41d4-a716-446655440000",
  "outputUrl":    "https://cdn.dockyfy.com/gen/2026/03/abc123.png",
  "format":       "png",
  "templateId":   "your-template-id",
  "creditsUsed":  1,
  "createdAt":    "2026-03-29T12:00:00Z"
}

Templates

Templates define the visual layout. Create and publish them in the Dockyfy editor, then reference them by ID in API calls.

Generate

The core production endpoint. Call it with a published template ID and your override data to receive a generated image or PDF URL.

Bulk Generation

Submit a JSON array of rows to generate hundreds of images or PDFs in a single API call. The job runs asynchronously — poll for status or use Webhooks to be notified on completion.

[
  { "name": "Alice Johnson",  "date": "March 29, 2026", "score": "92%" },
  { "name": "Bob Williams",   "date": "March 29, 2026", "score": "87%" },
  { "name": "Carol Martinez", "date": "March 29, 2026", "score": "95%" }
]

API Keys

Manage your dk_-prefixed API keys programmatically. A raw key is shown only once on creation — Dockyfy stores only a SHA-256 hash.

Webhooks

Receive real-time HTTP POST notifications when generation jobs complete, credits run low, or bulk jobs finish. Dockyfy delivers to your HTTPS endpoint with 3 automatic retry attempts on failure.

Available Events

HMAC Signature Verification

Every webhook delivery includes an X-Dockyfy-Signature header. Always verify this before processing the payload to ensure requests are authentic.

const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');
  // Constant-time comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signatureHeader)
  );
}

Webhook Endpoints

Credits & Billing

Every generation costs 1 credit. Credits are included in your plan and can be purchased as add-on packs at any time. Free accounts start with 50 credits.

Variables Guide

Variables let you inject dynamic content into templates at generation time. You define variable names in the template editor, then pass override values via the API.

How to Define Variables

1. Open the template editor and click any text, image, or shape object.
2. In the Properties panel, set a Variable Name (e.g. recipient_name).
3. The object's default content is used when no override is provided.
4. When calling the API, pass the variable name in overrides[].variableKey.

Override Properties by Object Type

Example Override Array

[
  { "variableKey": "recipient_name",  "text": "Jane Smith" },
  { "variableKey": "issue_date",      "text": "March 29, 2026" },
  { "variableKey": "badge_color",     "fill": "#6366f1" },
  { "variableKey": "profile_photo",   "src":  "https://cdn.example.com/jane.jpg" },
  { "variableKey": "score_text",      "text": "92%", "fontSize": 48, "fill": "#22c55e" }
]

Error Codes

All error responses return a structured JSON body:

{
  "type":    "https://tools.ietf.org/html/rfc9110",
  "title":   "Not Found",
  "status":  404,
  "detail":  "Template '550e8400-e29b-...' not found or not published.",
  "traceId": "00-abc123def456..."
}

Validation errors (400) include a field-level errors map:

{
  "status": 400,
  "title":  "One or more validation errors occurred.",
  "errors": {
    "format":     [ "'format' must be one of: png, jpg, pdf" ],
    "templateId": [ "'templateId' must not be empty." ]
  }
}

Code Examples

Full working examples for common use cases across popular languages and platforms.

Login + List Templates + Generate

// Node.js 18+ (built-in fetch)

const BASE    = 'https://api.dockyfy.com';
const API_KEY = 'dk_live_your_api_key';

// List templates (JWT)
async function listTemplates(accessToken) {
  const res = await fetch(`${BASE}/api/templates`, {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  });
  return res.json();
}

// Generate image (API key)
async function generate(templateId, overrides) {
  const res = await fetch(`${BASE}/api/templates/${templateId}/generate`, {
    method: 'POST',
    headers: { 'X-Api-Key': API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ format: 'png', overrides })
  });
  if (!res.ok) throw new Error(`Generate failed: ${res.status}`);
  return res.json();
}

// Submit bulk job (JWT)
async function submitBulk(accessToken, templateId, rows) {
  const res = await fetch(`${BASE}/api/bulk-jobs`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ templateId, format: 'png', rowsJson: JSON.stringify(rows) })
  });
  return res.json(); // { jobId, status: 'Queued' }
}