Docs
Connections

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

Open Datasets and drop a file into the upload area.
Xentropy detects the format and compression, then shows a mapping preview of the first 100 rows.
Adjust the delimiter, header row or record path if needed. Then set each field's type and name, and choose which fields to include.
Save the dataset. You can then create an artifact from it.

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

FormatDetectionOptions
CSV.csv, text/csv, contentDelimiter (one character), header row
TSV.tsv or .tab, text/tab-separated-valuesHeader row
JSON.json, application/jsonRecord path: a top-level array, or the path to an array such as data
NDJSON.ndjson or .jsonl, application/x-ndjsonOne record per line
XML.xml, application/xml or text/xmlRecord 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-Type decides, and then the content itself.

Mapping rules

  • Nested JSON objects flatten to dotted paths, such as user.login.
  • Arrays follow the shape's arrays mode. json keeps an array as JSON text, drop leaves it empty, and explode-first takes the first item.
  • In XML, attributes become @name fields and element text becomes #text. XML with a DOCTYPE or entity declarations is refused.
  • CSV headers that contain dots, such as shipping.city, are treated as nested paths.
  • Type hints:
    • unix-seconds and unix-ms read numbers as datetimes.
    • A date field can take a pattern built from YYYY, MM and DD.
    • 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_NULLED warning.

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 with SCHEMA_CHANGED and confirmRequired: 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

LimitValue
Upload size, plain or compressed25 MiB
Upload through MCP (data_uploads_create)5 MiB
Decompressed size5× the upload limit
Rows50,000, counted before anything is stored
Fields100
Characters per value10,000
JSON and XML nesting depth32 levels
Preview rows100
Unsaved upload lifetime24 hours

Errors

CodeCauseWhat to do
EMPTY_INPUTThe file is empty or has no recordsUpload a file with data
FORMAT_UNSUPPORTEDAn archive, a columnar file, or an undetectable formatUpload CSV, TSV, JSON, NDJSON or XML (optionally .gz)
ENCODING_UNSUPPORTEDThe file is not valid UTF-8Re-save it as UTF-8
DECOMPRESSION_LIMITGzip expands beyond 5× the upload limitUpload a smaller file
PARSE_FAILEDThe syntax is invalid, or the gzip data is corruptFix the file
RAGGED_ROW / DUPLICATE_HEADERA CSV row has the wrong number of cells, or two headers have the same nameFix the file, or turn off the header row
DEPTH_EXCEEDEDNesting is deeper than 32 levelsFlatten the file
XML_DOCTYPE_REFUSEDThe XML has a DOCTYPE or entity declarationsRemove them
RECORD_PATH_NOT_FOUNDThe record path does not existChoose a path from the preview
LIMIT_EXCEEDEDThe file has more than 50,000 rows, or exceeds another limitSplit the file, or filter it before uploading
VALUE_TOO_LONGA value is longer than 10,000 charactersDrop the field, or shorten the values
TYPE_MISMATCHA value does not match the field's type (with its row and field)Change the type, or fix the value
TIMEZONE_REQUIREDA datetime has no zoneSet the field's time zone
INVALID_SHAPEThe field mapping is invalidCorrect the mapping
SCHEMA_CHANGEDA replacement changes the schemaReview the changes, then confirm
SOURCE_CHANGEDThe file was replaced after this revision was savedRead the current revision
DATASET_IN_USEThe file backs datasetsDelete the dataset instead
NOT_FOUNDThe upload does not exist, or its original is no longer storedUpload the file again

On this page