API Usage: Publish and Query a Public Dataset with TablePage

If your script already produces a clean CSV, you can publish it without manually uploading the file. This API usage walkthrough sends an illustrative library-visits dataset to TablePage, checks the uploaded table, and retrieves branches with at least 1,000 visits.

An API is an interface a program can call. Here, the input is CSV text; the result is a public dataset page and an identifier you can use to retrieve its rows.

This upload publishes publicly. Use only data approved for public release—not personal information, credentials, confidential records, or an unreviewed working sheet. TablePage’s homepage describes public pages that anyone can explore without signing up. Source: TablePage

1. Prepare and upload the CSV

The commands below assume Bash, a recent version of curl, and jq, a command-line JSON processor. The three branch records are invented examples, not actual library statistics.

Create the request file:

cat > payload.json <<'JSON'
{
  "filename": "library-visits-example.csv",
  "visibility": "public",
"content": "branch,month,visits_count\nCentral,2026-09,1240\nEast,2026-09,860\nWest,2026-09,1080\n"
}
JSON

Before substituting a real dataset, check that each row represents the same thing, headers are unique, numeric columns contain numbers rather than display labels, and missing values have a documented meaning. For spreadsheet inputs, see the CSV conversion checks.

TablePage’s OpenAPI specification documents POST /api/upload-json for CSV or TSV text, with required filename and content fields. Public uploads can be unauthenticated. Excel files use the multipart /api/upload endpoint instead. The examples here follow the documented contract as of October 26, 2026. Source: API specification

Send the request once and save its response:

BASE='https://www.tablepage.ai'

curl --fail-with-body --silent --show-error \
-X POST "$BASE/api/upload-json" \
-H 'Content-Type: application/json' \
--data-binary @payload.json \
  -o upload.json

jq '{slug, url, visibility, malformed, truncated}' upload.json

A successful upload response includes a slug: the dataset identifier used in subsequent API paths. The response schema also documents url, visibility, malformed, and truncated fields. If malformed is nonzero or truncated is true, investigate before sharing the page as a complete dataset. Source: upload response schema

After a successful response, save the slug:

SLUG=$(jq -er '.slug' upload.json)

Keep upload.json. You do not need to upload again to check progress or retrieve rows. If the upload request failed or no slug was returned, stop and inspect the error before continuing.

2. Check processing and the stored table

Request processing status:

curl --fail-with-body --silent --show-error \
  "$BASE/api/d/$SLUG/status" | jq .

Repeat this GET request until ready is true; do not repeatedly POST the upload. The status response also exposes insights_status and enrichment_status. In an automated script, put a delay between checks and set a maximum waiting time. Stop and investigate errors or an expired waiting time rather than polling indefinitely. Source: agent workflow

Then inspect metadata:

curl --fail-with-body --silent --show-error \
  "$BASE/api/d/$SLUG/meta" | jq .

The metadata endpoint documents headers, row_count, and visibility. For this sample, verify three data rows, public visibility, and the headers branch, month, and visits_count. Source: metadata specification

Processing readiness is not a data-quality verdict. Compare the stored table with your reviewed input: counts, identifiers, missing values, and totals still need checking.

3. Retrieve a filtered slice

The row-query endpoint supports sorting, pagination, and column filters. This request asks for visit counts of at least 1,000, sorted highest first:

curl --fail-with-body --silent --show-error --get \
"$BASE/api/d/$SLUG/query" \
--data-urlencode 'sort=visits_count' \
--data-urlencode 'dir=desc' \
--data-urlencode 'limit=100' \
--data-urlencode 'page=0' \
--data-urlencode 'cfilters=[{"col":"visits_count","op":"gte","val":"1000"}]' \
  | jq .

gte means “greater than or equal to.” --data-urlencode encodes the filter JSON for the query string. The documented response contains headers, rows, and total; pages are zero-indexed, and limit defaults to 100 with a maximum of 1,000. Source: query specification

For the illustrative input, the expected matching records are Central with 1,240 visits, followed by West with 1,080. Compare that expectation with the returned rows rather than assuming a successful HTTP response means the filter behaved as intended.

For larger results, request successive pages using the same filters and sort settings. Do not treat the first page as the full dataset.

4. Share the checked release

Retrieve the page link from the saved upload response:

jq -r '.url' upload.json

For a real release, provide a meaningful title, source attribution, reporting period, units, and definitions of missing values alongside the table. TablePage documents metadata editing through PATCH /api/d/{slug}/meta, but it requires authentication and dataset ownership. This unauthenticated example does not demonstrate owner access; do not assume that obtaining a public slug gives you permission to edit its metadata. Source: metadata-editing specification

If a request fails, inspect its HTTP status and response body. The upload specification documents 400 for invalid input, 401 for authentication requirements, and 429 for rate limiting. Fix invalid input or pause rate-limited requests rather than immediately resubmitting. Source: upload errors For a recurring publishing workflow, add API monitoring that also checks data quality.