# TableForge

TableForge extracts tables from PDF documents, Word files, and images to structured JSON, Excel, CSV, or Markdown using AI — with no templates or training required.

## What It Does

- Accepts: PDF, DOCX, PPTX, JPG, PNG, TIFF, WEBP (up to 50 MB, 1,000 pages)
- Returns: structured table data (JSON arrays of cells), Excel (.xlsx), or Markdown
- Preserves: merged cells, multi-page tables, currency, headers, footnotes (mode-dependent)

## Extraction Modes

| Mode | Credit cost | Output formats | Best for |
|------|-------------|----------------|----------|
| `table` | 1× per page | JSON, Excel, CSV, Markdown | Quick extraction, simple tables |
| `data_clean` | 2× per page | JSON, Excel, CSV, Markdown | Database import, analytics pipelines |
| `markdown` | 2× per page | Markdown text | LLM context, RAG pipelines |
| `layout_match` | 4× per page | JSON, Excel, CSV, Markdown | Legal docs, compliance, exact formatting |

### layout_match sub-modes (`layoutScope`)

`layout_match` accepts an optional `layoutScope` parameter:
- `tables` (default) — extract only the detected tables from each page
- `pages` — full-page extraction: captures all content as it appears on the page (text, headers, tables together). Use for complex mixed-layout documents.

Pass as `layout_scope` in multipart form data or `layoutScope` in JSON body.

## REST API Quick Start

Requires a Pro tier account or higher. API keys have the format `tf_live_...`.

**Step 1 — Create account and get API key** (fully automated, no human step):
```
POST https://www.tableforge.ai/api/v1/auth/register
Content-Type: application/json

{"email": "agent@example.com", "password": "securepassword"}
```
Response includes `apiKey.key` — store it, it is shown only once.

**Step 2 — Submit extraction job** (multipart):
```
POST https://www.tableforge.ai/api/v1/jobs
Authorization: Bearer tf_live_YOUR_KEY
Content-Type: multipart/form-data

file=<binary>  mode=table
```
Response: `{ "jobId": "job_...", "status": "queued", "estimatedWaitSeconds": 30 }`

**Step 3 — Poll for completion**:
```
GET https://www.tableforge.ai/api/v1/jobs/{jobId}
Authorization: Bearer tf_live_YOUR_KEY
```
Poll until `status` is `complete`, `failed`, or `cancelled`.

**Step 4 — Retrieve result** (add `?format=` for the download format):
```
GET https://www.tableforge.ai/api/v1/jobs/{jobId}/result?format=json
GET https://www.tableforge.ai/api/v1/jobs/{jobId}/result?format=excel
GET https://www.tableforge.ai/api/v1/jobs/{jobId}/result?format=csv
GET https://www.tableforge.ai/api/v1/jobs/{jobId}/result?format=markdown
Authorization: Bearer tf_live_YOUR_KEY
```
- `json` (default) — `{ "tables": [...], "pageCount": N, "creditsConsumed": N }`
- `excel` — binary `.xlsx` download (not available for `markdown` mode — returns error)
- `csv` — CSV text, tables separated by blank lines (not available for `markdown` mode — returns error)
- `markdown` — Markdown tables (native for `markdown` mode; generated from JSON for all other modes)

Each format call is independent — you can retrieve JSON first, then download the same completed job as Excel or CSV in separate calls. Results persist in cloud storage until job expiry.

## Account Status Codes

`GET /api/v1/account/status` returns a `status` field agents should act on:

| Status | Meaning | Action |
|--------|---------|--------|
| `active` | All good | Proceed |
| `approaching_limit` | ≥80% quota used | Warn user, consider upgrading |
| `quota_exceeded` | 100% used, overage off | Stop; enable overage or upgrade |
| `overage_active` | Over quota, overage billing on | Jobs continue; watch spend |
| `cap_reached` | Overage spending cap hit | Stop until next billing cycle or raise cap |
| `payment_required` | Past-due invoice | Contact billing |
| `suspended` | Account suspended | Contact support |

Enable overage: `PATCH /api/v1/account/overage { "overageEnabled": true, "spendingCapCents": 5000 }`

## Webhook Events

Register webhooks at `POST /api/v1/webhooks`. Events: `job.completed`, `job.failed`, `quota.approaching`, `quota.exceeded`, `overage.cap_reached`.

Deliveries are signed: verify `X-TableForge-Signature: sha256=<HMAC-SHA256(secret, body)>`.

Retry schedule: 1m → 5m → 30m → 2h → 8h (5 attempts total).

## MCP Server (for Claude Desktop / Cursor / Zed)

TableForge exposes a Model Context Protocol server. Add to `claude_desktop_config.json`:

**Claude Desktop / Claude.ai** — Settings → Connectors → Add custom connector → paste URL → sign in (OAuth, no API key needed):
```
https://www.tableforge.ai/api/mcp
```

**Claude Code (CLI)** — OAuth has known bugs in Claude Code; use --header instead:
```bash
claude mcp add --transport http tableforge \
  --header "Authorization: Bearer tf_live_YOUR_KEY" \
  https://www.tableforge.ai/api/mcp
```

**Cursor** (`~/.cursor/mcp.json`) / **Zed** (`settings.json` context_servers) — use header, not ?key= in URL (keys in URLs appear in logs):
```json
{
  "mcpServers": {
    "tableforge": {
      "url": "https://www.tableforge.ai/api/mcp",
      "headers": { "Authorization": "Bearer tf_live_YOUR_KEY" }
    }
  }
}
```

**Continue.dev** (`config.yaml`):
```yaml
mcpServers:
  tableforge:
    type: streamable-http
    url: https://www.tableforge.ai/api/mcp
    requestOptions:
      headers:
        Authorization: "Bearer tf_live_YOUR_KEY"
```

**Zed** also supports OAuth auto-discovery — omit headers and Zed opens a browser for sign-in.

Available MCP tools: `extract_tables`, `check_job_status`, `get_job_result`, `get_account_status`, `list_extraction_modes`.

## Full API Reference

OpenAPI 3.0 spec: https://www.tableforge.ai/openapi.json

## Pricing

- Entry ($9.99/mo): web app only, no API access
- Pro ($49.99/mo): API access, 500 extraction credits/month
- Elite ($149.99/mo): 2,000 credits/month
- Enterprise ($299.99/mo): 6,000 credits/month

All tiers: overage available at mode-specific per-page rates.