Add sources from a file

POST

/orgs/{org}/imports/{id}/sources

const url = 'https://api.sloose.com/orgs/org_9f3c/imports/imp_4d1a/sources';
const form = new FormData();
form.append('version', '1');
form.append('file', 'file');
form.append('candidates', 'example');
form.append('flowIds', 'example');
form.append('sourceIds', '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: 'POST', 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 POST \
  --url https://api.sloose.com/orgs/org_9f3c/imports/imp_4d1a/sources \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form version=1 \
  --form file=@file \
  --form candidates=example \
  --form flowIds=example \
  --form sourceIds=example \
  --form label=example \
  --form origin=file \
  --form madeFrom=example \
  --form madeByAnswer=example \
  --form reshape=example \
  --form options=example \
  --form sheetName=example

Upload a file and make one source from it — or, from a workbook, one per worksheet — in one write under version.

A file is routed by its first bytes, never by its name. A workbook (.xlsx) is read by the workbook reader; anything else is delimited text, its delimiter, quoting and folding worked out from the file. An .xls or .ods is refused naming the one step that fixes it (422 SPREADSHEET_FORMAT).

From a workbook, candidates names the worksheets to add; absent, every worksheet with rows under its header is added. Each becomes its own source, in workbook order, with its own options — { sheet, headerRow }, the header row found per sheet — and every one of them reads the one stored copy of the file. A worksheet that cannot be read fails alone and is named in failed; when none can be, nothing is written (422 NOTHING_READ). Delimited text is one source, stored with { delimiter, quote, collapse } all null: worked out from the file each time it is read, as the wizard stores them.

The bytes are stored once, exactly as uploaded, under a key the server mints — no route takes one from a client — and before the sources are written. An upload that loses the version race takes its file back at once; one whose write failed without saying whether it landed leaves the file, and the nightly sweep deletes it after a day if nothing names it.

madeByAnswer says which kept AI answer made the file — its reshape, sample or re-read, applied — and is what says that answer was used; absent, or with a workbook, no answer made it.

Each source is named where its rows came from: the file’s name, with · <worksheet> for a sheet; “Pasted data” or “Generated sample” for those origins. A name another source of the import already has is numbered.

A source’s id may be the client’s. sourceIds names the id of each source made, paired exactly as flowIds is — the wizard keeps its own (source-1, source-2) because its flows are bound to them, and an id is unique within its import, not across imports. One this import already holds is refused (409 SOURCE_TAKEN); absent, the server mints one. An id removed from an import may be given again: nothing else is keyed by it once its source is gone, and every stored object sits under a revision of its own.

Authorizations

sessionAuth
apiTokenAuth

Parameters

Path Parameters

org

required

The org id the session was issued for. A token for one org can never read another.

string

Example

org_9f3c

The org id the session was issued for. A token for one org can never read another.

required

The import id.

string

Example

imp_4d1a

The import id.

Request Body^required

multipart/form-data

object

version

required

The version this change was made against — from the last read or write.

integer

>= 1

file

required

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.

string format: binary

candidates

A JSON array of worksheet names to add, e.g. ["Accounts","Contacts"]. Absent: every worksheet with rows. Only for a workbook.

string

flowIds

A JSON array of recipe flow ids, one per source made — paired with candidates by position when they are given, else with the sources in workbook order. Absent: minted. A flow id this import already uses is refused.

string

sourceIds

A JSON array of source ids, one per source made, paired as flowIds is. Each is 1 to 64 letters, digits, hyphens or underscores. Absent: minted. A source id this import already holds is refused.

string

label

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.

string

<= 200 characters

origin

Where the rows came from; file when absent. A paste is called “Pasted data” and a generated sample “Generated sample” rather than after a file, and both are delimited text.

string

Allowed values: file paste generated

madeFrom

What a generated sample was asked for — only with origin=generated.

string

<= 4000 characters

madeByAnswer

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.

string

reshape

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.

string

options

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.

string

sheetName

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.

string

<= 200 characters

Responses

201

Added.

application/json

object

import

required

object

required

string

orgId

required

string

connectorId

required

The connection Target names; null until one is chosen.

string | null

templateId

required

The template this import was started from or saved as.

string | null

templateVersion

required

The template version it copied: “the template has moved on” compares this.

integer | null

name

required

string

createdByUserId

required

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.

string | null

tokenId

required

The token held, when one was.

string | null

createdByScheduleId

required

string | null

status

required

Where it stands. An import being deleted is not returned at all: it reads as gone the moment its delete is accepted.

string

Allowed values: open running attention done

currentStep

required

Whichever step the wizard of the day left it on, as that wizard names it.

string | null

currentStage

required

string | null

completedSteps

required

Array<string>

enabledModules

required

Array<string>

version

required

The write precondition: every change names the version it was made against, and a stale one is refused 409 IMPORT_CHANGED.

integer

updatedByUserId

required

string | null

updatedByTokenId

required

string | null

updatedByScheduleId

required

string | null

runningRunId

required

The run that holds the import; every other write is refused while one does.

string | null

lastRunAt

required

string | null

createdAt

required

string

updatedAt

required

string

sources

required

The sources made, in workbook order, each with its columns and count.

Array<object>

object

required

string

position

required

integer

label

required

string

defaultLabel

required

string | null

origin

required

Where the rows came from: file, paste, generated, connection.

string

reader

required

Which reader read the bytes: delimited or xlsx.

string | null

connectorId

required

string | null

madeFrom

required

string | null

byteSize

required

integer | null

digest

required

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.

string | null

madeByAnswer

required

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

turnId

required

string

>= 1 characters <= 100 characters

index

required

integer

<= 499

reshape

required

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

steps

required

Array<object>

>= 1 items

object

required

string

>= 1 characters

marks

Array<object>

object

from

required

string

Allowed values: start end

required

integer

>= 1

shape

required

One letter a cell: b blank, n a number, t other text.

string

/^[bnt]*$/

text

required

Its text cells, digits taken out, case and spaces folded, joined by |.

string

key

additional properties

options

required

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.

object | null

sheetName

required

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.

string | null

columns

required

Array<string>

rowCount

required

integer

cleaningBytes

required

The size of the current cleaning revision; null when the source has none.

integer | null

workBytes

required

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.

integer | null

flowId

required

The recipe flow this source feeds, paired by id and never by label or position.

string | null

createdAt

required

string

failed

required

The worksheets asked for that could not be read. Always empty for text.

Array<object>

object

sheet

required

The worksheet, as it was asked for.

string

reason

required

Why it could not be read, in words a person can act on.

string

Example

{
  "import": {
    "status": "open"
  },
  "sources": [
    {
      "reshape": {
        "steps": [
          {
            "marks": [
              {
                "from": "start"
              }
            ]
          }
        ]
      }
    }
  ]
}

400

The request — its body or its query — did not match the schema. issues carries the Zod issue list.

application/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

401

No bearer, or one that is expired, revoked or no longer resolves to a member.

application/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

403

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).

application/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

404

No such import, or it is not visible to this session (code: IMPORT_NOT_FOUND).

application/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

409

As every write (IMPORT_CHANGED, IMPORT_RUNNING, NOT_CONFIGURED); a flow id in flowIds is already another source’s (code: FLOW_TAKEN); or a source id in sourceIds is already one of this import’s sources (code: SOURCE_TAKEN).

application/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

413

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).

application/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

415

The body is not multipart/form-data (code: UNSUPPORTED_MEDIA_TYPE).

application/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

422

The file cannot be made into a source: an .xls or .ods (SPREADSHEET_FORMAT, with the problem), a workbook the reader cannot open (UNREADABLE_FILE), worksheets named for a text file (NOT_A_WORKBOOK), a workbook sent as a paste or a sample (NOT_TEXT), or nothing in it could be read (NOTHING_READ, with failed for a workbook) — as of a text with a row of more than 1,048,576 characters in its cells, or more than 16,384 cells, more than the server reads in one.

application/json

The error envelope every non-2xx answer uses.

object

error

required

Human-readable explanation.

string

code

Machine-readable reason. Absent on a few legacy 400s.

string

key

additional properties

Example^generated

{
  "error": "example",
  "code": "example"
}

Report a problem with this page

Add sources from a file

Authorizations

Parameters

Path Parameters

Example

Example

Request Bodyrequired

Responses

201

Example

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

404

Examplegenerated

409

Examplegenerated

413

Examplegenerated

415

Examplegenerated

422

Examplegenerated

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated