Skip to content
SlooseSloose

Change a source

PATCH
/orgs/{org}/imports/{id}/sources/{sid}
curl --request PATCH \
  --url https://api.sloose.com/orgs/org_9f3c/imports/imp_4d1a/sources/src_7c2e \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "version": 1, "label": "example", "options": { "additionalProperty": "example" }, "position": 1 }'

Rename a source, read it under new options, or move it — under version, in one write with the bump. A change that changes nothing is answered with the source as it stands and moves no version.

New options re-read the stored file, so the columns and the count follow them, and a reading that refuses changes nothing (422 NOTHING_READ). Like a replaced file, a new reading drops the source’s cleaning — its exclusions and edits counted rows of the old reading — and says that no kept AI answer made it (madeByAnswer null): the rows are not the ones an answer left.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “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.

id
required

The import id.

string
Example
imp_4d1a

The import id.

sid
required

The source id.

string
Example
src_7c2e

The source id.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
version
required

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

integer
>= 1
label

What the source is called. Blank puts back the name its rows arrived under; a name another source has is numbered.

string
<= 200 characters
options

The reader’s options, the keys given replacing the stored ones. Delimited text: delimiter (, \t ; | or a space), quote (" or '), collapse (boolean) — each null to work it out from the file. A workbook: sheet and headerRow, both counted from 0; a new sheet without a headerRow has its header row found. Any other key is refused.

object
key
additional properties
position

Where the source sits among the import’s sources, which are listed by position and then in the order they were added.

integer
>= -1000000 <= 1000000
Examplegenerated
{
  "version": 1,
  "label": "example",
  "options": {
    "additionalProperty": "example"
  },
  "position": 1
}

Responses

Section titled “Responses”

200

Section titled “200”

The source as it now stands.

Media typeapplication/json
object
import
required
object
id
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
source
required
object
id
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
op
required
string
>= 1 characters
marks
Array<object>
object
from
required
string
Allowed values: start end
at
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
Example
{
  "import": {
    "status": "open"
  },
  "source": {
    "reshape": {
      "steps": [
        {
          "marks": [
            {
              "from": "start"
            }
          ]
        }
      ]
    }
  }
}

400

Section titled “400”

The body did not match the schema, or options named a key the source’s reader does not have (code: INVALID_BODY, with issues).

Media typeapplication/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
Examplegenerated
{
  "error": "example",
  "code": "example"
}

401

Section titled “401”

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

Media typeapplication/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
Examplegenerated
{
  "error": "example",
  "code": "example"
}

403

Section titled “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).

Media typeapplication/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
Examplegenerated
{
  "error": "example",
  "code": "example"
}

404

Section titled “404”

No such import (IMPORT_NOT_FOUND) or source (SOURCE_NOT_FOUND); or the file new options would re-read is not in storage (FILE_NOT_FOUND).

Media typeapplication/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
Examplegenerated
{
  "error": "example",
  "code": "example"
}

409

Section titled “409”

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). Or the stored file is a workbook whose XML unpacks to more than the server reads whole (code: WORKBOOK_TOO_LARGE, with unpacked and limit in bytes).

Media typeapplication/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
Examplegenerated
{
  "error": "example",
  "code": "example"
}

422

Section titled “422”

The source has no stored file to read under options (code: NO_FILE), or the file will not read under them (code: NOTHING_READ) — a sheet that is not there, a header row with nothing in it, a row of more than 1,048,576 characters in its cells or more than 16,384 cells.

Media typeapplication/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
Examplegenerated
{
  "error": "example",
  "code": "example"
}

Report a problem with this page