# tablepage.ai

> CSV to beautiful, shareable dataset page. Upload any CSV, TSV, or Excel file and get an instant interactive data page with search, sort, filter, charts, and AI-generated insights.

## Agent Workflow

Upload a dataset and get structured analysis — no scraping required:

1. `POST /api/upload` — upload a file, get back a `slug`
2. `GET /api/d/{slug}/status` — poll until `ready` is `true` (analysis takes 10-60s)
3. `GET /api/d/{slug}/meta` — get dataset metadata (title, headers, row count, tags)
4. `GET /api/d/{slug}/insights` — get structured analysis (correlations, outliers, distributions)
5. `GET /api/d/{slug}/charts` — list available charts, then `GET /api/d/{slug}/charts/{index}.png` for each
6. `GET /api/d/{slug}/query` — paginated row data with search/sort/filter
7. `GET /api/d/{slug}/stats/{column}` — per-column statistics
8. `POST /api/d/{slug}/analyze` — ask a natural-language question, get AI analysis
9. `GET /api/d/{slug}/analyze/{request_id}` — poll until analysis completes
10. `GET /api/d/{slug}/analyze` — list all past analysis requests and results

## API

Base URL: https://data.tablepage.ai

### Public endpoints (no auth required)

All /api/d/{slug}/* endpoints respect dataset visibility. Public datasets are open to all. Private datasets return 403 unless you pass a valid `?token=` share token.

#### Upload (for bots)

- POST /api/bot-upload — Upload a file (CSV/TSV/XLSX, max 25MB, rate limited 10/day)
  - Body: multipart/form-data with "file" field
  - Returns: { slug, truncated, malformed }

- POST /api/bot-upload-json — Upload CSV/TSV content as JSON (no multipart needed)
  - Body: JSON with "filename" (e.g. "data.csv") and "content" (CSV text)
  - Returns: { slug, url, next_step }

#### Dataset metadata & status

- GET /api/d/{slug}/meta — Full metadata: title, description, headers, row_count, col_count, tags, column_types, enrichment_status, insights_status, element_count, url

- GET /api/d/{slug}/status — Lightweight polling: { ready, insights_status, enrichment_status, element_count }. Poll this after upload until ready=true.

#### Querying data

- GET|POST /api/d/{slug}/query — Query dataset rows with search, sort, filter, pagination
  - GET params: q (full-text search), sort (column name), dir (asc|desc), limit (max 1000, default 100), page (0-indexed), offset (row offset), fcol (filter column), fval (filter value), cfilters (JSON array of column filters)
  - POST accepts JSON body with same params
  - Column filter format: [{"col": "Age", "op": "gte", "val": "18"}, {"col": "City", "op": "contains", "val": "New"}]
  - Supported ops: gte, lte, contains, exclude
  - Returns: { headers, rows, total }

- GET /api/d/{slug}/stats/{column} — Column statistics (min, max, mean, median, std, distribution, top values)

#### Insights & charts

- GET /api/d/{slug}/insights — Structured insights (correlations, outliers, distributions, quality issues). Returns data only, no HTML/SVG. Each insight has: type, text, column (optional), affected_row_count (optional), correlation (optional).

- GET /api/d/{slug}/charts — List all available charts: [{ index, type, label, column, png_url }]

- GET /api/d/{slug}/charts/{index}.png — Download chart as PNG image (0-indexed, from the list above)

- GET /api/d/{slug}/elements — List page elements (narratives, charts, annotations, banners) created by enrichment or analysis agents

#### AI Analysis (Expand Analysis)

Ask natural-language questions about a dataset. An AI agent runs Python analysis on the data, produces narratives and charts, and writes results back as page elements.

- POST /api/d/{slug}/analyze — Submit a question for AI analysis
  - Body: JSON { "question": "What are the top correlations?" }
  - Question max 500 characters
  - Rate limits: 10 questions/hour per IP, 5 questions/hour per dataset
  - Returns 202: { request_id, status: "pending", poll_url }

- GET /api/d/{slug}/analyze/{request_id} — Poll analysis status
  - Returns: { request_id, status, question, progress, created_at }
  - status is one of: pending, running, completed, failed
  - When status=completed, response includes "elements" array with the charts/narratives produced
  - When status=failed, response includes "error" message
  - Poll every 2-3 seconds; analysis typically takes 15-60 seconds

- GET /api/d/{slug}/analyze — List all analysis requests for this dataset
  - Returns: { requests: [{ id, question, status, created_at, ... }] }

Example analysis workflow:
```
# 1. Submit a question
POST /api/d/my-dataset/analyze
{"question": "Which columns are most correlated and why?"}
→ {"request_id": "abc123", "status": "pending", "poll_url": "/api/d/my-dataset/analyze/abc123"}

# 2. Poll until done
GET /api/d/my-dataset/analyze/abc123
→ {"request_id": "abc123", "status": "running", "progress": "Analyzing correlations..."}
→ {"request_id": "abc123", "status": "completed", "elements": [...]}

# 3. View all analyses
GET /api/d/my-dataset/analyze
→ {"requests": [{"id": "abc123", "question": "Which columns...", "status": "completed"}]}
```

#### Catalog & discovery

- GET /api/bot-query — Browse dataset catalog or get dataset details
  - Params: agent (your name), comment (message), slug (specific dataset)
  - Without slug: returns full catalog of public datasets
  - With slug: returns dataset metadata + 10 sample rows

#### Download

- GET /d/{slug}/download — Download full dataset as CSV file

### Admin endpoints (requires admin Bearer token)

- POST /api/d/{slug}/elements — Create page elements (chart, narrative, annotation, banner)
- PATCH /api/d/{slug}/elements/{id} — Update element fields (title, description, content, config)
- DELETE /api/d/{slug}/elements/{id} — Delete element
- GET /api/pending — List datasets awaiting enrichment
- POST /api/admin/d/{slug}/enrichment — Trigger enrichment
- POST /api/admin/d/{slug}/recompute-insights — Recompute dataset insights

### Discovery

- GET /llms.txt — This file

## Suggested agent workflow: deep analysis

For a thorough analysis of any dataset:

1. Upload or find your dataset: `POST /api/bot-upload` (or `POST /api/bot-upload-json`) or `GET /api/bot-query`
2. Wait for auto-analysis: poll `GET /api/d/{slug}/status` until ready=true
3. Read the auto-insights: `GET /api/d/{slug}/insights` for correlations, outliers, distributions
4. Get charts: `GET /api/d/{slug}/charts` then download PNGs
5. Query specific slices: `GET /api/d/{slug}/query?q=...&sort=...&cfilters=...`
6. Ask deeper questions: `POST /api/d/{slug}/analyze` with targeted questions
7. Poll results: `GET /api/d/{slug}/analyze/{request_id}` until completed
8. Repeat step 6-7 for follow-up questions (up to rate limits)

## Optional

- Browse datasets: https://data.tablepage.ai/
- Landing page: https://tablepage.ai