Skip to content

README.md

Latest commit

 

History

History
249 lines (190 loc) · 7.08 KB

README.md

File metadata and controls

249 lines (190 loc) · 7.08 KB

ReportForge API

API Status License: MIT Live Site

Turn CSV and JSON data into professional HTML reports with a simple REST API.

Features

  • 4 Built-in Templates — Sales Summary, Expense Report, Inventory Status, and Invoice — ready to use out of the box
  • Responsive HTML Output — clean, print-ready reports that look great on any device or as PDF exports
  • Free Tier Available — start generating reports immediately with no credit card required
  • API Key Authentication — simple x-api-key header for authenticated tiers with higher limits

Quick Start

1. Get Your API Key

curl -X POST https://reportforge-api.vercel.app/api/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

2. Generate a Report

curl -X POST https://reportforge-api.vercel.app/api/json-to-report \
  -H "Content-Type: application/json" \
  -H "x-api-key: rf_your_api_key_here" \
  -d '{
    "template": "sales-summary",
    "title": "Q1 Sales Report",
    "data": [
      {"item": "Widgets", "amount": 1250.00, "quantity": 50},
      {"item": "Gadgets", "amount": 890.50, "quantity": 30}
    ]
  }'

3. Use the HTML Output

The response contains a complete HTML document you can open in any browser, embed in an email, or print to PDF.

{
  "html": "<!DOCTYPE html>...",
  "meta": {
    "template": "sales-summary",
    "rowCount": 2,
    "columns": ["item", "amount", "quantity"],
    "generatedAt": "2025-01-15T10:30:00.000Z"
  }
}

API Endpoints

Method Endpoint Description
POST /api/signup Get a free API key
POST /api/json-to-report Generate an HTML report from a JSON array
POST /api/csv-to-report Generate an HTML report from raw CSV
GET /api/templates List all available templates and their columns

Base URL: https://reportforge-api.vercel.app

Templates

Template ID Required Columns Optional Columns
Sales Summary sales-summary item, amount date, quantity, category, customer, region
Expense Report expense-report description, amount date, category, vendor, payment_method, notes
Inventory Status inventory-status item, quantity sku, category, location, reorder_level, unit_price, supplier
Invoice invoice description, amount quantity, unit_price, tax_rate, date, invoice_number, client_name, client_email

Example Request and Response

Request

curl -X POST https://reportforge-api.vercel.app/api/json-to-report \
  -H "Content-Type: application/json" \
  -d '{
    "template": "sales-summary",
    "title": "Monthly Sales",
    "data": [
      {"item": "Widgets", "amount": 1250.00, "quantity": 50},
      {"item": "Gadgets", "amount": 890.50, "quantity": 30},
      {"item": "Sprockets", "amount": 445.75, "quantity": 15}
    ]
  }'

Response

{
  "html": "<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"UTF-8\">...</html>",
  "meta": {
    "template": "sales-summary",
    "rowCount": 3,
    "columns": ["item", "amount", "quantity"],
    "generatedAt": "2025-06-15T14:22:00.000Z"
  }
}

The html field contains a self-contained HTML document with inline CSS — no external dependencies required.

Code Examples

JavaScript (Node.js)

const response = await fetch('https://reportforge-api.vercel.app/api/json-to-report', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    data: [
      { item: 'Widgets', amount: 1250.00, quantity: 50 },
      { item: 'Gadgets', amount: 890.50, quantity: 30 }
    ],
    template: 'sales-summary',
    title: 'Q1 Sales Report'
  })
});

const { html, meta } = await response.json();
console.log(`Generated report: ${meta.rowCount} rows, template: ${meta.template}`);

Python

import requests

response = requests.post(
    'https://reportforge-api.vercel.app/api/json-to-report',
    json={
        'data': [
            {'item': 'Widgets', 'amount': 1250.00, 'quantity': 50},
            {'item': 'Gadgets', 'amount': 890.50, 'quantity': 30}
        ],
        'template': 'sales-summary',
        'title': 'Q1 Sales Report'
    }
)

data = response.json()
print(f"Generated report: {data['meta']['rowCount']} rows")

Authentication

For the free tier, no API key is required. For Starter and Business tiers, include your key in the x-api-key header:

curl -X POST https://reportforge-api.vercel.app/api/json-to-report \
  -H "Content-Type: application/json" \
  -H "x-api-key: rf_your_api_key_here" \
  -d '{...}'

Pricing

Free Starter Business
Price $0/mo $12/mo $35/mo
Reports per day 20 200 Unlimited
Templates All 4 All 4 All 4
API key Not required Included Included
Support Community Email Priority

View pricing and subscribe →

Error Handling

All errors return a consistent JSON format:

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Field \"data\" is required and must be an array"
  }
}
HTTP Status Error Code Description
400 INVALID_INPUT Missing or malformed fields
405 INVALID_INPUT Wrong HTTP method
413 INPUT_TOO_LARGE Input exceeds tier size limit
429 RATE_LIMITED Daily report limit exceeded

Links

Resource URL
Documentation reportforge-api.vercel.app/docs
Blog reportforge-api.vercel.app/blog
Status Page reportforge-api.vercel.app/status
OpenAPI Spec reportforge-api.vercel.app/openapi.json
Live Demo reportforge-api.vercel.app

Related Products

Product Description Link
DocForge Convert documents between formats (PDF, DOCX, HTML, Markdown) with a simple API docforge.dev
FormForge Generate dynamic web forms from JSON schemas with validation and submission handling formforge.dev

License

This project is licensed under the MIT License.