File uploads
Upload CSV, TSV, JSON, NDJSON or XML files, map their fields, and replace them safely.
Uploads are a built-in source for your own files. An upload needs no credential, endpoint or connection, and it does not count toward your connection limit. Stored originals count toward your storage. Reading an upload does not use your source capture budget.
Availability
File uploads are not yet generally available on xentropy.ai. Contact
support@xentropy.ai to request access. Until uploads are enabled for your
account, uploads fail with PROVIDER_DISABLED.
Upload a file
Agents can upload small files with the data_uploads_create MCP tool, which
takes base64 content of up to 5 MiB. Without content, the tool returns a link
for uploading in the browser. The REST route is POST /api/v1/data/uploads:
send the file as the raw request body, declare the format in Content-Type
and the file name in X-Filename. Uploading needs a browser session or the
data:write scope.
Formats
| Format | Detection | Options |
|---|---|---|
| CSV | .csv, text/csv, content | Delimiter (one character), header row |
| TSV | .tsv or .tab, text/tab-separated-values | Header row |
| JSON | .json, application/json | Record path: a top-level array, or the path to an array such as data |
| NDJSON | .ndjson or .jsonl, application/x-ndjson | One record per line |
| XML | .xml, application/xml or text/xml | Record path, a simple absolute element path such as /orders/order |
- Every format can be gzip-compressed (
.gz). Zip, 7z, RAR, bzip2, xz, zstd and tar archives are refused. - Parquet, Avro and ORC files are read through an S3-compatible connection, not uploads.
- Files must be UTF-8. A byte-order mark is removed. Other encodings, such as
Latin-1 or UTF-16, fail with
ENCODING_UNSUPPORTED. Re-save the file as UTF-8. - The file extension decides the format. If the file has no known extension,
the declared
Content-Typedecides, and then the content itself.
Mapping rules
- Nested JSON objects flatten to dotted paths, such as
user.login. - Arrays follow the shape's
arraysmode.jsonkeeps an array as JSON text,dropleaves it empty, andexplode-firsttakes the first item. - In XML, attributes become
@namefields and element text becomes#text. XML with aDOCTYPEor entity declarations is refused. - CSV headers that contain dots, such as
shipping.city, are treated as nested paths. - Type hints:
unix-secondsandunix-msread numbers as datetimes.- A date field can take a pattern built from
YYYY,MMandDD. - A boolean field can take tokens such as
yes,y/no,n. - A datetime without a zone needs a time zone (
TIMEZONE_REQUIRED).
- A non-finite number (NaN, Infinity) becomes empty, with a
NONFINITE_NULLEDwarning.
Replace, download and delete
- Replacing a file uploads a new version of it (
PUT /api/v1/data/uploads/:id). If the new file's schema differs, Xentropy shows the changes and stores nothing until you confirm. Over the API, the request fails withSCHEMA_CHANGEDandconfirmRequired: true. Repeat it with?confirm=true. - Each saved dataset revision records the original's SHA-256. If the file was
replaced after that revision was saved, reading the revision fails with
SOURCE_CHANGED. - Only you can download your original. It is always served as an attachment
(
application/octet-stream), never displayed in the browser. - A file that backs datasets cannot be deleted directly (
DATASET_IN_USE). Delete the dataset instead. The original is deleted together with its last dataset. - An upload that is never saved as a dataset expires after 24 hours.
Limits
| Limit | Value |
|---|---|
| Upload size, plain or compressed | 25 MiB |
Upload through MCP (data_uploads_create) | 5 MiB |
| Decompressed size | 5× the upload limit |
| Rows | 50,000, counted before anything is stored |
| Fields | 100 |
| Characters per value | 10,000 |
| JSON and XML nesting depth | 32 levels |
| Preview rows | 100 |
| Unsaved upload lifetime | 24 hours |
Errors
| Code | Cause | What to do |
|---|---|---|
EMPTY_INPUT | The file is empty or has no records | Upload a file with data |
FORMAT_UNSUPPORTED | An archive, a columnar file, or an undetectable format | Upload CSV, TSV, JSON, NDJSON or XML (optionally .gz) |
ENCODING_UNSUPPORTED | The file is not valid UTF-8 | Re-save it as UTF-8 |
DECOMPRESSION_LIMIT | Gzip expands beyond 5× the upload limit | Upload a smaller file |
PARSE_FAILED | The syntax is invalid, or the gzip data is corrupt | Fix the file |
RAGGED_ROW / DUPLICATE_HEADER | A CSV row has the wrong number of cells, or two headers have the same name | Fix the file, or turn off the header row |
DEPTH_EXCEEDED | Nesting is deeper than 32 levels | Flatten the file |
XML_DOCTYPE_REFUSED | The XML has a DOCTYPE or entity declarations | Remove them |
RECORD_PATH_NOT_FOUND | The record path does not exist | Choose a path from the preview |
LIMIT_EXCEEDED | The file has more than 50,000 rows, or exceeds another limit | Split the file, or filter it before uploading |
VALUE_TOO_LONG | A value is longer than 10,000 characters | Drop the field, or shorten the values |
TYPE_MISMATCH | A value does not match the field's type (with its row and field) | Change the type, or fix the value |
TIMEZONE_REQUIRED | A datetime has no zone | Set the field's time zone |
INVALID_SHAPE | The field mapping is invalid | Correct the mapping |
SCHEMA_CHANGED | A replacement changes the schema | Review the changes, then confirm |
SOURCE_CHANGED | The file was replaced after this revision was saved | Read the current revision |
DATASET_IN_USE | The file backs datasets | Delete the dataset instead |
NOT_FOUND | The upload does not exist, or its original is no longer stored | Upload the file again |
Google BigQuery
Connect BigQuery with a read-only service account key, read tables at no query cost, and run SELECT queries under a dry-run estimate and a hard cost cap.
S3-compatible storage
Read Parquet, Avro, ORC, CSV, TSV, JSON, NDJSON and XML objects from Cloudflare R2, Amazon S3 or another S3-compatible endpoint.