---
title: "Start Export"
method: POST
path: "/api/bitables/{table_id}/exports"
tags: ["bitables"]
---

# Start Export

`POST /api/bitables/{table_id}/exports`

## Request

- Base URL: `https://api.tintin-x.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tintin-x.com/api/bitables/{table_id}/exports`
- Auth: HTTP bearer

Kick off an async export. Returns a job_id immediately; the
client polls ``GET /exports/{job_id}`` until status is ready (or
failed) and then downloads from the returned presigned URL.

Three formats:
  - ``xlsx`` / ``pdf``: legacy whole-table export, no body.
  - ``zip``: batch attachment export. Body is required and carries
    the row/column/cell selection + naming + sub-table options.
    Schema: ``ZipExportRequest`` in ``schemas/bitable_export.py``.

The ZIP path replaces the per-cell single-file download for users
who need to grab attachments in bulk; we lean on the same job
machinery so the frontend only has one polling shape to maintain.

## Path parameters

- `table_id` string, uuid, required

## Query parameters

- `format` string

## Request body

- ZipExportRequest: Body for ``POST /api/bitables/{id}/exports?format=zip``. Selection precedence: ``cell_refs`` > ``row_ids`` (× ``col_ids``) > "all rows × all attachment columns". Caller picks one shape; we don't try to reconcile mixed shapes. ``naming_mode``: - ``subfolder``: ``{column_name}/{row_label}/file.ext`` - ``prefix``: ``{column_name}__{row_label}__file.ext`` ``version_scope`` only affects versioned attachment columns. ``current`` pulls each cell's ``current_version_id`` value; ``all`` walks every ``BitableCellVersion`` for the cell and prefixes the version number into the path. ``sub_table_depth`` recurses link columns. Cycles are detected by visited table_id; a cycled table is skipped (not an error). ``0`` disables sub-table recursion entirely.
  - `row_ids` string[], nullable
  - `col_ids` string[], nullable
  - `cell_refs` ZipCellRef[], nullable
    - `row_id` string, uuid, required
    - `col_id` string, required
  - `naming_mode` 'subfolder' | 'prefix'
  - `revision_id` string, uuid, nullable
  - `version_scope` 'current' | 'all'
  - `sub_table_depth` integer

## Response `202`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/tintin-x/apis/tintin-api.md) · [All operations](https://skmtc.dev/tintin-x/apis/tintin-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tintin-x/apis/tintin-api/revisions/8839a8d0a66c?raw)