> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fileloom.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Understand the key concepts behind Fileloom: workspaces, templates, credits, and more.

## Workspaces

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

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

**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.

```html theme={null}
<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:**

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

## Handlebars Templating

Fileloom uses [Handlebars](https://handlebarsjs.com/) for dynamic content. Basic syntax:

```handlebars theme={null}
{{! 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](/helpers/overview).

## 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:**

```bash theme={null}
# 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:**

1. Monthly quota (from your plan)
2. Purchased credit packs (oldest expiring first)
3. 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](/integrations/overview) 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](/webhooks/overview) 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:

```tsx theme={null}
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](/billing/plans) for full details.

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Complete API documentation
  </Card>

  <Card title="Template Helpers" icon="wand-magic-sparkles" href="/helpers/overview">
    70+ built-in formatting helpers
  </Card>

  <Card title="Dashboard Guide" icon="browser" href="/dashboard/overview">
    Navigate the Fileloom dashboard
  </Card>

  <Card title="Best Practices" icon="check" href="/templates/best-practices">
    Tips for production templates
  </Card>
</CardGroup>