Upload API
How do I push files from a script or pipeline?
Vantage has no file upload API for scripts or pipelines today. Files go in through the browser: the app issues a five-minute upload ticket to a signed-in person and the browser posts the file straight to the dataplane. This page describes that endpoint, why a script cannot use it, and what machine callers use instead.
| Need | What to use |
|---|---|
| A person loads a CSV or Parquet file | Upload a file in the app |
| A pipeline pushes rows on a schedule | An n8n-type source whose workflow posts JSON batches to /api/internal/load-batch with a service token the operator holds |
| Tables you build yourself in the warehouse | Bring your own dbt, then register the tables |
Why a script cannot upload
The ticket is the only credential /api/upload/file accepts. Only a signed-in session can ask
for one, and it is signed with UPLOAD_TOKEN_SECRET, an operator secret shared by the app and
the dataplane. Anyone holding that secret can sign tickets for every workspace, so it is never
handed to a script. There are no per-workspace upload keys.
The endpoint, for reference
POST {PUBLIC_DATAPLANE_URL}/api/upload/file (on the cluster, https://uploads.<domain>).
The ingress exempts /api/upload/* from its operator sign-in because the ticket authenticates
the request.
| Part | Rule |
|---|---|
Authorization | Bearer <ticket>; checked before any byte is written, otherwise 401 Invalid upload ticket |
| Body | multipart/form-data, one file in field file |
| File name | ends in .csv or .parquet |
| Size | up to MAX_FILE_SIZE_BYTES, 512 MiB by default |
| Columns | must include id; must not include tenant_id, _ingested_at, _source_id; names match [A-Za-z_][A-Za-z0-9_]* |
| Response | Body |
|---|---|
| 200 | { "rowsLoaded": 1200, "dataset": "sales" } |
| 400 | { "message": "File is missing the required \"id\" column" }; the source's status turns error with the same message |
| 404 | { "message": "Unknown data source" } |
The file lands in tenant_<slug>.raw_<source name slug>, with the column types inferred from
the file.