Documentation

# Render the built-in invoice template and save the PDF.
# On an error, curl exits non-zero and invoice.pdf holds the JSON error body instead (cat it to read why).
curl -sS "${KTAVLY_API_URL:-https://api.ktavly.com}/v1/render" \
  -H "Authorization: Bearer $KTAVLY_API_KEY" \
  -H "Content-Type: application/json" \
  --fail-with-body -o invoice.pdf \
  -d '{
    "template": "invoice",
    "data": {
      "number": "INV-1001", "issueDate": "2026-10-18", "currency": "USD",
      "from": { "name": "Northwind Studio" },
      "to": { "name": "Lumen Analytics" },
      "items": [{ "description": "Design sprint", "quantity": 1, "unitPrice": 6400 }],
      "taxRate": 8.5
    }
  }'

// Node 18+ (built-in fetch). Run: node quickstart.mjs
import { writeFile } from 'node:fs/promises';

const API = process.env.KTAVLY_API_URL ?? 'https://api.ktavly.com';
const res = await fetch(`${API}/v1/render`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.KTAVLY_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    template: 'invoice-he',
    data: {
      documentType: 'tax_invoice', number: '20261042', issueDate: '2026-10-18',
      seller: { name: 'סטודיו גפן בע״מ', businessId: '514238765' },
      customer: { name: 'אורן מערכות מידע בע״מ' },
      items: [{ description: 'עיצוב ממשק משתמש', quantity: 1, unitPrice: 18500 }],
    },
  }),
});
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}
await writeFile('invoice-he.pdf', Buffer.from(await res.arrayBuffer()));
console.log(`Saved invoice-he.pdf (${res.headers.get('x-pages')} page, ${res.headers.get('x-usage-remaining')} left this month)`);

# Python 3.8+ with requests (pip install requests). Run: python quickstart.py
import os
import requests

API = os.environ.get("KTAVLY_API_URL", "https://api.ktavly.com")
r = requests.post(
    f"{API}/v1/render",
    headers={"Authorization": f"Bearer {os.environ['KTAVLY_API_KEY']}"},
    json={
        "template": "receipt",
        "data": {
            "number": "RC-58213", "date": "2026-10-18", "currency": "EUR",
            "business": {"name": "Café Lisboa"},
            "customer": {"name": "Dana Kowalski"},
            "items": [{"name": "Barista workshop", "quantity": 2, "price": 45}],
            "taxRate": 23,
            "payment": {"method": "Visa", "last4": "4242"},
        },
        "options": {"filename": "receipt-RC-58213.pdf"},
    },
    timeout=60,
)
if r.status_code != 200:
    err = r.json()["error"]
    raise SystemExit(f"{err['code']}: {err['message']}")
with open("receipt.pdf", "wb") as f:
    f.write(r.content)
print(f"Saved receipt.pdf ({r.headers['X-Pages']} page)")

<?php
// PHP 7.4+ with the curl extension. Run: php quickstart.php
$api = getenv('KTAVLY_API_URL') ?: 'https://api.ktavly.com';
$payload = [
    'template' => 'report',
    'data' => [
        'title' => 'Q3 2026 Revenue Review',
        'kpis' => [['label' => 'Revenue', 'value' => '$2.84M', 'delta' => 14.2]],
        'sections' => [['heading' => 'Outlook', 'paragraphs' => ['Q4 revenue is expected to grow.']]],
    ],
];
$ch = curl_init("$api/v1/render");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('KTAVLY_API_KEY'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
if ($status !== 200) {
    $err = json_decode($body, true)['error'] ?? ['code' => 'network_error', 'message' => 'request failed'];
    fwrite(STDERR, "{$err['code']}: {$err['message']}\n");
    exit(1);
}
file_put_contents('report.pdf', $body);
echo "Saved report.pdf\n";

// Node 18+ with the Ktavly SDK (npm install ktavly, at launch). Run: node sdk-quickstart.mjs
import { writeFile } from 'node:fs/promises';
import { Ktavly } from 'ktavly';

const ktavly = new Ktavly({
  apiKey: process.env.KTAVLY_API_KEY,
  baseUrl: process.env.KTAVLY_API_URL ?? 'https://api.ktavly.com',
});
// Typed errors (ValidationError, QuotaExceededError, RateLimitError, ...); 429/5xx are retried for you.
const { pdf, meta } = await ktavly.renderWithMeta('invoice-he', {
  documentType: 'tax_invoice', number: '20261042', issueDate: '2026-10-18',
  seller: { name: 'סטודיו גפן בע״מ', businessId: '514238765' },
  customer: { name: 'אורן מערכות מידע בע״מ' },
  items: [{ description: 'עיצוב ממשק משתמש', quantity: 1, unitPrice: 18500 }],
});
await writeFile('invoice-he.pdf', pdf);
console.log(`Saved invoice-he.pdf (${meta.pages} page, ${meta.usage.remaining} left this month)`);

# Python 3.9+ with the Ktavly SDK (pip install ktavly, at launch). Run: python sdk-quickstart.py
import os

from ktavly import Ktavly

ktavly = Ktavly(
    api_key=os.environ["KTAVLY_API_KEY"],
    base_url=os.environ.get("KTAVLY_API_URL", "https://api.ktavly.com"),
)
# Typed errors (ValidationError, QuotaExceededError, RateLimitError, ...); 429/5xx are retried for you.
result = ktavly.render_with_meta(
    "receipt",
    {
        "number": "RC-58213", "date": "2026-10-18", "currency": "EUR",
        "business": {"name": "Café Lisboa"},
        "customer": {"name": "Dana Kowalski"},
        "items": [{"name": "Barista workshop", "quantity": 2, "price": 45}],
        "taxRate": 23,
        "payment": {"method": "Visa", "last4": "4242"},
    },
    {"filename": "receipt-RC-58213.pdf"},
)
result.save("receipt.pdf")
print(f"Saved receipt.pdf ({result.meta.pages} page)")

# Raw HTML → PDF with page numbers and a Hebrew line
curl "$KTAVLY_API_URL/v1/render" \
  -H "Authorization: Bearer $KTAVLY_API_KEY" -H "Content-Type: application/json" \
  -d '{"html":"<h1>Hello</h1><p>שלום עולם</p>",
       "options":{"format":"A4","margin":"15mm","pageNumbers":true,"footer":"Acme Ltd · confidential"}}' \
  -o hello.pdf

# Same request, but get JSON with base64 (handy for Zapier / Make)
curl "$KTAVLY_API_URL/v1/render" -H "Accept: application/json" ...

# Any template with its own sample data
curl -s "$KTAVLY_API_URL/v1/templates/invoice-he/sample" | \
  jq '{template:"invoice-he", data:.}' | \
  curl "$KTAVLY_API_URL/v1/render" -H "Authorization: Bearer $KTAVLY_API_KEY" \
       -H "Content-Type: application/json" -d @- -o invoice-he.pdf

{"template":"invoice-he","data":{"documentType":"tax_invoice_receipt","number":"20261042", …}}

// or any template in Hebrew:
{"template":"invoice","styles":{"locale":"he-IL"},"data":{"currency":"ILS","number":"חש-0087", …}}