Files

A file is an uploaded blob — usually a spreadsheet (xlsx, csv, ods) staged for a mass import. You upload a file (up to 50 MB by default) with the files:write ability, then read its metadata or preview its sheets — both of which need imports:read instead. On this page you'll upload files, retrieve their metadata, and preview a spreadsheet's sheets before importing.

The file model

Name
object
Type
string
Description
Always file.
Name
id
Type
string
Description
Unique identifier, e.g. file_00a1b2c3d4e5f607.
Name
filename
Type
string
Description
Original name of the uploaded file, e.g. units.xlsx. Nullable.
Name
extension
Type
string
Description
File extension without the dot, e.g. xlsx. Nullable.
Name
size
Type
integer
Description
Size of the file in bytes. Nullable.
Name
created_at
Type
string
Description
ISO 8601 timestamp of the upload. Nullable.

The file preview model

Name
object
Type
string
Description
Always file.preview.
Name
file
Type
string
Description
The id of the previewed file, e.g. file_00a1b2c3d4e5f607.
Name
sheets
Type
array
Description
One entry per worksheet in the spreadsheet (see below).

The sheet object

Each entry in sheets describes one worksheet — enough to build an import mapping and rows value without downloading the file.

Name
index
Type
integer
Description
Zero-based position of the sheet in the workbook.
Name
name
Type
string
Description
The sheet's tab name.
Name
header
Type
array
Description
The column labels taken from the first row.
Name
examples
Type
array
Description
Up to two example data rows, each an array of cell values.
Name
rows
Type
integer
Description
Data row count, with the header row excluded.

POST/v1/files

Upload a file

Uploads a file as multipart/form-data in a single shot (max 50 MB by default). Spreadsheets can then be previewed and imported. Requires files:write — note that reading a file back needs imports:read instead. Accepts an optional Idempotency-Key header.

Required attributes

Name
file
Type
string
Description
The file to upload, sent as a binary multipart/form-data part. Do not set a JSON content type.

Request

POST

/v1/files

curl https://api.synexcloud.com/v1/files \
  -H "Authorization: Bearer $SYNEX_API_KEY" \
  -F "file=@units.xlsx"

Response

{
  "object": "file",
  "id": "file_00a1b2c3d4e5f607",
  "filename": "units.xlsx",
  "extension": "xlsx",
  "size": 20480,
  "created_at": "2026-07-12T09:31:00Z"
}

GET/v1/files/:file

Retrieve a file

Retrieves a file's metadata by id. Requires imports:read.

Request

GET

/v1/files/file_00a1b2c3d4e5f607

curl https://api.synexcloud.com/v1/files/file_00a1b2c3d4e5f607 \
  -H "Authorization: Bearer $SYNEX_API_KEY"

Response

{
  "object": "file",
  "id": "file_00a1b2c3d4e5f607",
  "filename": "units.xlsx",
  "extension": "xlsx",
  "size": 20480,
  "created_at": "2026-07-12T09:31:00Z"
}

GET/v1/files/:file/preview

Preview a spreadsheet

Parses a previously uploaded spreadsheet and returns, per sheet, the header labels, up to two example rows, and the data row count — everything you need to build an import mapping and rows value. Requires imports:read.

Request

GET

/v1/files/file_00a1b2c3d4e5f607/preview

curl https://api.synexcloud.com/v1/files/file_00a1b2c3d4e5f607/preview \
  -H "Authorization: Bearer $SYNEX_API_KEY"

Response

{
  "object": "file.preview",
  "file": "file_00a1b2c3d4e5f607",
  "sheets": [
    {
      "index": 0,
      "name": "Units",
      "header": ["Capacity", "Alias"],
      "examples": [
        ["4500", "unit-01"],
        ["4800", "unit-02"]
      ],
      "rows": 120
    }
  ]
}