Developer reference

OpenAPI & catalog

• /api/openapi.json — OpenAPI 3.1 with request examples for every generate and import route
• /api/v1/schema — family catalog with per-template schema URLs

Document families

Invoice

GET/POST /api/v1/invoices/schema, …/generate, …/import

W-9

GET/POST /api/v1/w9/schema, …/generate, …/import — request body uses a w9 object

Japan visa

GET/POST /api/v1/japan-visa/schema, …/generate, …/import — request body uses a japanVisa object

Authentication & key scopes

• Account API keys: create keys under Settings → API access and send Authorization: Bearer fldr_live_… or X-FLDR-API-Key.
• Each key can be limited to generate and/or import, and to specific document families (invoice, W-9, Japan visa).
• Deployment integrations may use FLDR_PROGRAMMATIC_API_KEY (server env) with full access.
• Signed-in FLDR users may call generate endpoints with a Clerk session; export limits apply to the account tier.

Rate limits

Programmatic generate and import routes share a limit of 60 POST requests per minute per IP (separate counters per route family). Successful responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. When exceeded, responses return HTTP 429 with Retry-After and the same rate-limit headers. Per-account API keys may also return HTTP 429 with quota_exceeded when daily or monthly quotas are configured in API access settings.

Export webhooks

After a successful programmatic generate, FLDR can POST an export.completed event to URLs you configure under API access. Verify the X-Fldr-Signature header: HMAC-SHA256 of the raw JSON body using your signing secret, prefixed with sha256=. Failed deliveries are retried automatically (up to three attempts); view the delivery log and trigger manual retries in account settings.

// Node.js verification sketch
const crypto = require("crypto");
const expected = crypto.createHmac("sha256", signingSecret).update(rawBody).digest("hex");
const ok = req.headers["x-fldr-signature"] === `sha256=${expected}`;

Required fields

The invoice object requires sender.name and at least one lineItems entry with description. W-9 requires name; Japan visa requires passport and applicant identity fields — see each family schema endpoint.

Example: invoice generate

curl -X POST 'https://www.fldr.diy/api/v1/invoices/generate' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "format": "pdf",
    "filename": "invoice-acme",
    "invoice": {
      "invoiceNumber": "INV-1042",
      "date": "2026-05-30",
      "sender": {
        "name": "River & Co. Design Studio",
        "email": "billing@example.com",
        "address": "142 Cedar Lane\nPortland, OR 97205"
      },
      "recipient": {
        "name": "Alex Morgan",
        "company": "Northwind Media LLC"
      },
      "lineItems": [
        {
          "description": "Brand identity refresh",
          "quantity": 8,
          "unitPrice": 125
        }
      ],
      "taxRate": 8.5,
      "notes": "Net 15 — thank you."
    }
  }'

Example: W-9 generate

curl -X POST 'https://www.fldr.diy/api/v1/w9/generate' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "format": "pdf",
    "filename": "w9-contractor",
    "w9": {
      "name": "Jordan Lee",
      "businessName": "Lee Consulting LLC",
      "taxClassification": "LLC",
      "address": "88 Market Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "tin": "12-3456789"
    }
  }'

Example: Japan visa generate

curl -X POST 'https://www.fldr.diy/api/v1/japan-visa/generate' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "format": "pdf",
    "filename": "visa-application",
    "japanVisa": {
      "surname": "Tanaka",
      "givenNames": "Yuki",
      "passportNumber": "AB1234567",
      "nationality": "United States",
      "dateOfBirth": "1990-04-12",
      "purposeOfVisit": "Tourism",
      "intendedStay": "14 days"
    }
  }'

Editor import

In the workspace, use Import JSON and API in the top bar (Import JSON opens paste/upload; API opens this reference). Import API routes accept "persist": false to return mapped fields without a cloud write.

Discovery

llms.txt lists public integration surfaces for this deployment. Canonical types live in @fldr/document-model.