# 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.

Interactive docs: https://data.tablepage.ai/api/docs

OpenAPI spec:     https://data.tablepage.ai/api/openapi.json

## 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

### Auth & visibility

Two equivalent auth modes (most endpoints accept either):

- **API key** — `Authorization: Bearer tp_live_…`. Mint at `POST /api/keys` from a logged-in browser session, then store in your script.

- **Session cookie** — `tp_session`, set by the Lovable login flow. Used by the web UI itself.

Datasets are `public` by default. To create a private dataset, pass `visibility=private` on the upload and authenticate the request (key or cookie). Private datasets return 403 to anonymous viewers unless they pass a valid `?token=` share token.

### API keys (Lovable-issued)

- POST /api/keys — Mint a new key (session cookie required; keys cannot mint other keys)

  - Body: { "name": "optional label" }

  - Returns: { id, key, prefix, name } — `key` is shown once and never retrievable again

- GET /api/keys — List the caller's keys (prefix + metadata only)

- DELETE /api/keys/{id} — Soft-revoke

### Upload

All upload endpoints accept an optional `visibility=private` field (multipart form field or JSON body key). `visibility=private` requires auth; otherwise returns 401.

- POST /api/upload — Multipart upload of CSV/TSV/XLSX (max 25MB, rate limited 10/day)

  - Body: multipart/form-data with "file" field and optional "visibility"

  - Returns: { slug, truncated, malformed, visibility }

- POST /api/upload-json — CSV/TSV content as JSON (no multipart needed)

  - Body: { "filename": "data.csv", "content": "...", "visibility": "public"|"private" }

  - Returns: { slug, url, next_step, visibility }

- POST /api/bot-upload — Same as /api/upload but appends "-bot" to the title

- POST /api/bot-upload-json — Same as /api/upload-json but appends "-bot" to the title

### Dataset metadata & status

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

- PATCH /api/d/{slug}/meta — Edit title / description / tags / visibility (owner only; requires auth)

- GET /api/d/{slug}/status — Lightweight polling: { ready, insights_status, enrichment_status, element_count }. Poll 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), token (share token for private datasets)

  - 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)

- 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

### Sharing a private dataset

- POST /api/d/{slug}/share-token — Generate a time-bound share link (owner only, private datasets only)

  - Body: { "expires_hours": 24 } (1 to 720)

  - Returns: { token, expires_at, share_url }

  - Recipients open share_url; no key needed

- DELETE /api/d/{slug}/share-token — Revoke the active share token

### 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

  - Poll every 2-3 seconds; analysis typically takes 15-60 seconds

- GET /api/d/{slug}/analyze — List all analysis requests for this dataset

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": "completed", "elements": [...]}

```

### Account

- GET /api/me/datasets — List datasets owned by the caller (key or cookie required)

### 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

### Discovery

- GET /api/docs — Interactive Swagger UI

- GET /api/openapi.json — OpenAPI 3.1 spec

- 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