Exports guide

The export centre produces, in the background, a file from one or more of the company's datasets. The same datasets serve exports, the public API, the MCP server and the connectors: a column, a filter or an access check is defined once.

Status: developed and tested (lots 1A and 1B); module open in production since 2026-11-05. Exports from the application: Data & integrations › My exports; through the API: /exports (scopes exports:read and exports:write); through MCP: the tauraco_request_export tool.

Datasets

Each dataset applies the same check as the matching list in the application: a user or an application that cannot see a list cannot export it. The full catalogue (columns, labels, filters, accepted formats) is served by GET /integrations/datasets, limited to the datasets your token and rights allow you to export; GET /integrations/formats lists the formats, GET /integrations/connections the delivery connections (delivery).

Formats

Formula neutralisation. In CSV and XLSX, a text cell starting with =, +, -, @, a tab or a carriage return is prefixed with an apostrophe so that a spreadsheet does not execute it. Amounts, numbers and dates are written from their typed value and never prefixed; JSON, JSON Lines and XML are left untouched (a program reads them).

Export lifecycle

QUEUED → RUNNING → SUCCEEDED, or FAILED (with an error code), or CANCELLED. A SUCCEEDED file becomes EXPIRED after 30 days, then it is purged (410 export_expired). A large export never blocks the application: it is read in batches in a read-only transaction, with a per-query timeout.

Per-export limits: 1,000,000 rows, 500 MB, 30 minutes; beyond that, 422 export_limit_exceeded. Until the export is finished, its download answers 409 export_not_ready.

Personal data

Personal data columns (a customer's e-mail, phone, address…) are excluded by default. Only an ERP_OWNER or ERP_ADMIN of the company can ask to include them (include_pii: true), a role re-read both at request time and at run time; such an export is only visible to users who hold that right themselves in the company (ERP_OWNER or ERP_ADMIN, re-read on every access), its author included as long as they keep it. A client_credentials application gets this right from no scope in v1: its request is refused (403 forbidden). A delegated access (authorization_code) is admitted only if the user who granted it is an ERP_OWNER or ERP_ADMIN themselves. An application only sees the exports it created for the same subject, and never an export with personal data created by a user.

Download

The file is never served from a storage URL: it goes through Tauraco, with Cache-Control: private, no-store, X-Content-Type-Options: nosniff and X-Content-SHA256. Through the API, two ways:

• GET /exports/{job_id}/download with your token: the file as a stream (409 export_not_ready until the export has succeeded, 410 export_expired after the purge);
• POST /exports/{job_id}/download-link: a single-use signed link, valid for 60 seconds, to GET /exports/{job_id}/file?token=…, to be opened without an Authorization header (third-party tool, browser; Referrer-Policy: no-referrer). The application's rights are re-read from the database at download time. A response replayed through Idempotency-Key carries url: null: ask for a new link.

From the application, the same signed link can be issued. A link must be neither shared nor logged.

Scheduled and differential exports

An export template (datasets, columns, filters, format) can be scheduled (daily, weekly, monthly) from Scheduled exports. In differential mode, each run only takes the rows modified since the last success, with a 5-minute overlap: a record may appear twice, deduplicate on its identifier. A schedule failing for a lasting reason (rights removed, dataset unavailable) is disabled (disabled, “Disabled” on screen) and its author is notified; a transient error does not disable it. An export.completed or export.failed event is sent at the end of each run.

Example: export through the API

curl -sS -X POST "https://api.tauraco.io/public/v1/exports" \
  -H "Authorization: Bearer ${TAURACO_TOKEN}" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"datasets":[{"dataset":"invoices","filters":{"status":"PAID"}}],"format":"xlsx"}'

Body (ExportRequest): datasets, one to ten {dataset, columns, filters} objects (no columns: the dataset's default columns); format, a code from GET /integrations/formats; format_options; include_pii (false by default); file_name; delivery (download by default, or a connection from GET /integrations/connections). The 202 response returns the QUEUED export and its address in Location; follow GET /exports/{job_id} or the export.completed event. POST /exports/{job_id}/cancel cancels a queued or running export (409 if it has finished).