Core Concepts

Workspaces

A workspace is your isolated environment in Fileloom. Everything belongs to a workspace: templates, files, API keys, team members, and billing.

When you sign up, a default workspace is created automatically. You can create additional workspaces to separate projects or clients.

Key points:

Each workspace has its own API keys, templates, and usage quota
Team members can be invited with different roles (owner, editor, viewer)
Billing and subscription are per-workspace
Switch between workspaces using the dropdown in the dashboard sidebar

Templates

Templates are reusable HTML documents with Handlebars placeholders for dynamic content.

<div class="invoice">
  <h1>Invoice #{{invoiceNumber}}</h1>
  <p>Customer: {{customer.name}}</p>
  <p>Total: {{currency total "USD"}}</p>
</div>

Template components:

Component	Description
HTML	The document structure and content
CSS	Styling (inline or in a separate tab)
Test Data	Sample JSON for preview
Settings	Paper size, margins, orientation, headers/footers

Template lifecycle:

Draft — Work in progress, auto-saved
Published — Available for API use, version tracked
Versions — Each publish creates a new version you can reference or rollback

Handlebars Templating

Fileloom uses Handlebars for dynamic content. Basic syntax:

{{! Variable output }}
{{variableName}}

{{! Nested objects }}
{{customer.address.city}}

{{! Helpers with arguments }}
{{currency amount "EUR"}}
{{formatDate date "MMMM D, YYYY"}}

{{! Conditionals }}
{{#if isPaid}}
  <span class="paid">PAID</span>
{{else}}
  <span class="unpaid">UNPAID</span>
{{/if}}

{{! Loops }}
{{#each items}}
  <tr>
    <td>{{this.name}}</td>
    <td>{{currency this.price "USD"}}</td>
  </tr>
{{/each}}

Fileloom provides 70+ built-in helpers for formatting, math, dates, and business logic. See the Helpers Reference.

API Keys

API keys authenticate your requests to the Fileloom API. Format: fl_xxxxxxxxxxxx Best practices:

Create separate keys for different environments (development, staging, production)
Rotate keys periodically
Never expose keys in client-side code
Use environment variables to store keys

Authentication methods:

# Header (recommended)
X-API-Key: fl_your_api_key

# Bearer token
Authorization: Bearer fl_your_api_key

Credits & Quota

Fileloom uses a credit system for PDF generation: Monthly Quota:

Each plan includes a monthly PDF allowance
Quota resets on your billing date
Unused quota does not roll over

Credit Packs:

Purchase additional credits when you need more
Credits are consumed after monthly quota is exhausted
Credits expire 90 days after purchase
Consumed in FIFO order (oldest first)

Consumption order:

Monthly quota (from your plan)
Purchased credit packs (oldest expiring first)
Hard block when no credits remain

Files

Every generated PDF is stored as a file in your workspace. File properties:

Property	Description
`fileId`	Unique identifier (e.g., `file_1234567890_abc123`)
`url`	Permanent public URL
`signedUrl`	Temporary secure URL (24 hours)
`filename`	Original or generated filename
`size`	File size in bytes
`status`	`generated`, `expired`, or `deleted`

Retention:

Files are retained based on your plan (7 days to 365 days)
After retention period, files are automatically deleted
You can manually delete files at any time

Storage Options

By default, Fileloom stores your PDFs in Firebase Storage. You can also configure external storage: Storage modes:

Mode	Behavior
`fileloom`	Store in Fileloom only (default)
`external`	Store in your S3/Supabase only
`both`	Store in both Fileloom and external

See Integrations to set up AWS S3 or Supabase storage.

Webhooks

Webhooks notify your server when events occur in Fileloom. Available events:

Event	Trigger
`pdf.generated`	PDF successfully created
`pdf.failed`	PDF generation failed

Webhook payloads include file details, processing time, and error information (for failures). See Webhooks for setup instructions.

Rate Limits

API requests are rate-limited based on your plan:

Plan	Requests per Minute
Free	60
Starter	120
Growth	200
Scale	400
Scale Business	1,000
Scale Enterprise	Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 198
X-RateLimit-Reset: 1734012400

Plan Limits Summary

Each plan has limits on resources beyond PDF generation:

Resource	Free	Starter	Growth	Scale
PDFs/month	200	2,000	10,000	50,000
Templates	5	50	Unlimited	Unlimited
Team Members	2	3	5	10
API Keys	1	2	5	10
Retention	7 days	30 days	90 days	180 days
Max HTML Size	2 MB	5 MB	10 MB	50 MB
Max PDF Size	10 MB	25 MB	50 MB	50 MB
Timeout	15s	30s	45s	120s

See Plans & Pricing for full details.

Next Steps

API Reference

Complete API documentation

Template Helpers

70+ built-in formatting helpers

Dashboard Guide

Navigate the Fileloom dashboard

Best Practices

Tips for production templates

Getting Started

Dashboard

Template Editor

API Reference

Templates

Helpers

Integrations

Webhooks

Billing

Code Examples

Resources

Workspaces

Templates

Handlebars Templating

API Keys

Credits & Quota

Files

Storage Options

Webhooks

Rate Limits

Plan Limits Summary

Next Steps

API Reference

Template Helpers

Dashboard Guide

Best Practices

​Workspaces

​Templates

​Handlebars Templating

​API Keys

​Credits & Quota

​Files

​Storage Options

​Webhooks

​Rate Limits

​Plan Limits Summary

​Next Steps

API Reference

Template Helpers

Dashboard Guide

Best Practices

Workspaces

Templates

Handlebars Templating

API Keys

Credits & Quota

Files

Storage Options

Webhooks

Rate Limits

Plan Limits Summary

Next Steps