API Documentation

Endpoints

All requests require authentication via Authorization: Bearer <api_key> header or ?api_key=<api_key> query parameter.

Reading Records

List rows or fetch a single row by id. Both endpoints accept either a pk_ or sk_ key.

curl -H "Authorization: Bearer {api_key}" \
     "https://csv-api.com/api/v1/datasets/{public_id}/records?per_page=25"

{
  "data": [
    { "id": 1, "name": "Ada", "city": "Portland" },
    { "id": 2, "name": "Grace", "city": "Seattle" }
  ],
  "meta": { "total": 2, "page": 1, "per_page": 25, "total_pages": 1 }
}

curl -H "Authorization: Bearer {api_key}" \
     "https://csv-api.com/api/v1/datasets/{public_id}/records/42"

{ "data": { "id": 42, "name": "Ada", "city": "Portland" } }

Filtering

Filter records using query parameters.

Runnable curl example

curl -H "Authorization: Bearer {api_key}" \
     "https://csv-api.com/api/v1/datasets/{public_id}/records?filter%5Bcity%5D=Portland&filter%5Bage%5D%5Bgte%5D=21"

Note: [ and ] are encoded as %5B / %5D so curl doesn't interpret them as glob ranges. (Alternatively, pass -g to disable curl's URL globbing.)

Sorting

Sort results by one or more columns. Prefix with - for descending order. Separate multiple columns with commas.

?sort=name

?sort=-created_date

?sort=city,-age

Pagination

Results are paginated. Default: 25 per page, maximum: 100.

?page=2&per_page=50

The response includes a meta object:

{
  "data": [...],
  "meta": {
    "total": 1000,
    "page": 2,
    "per_page": 50,
    "total_pages": 20
  }
}

Field Selection

Return only specific columns to reduce payload size.

?fields=name,email,age

Rate Limits & Plan Limits

When the rate limit is exceeded, the API returns 429 Too Many Requests.

Writing Records

Create, update, and delete individual rows over the API. Write endpoints require a private (sk_) key — using a public key returns 403 Forbidden.

Send columns by their display names (the same names you see in the dataset table). Unknown columns are silently ignored. Type validation runs on the database side — invalid values return 422.

curl -X POST -H "Authorization: Bearer {api_key}" \
     -H "Content-Type: application/json" \
     -d '{"record": {"name": "Ada", "city": "Portland"}}' \
     "https://csv-api.com/api/v1/datasets/{public_id}/records"

curl -X PATCH -H "Authorization: Bearer {api_key}" \
     -H "Content-Type: application/json" \
     -d '{"record": {"city": "Seattle"}}' \
     "https://csv-api.com/api/v1/datasets/{public_id}/records/42"

curl -X DELETE -H "Authorization: Bearer {api_key}" \
     "https://csv-api.com/api/v1/datasets/{public_id}/records/42"

Bulk Writes & Upserts

Write up to 1,000 rows per request. Choose how to handle conflicts on the columns you designate as keys — useful when you want idempotent imports without re-uploading the whole file.

curl -X POST -H "Authorization: Bearer {api_key}" \
     -H "Content-Type: application/json" \
     -d '{
           "records": [
             {"email": "[email protected]", "name": "Ada"},
             {"email": "[email protected]", "name": "Grace"}
           ],
           "on_conflict": "update",
           "key_columns": ["email"]
         }' \
     "https://csv-api.com/api/v1/datasets/{public_id}/records/bulk"

Response: { "data": { "inserted": 1, "updated": 1 } }

Aggregation

Compute counts, sums, averages, and more without pulling rows down. Combine with the same filter[…] syntax used by the list endpoint.

curl -H "Authorization: Bearer {api_key}" \
     "https://csv-api.com/api/v1/datasets/{public_id}/records/aggregate?metric=count,avg:price&group_by=city"

Append & Upsert Imports

Add new rows to an existing dataset by uploading another CSV or Excel file — no need to re-upload everything from scratch. Available on paid plans from the dataset detail page.

• Append — every row in the upload is added as a new row.
• Upsert — pick one or more key_columns; rows that match an existing key get updated, the rest are inserted.

Imports run as background jobs and complete asynchronously.

Shared Pages

Create public, read-only pages for any dataset. Each shared page gets a unique URL that anyone can access without an API key.

You can configure static filters on shared pages to show a specific view of your data. For example, only show rows where status = active or city = Portland. Static filters are always applied before any visitor search or sort.

Shared page limits vary by plan: Free (1), Starter (5), Pro (50), Scale (unlimited). Configure shared pages and their filters from the dataset detail page.