TableFromJSON API Documentation

Overview

The TableFromJSON API enables you to programmatically convert JSON data into structured table formats (CSV, Excel, HTML, Markdown). Perfect for automating exports, building integrations, or adding premium features to your applications.

Base URL

https://tablefromjson.com/api/v1

Content Type

application/json

Authentication Required

All API requests require a valid API key in the X-API-Key header. API keys are available exclusively to Pro members.

Authentication

Secure your API requests with API key authentication.

Getting an API Key

API keys are available exclusively to Pro members. To generate an API key:

Log in to your TableFromJSON account
Ensure you have an active Pro subscription
Click on your name in the top-right dropdown menu
Click "Generate API Key"
Copy and securely store your API key (it will only be shown once)

Using Your API Key

Include your API key in the X-API-Key header for all requests:


X-API-Key: tfj_your_api_key_here

Rate Limiting

Understand the limits and features available to your account.

Rate Limits & Features

Pro Members: 120 requests per minute with unlimited rows per request
Premium Features: Key-based deduplication, advanced HTML exports with custom themes, Excel format (XLSX)
Non-Pro Users: Limited to 200 exported rows per request (only if API key was generated before subscription expired)

Response Headers

The API includes helpful headers when limits are applied:

Header	Description
`X-Row-Limit-Applied`	`true` when the free-tier row cap trims the dataset.
`X-Original-Rows`	Total rows supplied before limiting.
`X-Exported-Rows`	Rows included in the exported file.
`X-Row-Limit-Message`	Human-readable explanation of the applied restriction.

POST /convert

Convert JSON data into downloadable table formats (CSV, Excel, HTML, Markdown).

POST /api/v1/convert

Accepts a JSON payload describing the dataset, desired format, and optional customization flags. Responds with a downloadable file in the requested format.

Request Parameters

Detailed reference for all available request parameters.

Field	Type	Required	Description
`data`	Array<Object> \| Object	Required	The records to export. A single JSON object is treated as one row, an array supplies multiple rows.
`format`	String	Optional	One of `csv`, `xls`, `xlsx`, `html`, `md`. Defaults to `csv`.
`filename`	String	Optional	Base name for the download. Timestamp and extension are appended automatically.
`headers`	Array<String>	Optional	Custom column labels shown in the export. Requires a matching `original_headers` array.
`original_headers`	Array<String>	Optional	Explicit column ordering matching the `headers` labels. Defaults to the keys from the first record.
`remove_duplicates`	Boolean	Optional	Enable deduplication before export.
`deduplication_mode`	String	Optional	`first` to keep earliest duplicates, `last` to keep latest, `none` to disable. Defaults to `none`.
`key_field`	String	Premium	Exclusive to premium usage. Deduplicates rows by the provided key (e.g. `email`).
`options`	Object	Optional	Format-specific tuning (delimiter for CSV, theme/pagination for HTML, etc.).

Response Format

Understanding API responses and content types.

Content Types

The API streams a downloadable file. Check the Content-Type header to determine the format:

text/csv; charset=UTF-8
application/vnd.ms-excel
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
text/html; charset=UTF-8
text/markdown; charset=UTF-8

Deduplication Headers

If deduplication runs, expect additional metadata:

Header	Description
`X-Deduplication-Mode`	`first` or `last` when duplicates were processed.
`X-Deduplication-Key`	The field used for premium key-based deduplication.
`X-Removed-Duplicates`	Total rows removed by the deduplication pass.

Error Handling

Common error responses and how to handle them.

Status	Reason	Example Message
`400`	Malformed payload	`{"message":"Invalid JSON payload."}`
`401`	Missing or invalid API key	`{"message":"API key required. Please provide a valid API key in the X-API-Key header."}`
`403`	Premium feature requires Pro subscription	`{"message":"Key-based deduplication is only available to premium API users."}`
`422`	Validation failure	`{"message":"Custom headers and original headers must have the same length."}`
`429`	Rate limit exceeded	`{"message":"Too Many Attempts."}`
`500`	Unexpected server error	`{"message":"Server error. Please try again."}`

Code Examples

Ready-to-use code snippets for common scenarios.

Basic CSV Export

                            
curl -X POST "https://tablefromjson.com/api/v1/convert" \

  -H "Content-Type: application/json" \

  -H "X-API-Key: tfj_your_api_key_here" \

  -d '{

    "format": "csv",

    "data": [

      {"name": "Ada", "role": "Engineer"},

      {"name": "Grace", "role": "Scientist"}

    ]

  }' \

  --output team.csv

Advanced HTML Export with Deduplication

                            
POST /api/v1/convert HTTP/1.1

Host: tablefromjson.com

Content-Type: application/json

X-API-Key: your-premium-key

{

  "format": "html",

  "filename": "customer-report",

  "headers": ["Customer", "MRR", "Plan"],

  "original_headers": ["name", "mrr", "plan"],

  "remove_duplicates": true,

  "deduplication_mode": "first",

  "key_field": "email",

  "options": {

    "sortable": true,

    "pagination": true,

    "rows_per_page": 50,

    "theme": "modern"

  },

  "data": [

    {"name": "ACME", "email": "ops@acme.test", "mrr": 1250, "plan": "Pro"},

    {"name": "ACME", "email": "ops@acme.test", "mrr": 1250, "plan": "Pro"}

  ]

}

Best Practices

Tips for using the API effectively and securely.

Secure your API key: Treat your API key like a password. Never expose it in client-side code or commit it to version control.
Validate JSON locally before sending to reduce 422 responses.
Supply original_headers whenever you rename columns so ordering remains predictable.
Store your API key securely using environment variables or a secrets management service.
Monitor rate-limit and deduplication headers for operational insight.
If your Pro subscription expires, your API key will still work but with reduced limits (200 rows per request).
Regenerate your API key immediately if you suspect it has been compromised.

API Key Management

How to generate and manage your API keys.

API keys can only be generated by Pro members through the web interface. Currently, you can generate API keys from your account dropdown menu. Advanced API key management features (list, revoke, set expiration dates) are coming soon.

Each API key is tied to your user account. If your Pro subscription expires, existing API keys will continue to work but with non-Pro limitations (200 row limit). Reactivating your Pro subscription restores full access.