API Reference

Fireloom exposes a single HTTP endpoint for converting Firebase Firestore export files. Use it from curl, a Bash script, a Cron job, or any HTTP client. No SDK needed.

Quick start

# Free tier — first 10 documents, no auth required:
curl -X POST 'https://fireloom.io/api/convert?format=csv' \
     -F 'file=@output-0' \
     -o export.csv

# Pro tier — pass your license key as a Bearer token:
curl -X POST 'https://fireloom.io/api/convert?format=sql' \
     -H 'Authorization: Bearer FIRELOOM-PRO-v1.xxxxxxxx.yyyyyyyy' \
     -F 'file=@output-0' \
     -F 'file=@output-1' \
     -F 'file=@output-2' \
     -o export.sql

Don't have a license yet? Get a 30-day Pro pass for $19 — your key is delivered by email.

Authentication

Pro features (unlimited documents, all formats without truncation) require a license key sent in the Authorization header:

Authorization: Bearer FIRELOOM-PRO-v1.<payload>.<signature>

The license is bound to the email you used at checkout and expires 30 days after purchase. Store it however your stack stores secrets — env var, secret manager, etc.

Endpoints

POST/api/convert

Converts one or more Firebase Firestore export files into the target format and streams the result back as the response body.

Query parameters

Name	Type	Description
`format`	string	One of `csv`, `jsonl`, `jsonl-typed`, `sql`. Defaults to `csv`.

Request body

Multipart form-data with one or more file fields. Each file must be named output-N (e.g. output-0, output-1) — that's how Firebase names them in Export entire database.

Response headers

Name	Description
`X-Fireloom-Processed`	Number of Firestore documents processed.
`X-Fireloom-Truncated`	`true` if the response was capped at the free tier's 10-document limit.

Status codes

`200`	Conversion succeeded. Body is the converted file in the requested format.
`400`	No Firestore documents in the upload, or unsupported format.
`401`	Bearer token failed signature verification (forged or tampered).
`403`	License is expired.

Output formats

Format	Content-Type	Notes
`csv`	text/csv	Header row + one row per document. Nested fields flattened to `parent.child` columns.
`jsonl`	application/x-ndjson	One JSON object per line (NDJSON). Firestore values are stringified — numbers and booleans become string fields.
`jsonl-typed`	application/x-ndjson	Like `jsonl` but preserves Firestore types — numbers stay numeric, booleans stay boolean. Recommended for typed pipelines.
`sql`	application/sql	PostgreSQL `INSERT` statements with proper escaping. Pipe directly into `psql`.

Examples

Convert and pipe straight into Postgres

curl -sS -X POST 'https://fireloom.io/api/convert?format=sql' \
     -H "Authorization: Bearer $FIRELOOM_LICENSE" \
     -F 'file=@output-0' \
  | psql "$DATABASE_URL"

Scriptable directory upload

FILES=()
for f in firestore_export/all_namespaces/output-*; do
    FILES+=(-F "file=@$f")
done
curl -X POST 'https://fireloom.io/api/convert?format=jsonl-typed' \
     -H "Authorization: Bearer $FIRELOOM_LICENSE" \
     "${FILES[@]}" \
     -o export.jsonl

Validate your license

curl 'https://fireloom.io/api/license/validate' \
     -H "Authorization: Bearer $FIRELOOM_LICENSE"
# → {"valid":true,"email":"you@example.com","plan":"pro","expiry":"2026-05-27"}

Limits & conventions

Free tier: 10 documents per request, all formats. Beyond 10 docs the response is truncated and an X-Fireloom-Truncated: true header is set.
Upload size: 256 MB per request (multipart total). Send larger exports in chunks of output-N files.
Concurrency: no published limit. Be reasonable.
SLA: best-effort. Email us if you need guarantees.

Need help?

Email hello@fireloom.io. Bug reports get faster turnaround if you include the request ID from the X-Request-Id response header.