Replace a source’s file
const url = 'https://api.sloose.com/orgs/org_9f3c/imports/imp_4d1a/sources/src_7c2e/file';const form = new FormData();form.append('version', '1');form.append('file', 'file');form.append('sheet', 'example');form.append('label', 'example');form.append('origin', 'file');form.append('madeFrom', 'example');form.append('madeByAnswer', 'example');form.append('reshape', 'example');form.append('options', 'example');form.append('sheetName', 'example');
const options = {method: 'PUT', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://api.sloose.com/orgs/org_9f3c/imports/imp_4d1a/sources/src_7c2e/file \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: multipart/form-data' \ --form version=1 \ --form file=@file \ --form sheet=example \ --form label=example \ --form origin=file \ --form madeFrom=example \ --form madeByAnswer=example \ --form reshape=example \ --form options=example \ --form sheetName=exampleReplace the file a source reads, keeping the source’s id — the recipe’s flow is bound to it. The new bytes go under a new revision key and the old object stays, because a run’s snapshot may name it. One write under version moves the file, its reader, options, columns and count together, so a colleague sees the old file or the new one and never a source with no file.
Delimited text keeps the options the source had: a setting somebody chose survives the next file, and a null is worked out again from this one. A workbook starts afresh: sheet names the worksheet, the first with rows when absent, and its header row is found. A name somebody gave the source stays; otherwise it takes the new file’s. origin and madeFrom say where the new rows came from, and are kept when absent. madeByAnswer says which kept AI answer made the new file, and is never kept: absent, no answer made it.
The cleaning goes with the old file. Row exclusions and cell edits count rows of the file they were made on, so the source has no cleaning until one is saved for the new one.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The org id the session was issued for. A token for one org can never read another.
Example
org_9f3cThe org id the session was issued for. A token for one org can never read another.
The import id.
Example
imp_4d1aThe import id.
The source id.
Example
src_7c2eThe source id.
Request Bodyrequired
Section titled “Request Bodyrequired”object
The version this change was made against — from the last read or write.
The file, at most 50 MB: a workbook (.xlsx) or delimited text, told apart by its first bytes. A plain field is read as text.
The worksheet to read, by name. Only for a workbook; the first with rows when absent.
What to call the upload in place of the file’s own name: the name its rows arrive under, and so the one a cleared name returns to.
Where the rows came from; the source’s own when absent. A paste is called “Pasted data” and a generated sample “Generated sample” rather than after a file, and both are delimited text.
What a generated sample was asked for — only with origin=generated.
Which kept AI answer made this file, as JSON — { "turnId": "…", "index": 0 }: the turn (GET …/conversations) and the place in its targets of the reshape, sample or re-read applied to make it. What says that answer was used, where the file’s shape cannot. Absent, or not a turn and a place, the file is one no answer made: every file stored, and every new reading of one, says which answer made it or that none did. Delimited text only: no answer makes a workbook.
How this file was reshaped from the file as read at its header row, as JSON — { "steps": [ … ] }: the reshape steps in order, each counted on the grid the ones before it left, and every row a step names by its place marked (marks: the end it was nearer, its place from that end, its cells’ shape and its words) so a template can find it in another file. A template made from the import carries it. Absent, or not one, the file is kept as not reshaped. Delimited text only.
Delimited text only: how to read it, as JSON — { "delimiter": ",", "quote": "\"", "collapse": false }, any setting null or absent to be worked out from the file. For a client that wrote the text itself and knows its format; a guess is right for a file somebody chose, and can only be wrong for this.
Delimited text only: the worksheet the client made it from, which a template names the source by. The server records what it is told; for a workbook it reads the name itself.
Responses
Section titled “Responses”The source, reading the new file.
object
object
The connection Target names; null until one is chosen.
The template this import was started from or saved as.
The template version it copied: “the template has moved on” compares this.
Who started it — the person, or the person a token acts as. Null only for an import a schedule started, which is nobody’s own.
The token held, when one was.
Where it stands. An import being deleted is not returned at all: it reads as gone the moment its delete is accepted.
Whichever step the wizard of the day left it on, as that wizard names it.
The write precondition: every change names the version it was made against, and a stale one is refused 409 IMPORT_CHANGED.
The run that holds the import; every other write is refused while one does.
object
Where the rows came from: file, paste, generated, connection.
Which reader read the bytes: delimited or xlsx.
The SHA-256 of the file stored for the source, hex: the identity of its bytes, which changes with every new file and never with a new reading of the same one. With how they are read (reader, options, sheetName), what says an AI answer that proposed a change to the file (a reshape, a sample, a re-read) was not taken: the same bytes, read the same way, are still the file it was proposed for. Null for a file stored before it was kept; the sheets of one workbook share their workbook’s.
Which kept answer made this file — { turnId, index }, the turn and the reshape, sample or re-read in its targets — or null: what says such an answer was used, on the server and in the app alike, where the file’s shape cannot. Written with every file stored for the source and every new reading of it, from the upload’s madeByAnswer, and null for any other.
object
How this file was reshaped from the file as read at its header row (#1363): the steps in order, each counted on the grid the ones before it left, every row a step named by its place marked so another file’s can be found by it. Written with every file stored for the source and every new reading of it, from the upload’s reshape, and null for any other.
object
object
object
One letter a cell: b blank, n a number, t other text.
Its text cells, digits taken out, case and spaces folded, joined by |.
What the reader needs to read the file again: delimiter, sheet, header row — in the shape this build reads, whatever shape they were stored in. They are stored with the version of that shape and walked forward when read; that version is not shown.
The worksheet’s name, for a source read from one; null for text. The reader finds the sheet by its place (options.sheet); a template names it by this, because a name survives next month’s workbook having its tabs reordered.
The size of the current cleaning revision; null when the source has none.
The size of the current revision of its work — the guesses waiting on it, the ones turned down, how each used one was found; null when the source has none.
The recipe flow this source feeds, paired by id and never by label or position.
Example
{ "import": { "status": "open" }, "source": { "reshape": { "steps": [ { "marks": [ { "from": "start" } ] } ] } }}The request — its body or its query — did not match the schema. issues carries the Zod issue list.
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}No bearer, or one that is expired, revoked or no longer resolves to a member.
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}The bearer’s role is too low, or it was issued for a different org; or somebody else started this import and an operator changes only their own (code: NOT_YOURS).
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}No such import (code: IMPORT_NOT_FOUND) or source (code: SOURCE_NOT_FOUND), or it is not visible to this session.
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}Somebody changed the import since this version was read (code: IMPORT_CHANGED, with the version it is at now and updatedBy); a run holds it (code: IMPORT_RUNNING, with the runId); this deployment has no storage for imports yet (code: NOT_CONFIGURED); or a source’s reader options were written by a newer build of Sloose than this one (code: FROM_FUTURE, which is refused before anything is written).
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}The file is larger than 50 MB (code: FILE_TOO_LARGE, with the limit in bytes); or it is a workbook whose XML unpacks to more than 16 MB, more than the server reads whole — saved as CSV, the same sheet is read at any size up to the upload’s (code: WORKBOOK_TOO_LARGE, with unpacked and limit in bytes).
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}The body is not multipart/form-data (code: UNSUPPORTED_MEDIA_TYPE).
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}The file cannot be read into this source: SPREADSHEET_FORMAT, UNREADABLE_FILE, NOT_A_WORKBOOK (a sheet named for a text file) and NOT_TEXT as when adding one; NO_SUCH_SHEET for a sheet the workbook does not have; NOTHING_READ when the reading refused — an empty text, or a row of more than 1,048,576 characters in its cells or more than 16,384 cells.
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}