DocForge REST API

Authentication

Every request requires an API key. Create one in Settings → API keys. Send it as a bearer token:

Authorization: Bearer dfk_xxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are SHA-256 hashed at rest; the plaintext is shown once at creation. Revoke a compromised key immediately — there's a delete button next to each row in the dashboard.

Base URL

https://trydocforge.com/api/v1

Create a run

POST /runs — submit rows inline, get a run id back.

curl -X POST https://trydocforge.com/api/v1/runs \
  -H "Authorization: Bearer $DOCFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "51b0f...9a",
    "rows": [
      { "customer": "Acme Inc.", "invoice_number": "INV-001", "amount": 1250 },
      { "customer": "Globex",    "invoice_number": "INV-002", "amount": 980 }
    ]
  }'

Response:

{
  "id": "4f3a...c2",
  "status": "pending",
  "total_documents": 2
}

Request body

• templateId — UUID of a template you own.
• rows — array of objects. Keys should match your template's variable keys. Max 5,000 rows per request.
• fieldMapping (optional) — { "variable_key": "source_column" } if your row keys differ.

Errors

• 401 — missing or invalid API key.
• 403 — your plan does not include API access.
• 402 — monthly document quota exceeded.
• 404 — template not found.

Fetch a run

GET /runs/:id — poll to watch progress, or use a webhook (preferred). Returns signed PDF URLs for completed documents; URLs expire after 5 minutes.

curl https://trydocforge.com/api/v1/runs/4f3a...c2 \
  -H "Authorization: Bearer $DOCFORGE_API_KEY"

{
  "run": {
    "id": "4f3a...c2",
    "status": "completed",
    "total_documents": 2,
    "completed_documents": 2,
    "failed_documents": 0
  },
  "documents": [
    {
      "id": "...",
      "row_index": 0,
      "display_name": "Acme Inc.",
      "status": "done",
      "download_url": "https://...signed.../inv-001.pdf"
    }
  ]
}

List templates

GET /templates

GET /templates/:id — includes HTML, CSS, variables, and sample_payload.

Webhooks

Instead of polling, configure a webhook at Settings → Webhooks. We POST a signed JSON body to your URL when events fire:

• run.completed
• run.failed
• document.generated
• template.updated

Every delivery includes:

• X-DocForge-Event — event name.
• X-DocForge-Signature — HMAC-SHA256 of the body, hex-encoded, using your webhook's signing secret.

Verify a webhook

const crypto = require("crypto");

function verify(secret, body, sig) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

Rate limits

The API soft-limits at 60 requests per minute per key. Exceeding this returns 429. Need higher throughput? Email sales@trydocforge.com.

Support

Problems or feature requests: support@trydocforge.com.