Generate a file, or say how to reshape one
const url = 'https://api.sloose.com/ai/source?connector=con_8f2a&keep=0199a1b2-7c3d-7e4f-8a9b-0c1d2e3f4a5b%3A3';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"question":"example","grid":[["example"]],"totalRows":1,"delimiter":",","quote":"\"","collapse":true,"rowFilter":"example","raggedRows":[{"at":1,"cells":["example"]}],"raggedCount":1,"tailRows":[{"at":1,"cells":["example"]}],"want":"filter","lands":{"steps":"any","parse":true,"filter":true},"enabledModules":["example"],"conversation":{"importId":"example","place":{"kind":"source","source":"example"},"question":"example","file":{"digest":"example","reading":"example"},"version":1,"last":{"turnId":"example","waiting":[1],"declined":[1]}},"history":[{"question":"example","answer":"example","proposed":["example"],"outcome":"example","samples":"allow"}]}'};
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/ai/source?connector=con_8f2a&keep=0199a1b2-7c3d-7e4f-8a9b-0c1d2e3f4a5b%3A3' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "question": "example", "grid": [ [ "example" ] ], "totalRows": 1, "delimiter": ",", "quote": "\"", "collapse": true, "rowFilter": "example", "raggedRows": [ { "at": 1, "cells": [ "example" ] } ], "raggedCount": 1, "tailRows": [ { "at": 1, "cells": [ "example" ] } ], "want": "filter", "lands": { "steps": "any", "parse": true, "filter": true }, "enabledModules": [ "example" ], "conversation": { "importId": "example", "place": { "kind": "source", "source": "example" }, "question": "example", "file": { "digest": "example", "reading": "example" }, "version": 1, "last": { "turnId": "example", "waiting": [ 1 ], "declined": [ 1 ] } }, "history": [ { "question": "example", "answer": "example", "proposed": [ "example" ], "outcome": "example", "samples": "allow" } ] }'Help with the source file before any of it is mapped: invent one shaped for the modules this import is for, or read the one you have and say what is wrong with it.
A reshape comes back as a recipe, not as data. Your file has as many rows as it has and the model is shown twelve, so anything it handed back would be a rewrite of the twelve. Instead it returns steps — a closed set of named operations (use_header_row, set_header, drop_rows, rename_column, drop_column, fill_down) which you apply to every row yourself. @sloose/source-csv exports reshapeSource to do exactly that; willDo is the same list in plain words, one line per step.
The file’s shape, never its values. Splitting a name into two columns or stripping a currency symbol are mapping rules — one expression on the Map step does them per field without rewriting every row — so there is no operation for them here, and asked for one the assistant says so.
Every step is dry-run before you see it, one at a time and cumulatively against the records the model was shown, so a rename can feed the fill-down after it. A step that reports a problem is dropped and named in notes.
Two answers are not steps. parse says the separator or text qualifier in use is wrong and the file should be re-read; rowFilter is an expression that is TRUE for the rows to keep, compiled and run in the sandbox against your own rows before it is offered.
What the page cannot take is not sent back. want: 'filter' (the rows’ question) takes a re-read out of the answer. lands says what else cannot land where it was asked:
steps: 'none'for a file the import holds under another tab;steps: 'no-header'for a sheet being looked at, whose header row is set with its own box, which takes every step out of an answer that moves the header row (use_header_row, ordrop_rowstaking row 1);parse: falsefor a re-read that cannot be taken: a source that is not delimited text or not read yet, or an answer about another file — a sheet being looked at, or a file held under another tab — since a re-read reads the file in force;filter: falsefor a file the import does not hold yet.
Steps taken out take their row filter with them, since it was checked on the rows those steps make. What is taken out is said in withheld (steps, parse, filter). All of these only ever remove. Every field after question, grid, totalRows and enabledModules came after this route shipped, so a value that does not parse is left out rather than refused. An answer left with nothing to apply is not charged: no steps, no re-read, no row filter and no file — words alone, or a proposal the server refused and named in notes — settles at 0 credits.
Send grid as the file parsed into raw records, header included and nothing interpreted, plus raggedRows — the records whose field count differs from the header’s, at their real positions. A file that will not parse is broken on one line and that line is never in the first twelve, so without those the answer is about the healthy part of the file. For a file that runs past the grid, send tailRows too: its last few lines (at most 5), at their real positions, since a report ends in a grand total or a footnote the head never shows. A drop may name one by the row it is shown as, as it may a ragged one. Omit grid entirely to ask for a file to be generated.
A conversation kept with the import. Name it with conversation: the import, and the place, which for this route is always a file’s Source ({ kind: 'source', source }; any other place is 400 PLACE_NOT_ANSWERED). The server then reads the conversation’s earlier turns itself and ignores history: the newest six from where replay starts, each question and answer and what it proposed, and, for the newest that proposed anything, what became of each thing it proposed, read off the import as it stands now — used, changed by hand (to what), still waiting or turned down, or not taken. A row filter is judged by the filter in force; a reshape, a sample or a re-read by which answer made the file the import holds (the source’s madeByAnswer, which the upload that applies one names), never by the file’s shape; what still waits and what was turned down by the stamps the file’s work keeps, never by the page’s word (conversation.last is not read here). Before anything is charged: the import must be this organisation’s and not being deleted (404 IMPORT_NOT_FOUND), the person must be one who may change it (403 NOT_YOURS), it must write to the connection ?connector= names (409 CONNECTION_MISMATCH), it must hold the file the place names (404 SOURCE_NOT_FOUND: a file still being added has no conversation yet, and is asked about with history; one the import held and no longer does was taken out, and is not asked about at all), and when conversation.file names the file the asker believes it holds, that must be the file it holds — the same bytes, read the same way (409 FILE_CHANGED: it was replaced, or read again under other options, since the asker last read the import, whose turn would be kept against a file the model was never shown; read the import again, and ask about the file as it is now), and when conversation.version names the version of the import the asker’s picture was built from, the import must still be at it (409 IMPORT_CHANGED, with the version it is at, updatedBy and updatedAt: what became of earlier answers is judged, and this answer’s targets recorded, against the recipe the server holds, so a question about a row filter somebody else changed since is not asked; read the import again and ask). The answer is kept as a turn and returned as turn, shaped as GET /orgs/{org}/imports/{id}/conversations shows it: the question (conversation.question, else question), the answer, what it offered as targets (filter, parse, reshape and sample, each with what its slot held when it was made), the notes — none of them saying a value of the file unless the organisation’s AI data setting shares values — what of the file it was made from, who asked and how. A turn another turn beat to its place is not kept, and not charged (409 CONVERSATION_MOVED_ON: ask again, and it carries on from where the conversation is now); nor is one whose import or file went, or whose file was replaced or read again under other options, while it was answered (404 CONVERSATION_GONE). The earlier turns go to the model only while the organisation’s AI data setting is no stricter than the loosest of what they were made from; under a stricter one the question starts afresh, notice says so, and every later question keeps to that start. A kept turn is kept for the plan’s history window from when it was asked, and goes with its file, its import and its organisation.
Without a kept conversation (a file still being added, the demo), send history, the earlier turns about this file as the page holds them, oldest first and at most six: each question, its answer, what it proposed and what became of it (outcome), with the samples its response carried. Nothing is kept. Every answer says in samples what of the file it was made from: its values (allow), their shapes (masked), or none of it (none), counting the earlier turns it was sent as well as the grid, since an answer can repeat what one of them said. A turn goes to the model only while the organisation still shares what it was made from — one made from values under allow alone, one made from shapes under allow or masked, one made from no file under any setting — and a turn that does not say is taken to have been made from values: a stricter setting starts the conversation afresh.
What the model sees. Fields the organisation has excluded from AI are withheld from every sample — never sent in any form; their examples stand in for them — from the moment they are excluded: on /ai/chat an earlier turn is replayed as it was first sent — and an organisation whose AI sample policy is deny sends it no rows at all. The same applies to what a failed expression is allowed to say back: a thrown value is a value.
What you see is your own, where it is computed for you. This policy governs the model, not this response. Evidence produced FOR the caller comes from the rows you sent, unmasked, because you are the organisation and the model is not: the sample outputs on a validated proposal, and a formula’s own results and error.
Except what mirrors the conversation. A tool_result event on /ai/chat carries what the MODEL was told, so under masked or deny it carries the model’s copy rather than yours. It is capped at 200 characters and ellipsed past that, so a short result arrives whole and a long one does not — check for the ellipsis rather than assuming either. And none of this says anything about the rest of a response, which may be a generated file or a list of destination options rather than anything of yours. An organisation set to deny is refused with SAMPLES_DENIED when a grid is sent, and can still generate. raggedRows follow the setting like the grid: masked under masked — and in a file with a column excluded from AI, sent with every cell empty under any setting, since a ragged record’s cells do not line up with its columns. tailRows follow it as the grid’s rows do, and one that is ragged as a ragged record does.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”The connection this is about, by id: one of the organisation’s, or your own. REQUIRED: absent or empty is 400 CONNECTION_REQUIRED, listing the connections this bearer may name, because nothing picks one for a request that does not say (design §14.8). Any other — another organisation’s, or another person’s — is 404 CONNECTION_NOT_FOUND.
Example
con_8f2aThe connection this is about, by id: one of the organisation’s, or your own. REQUIRED: absent or empty is 400 CONNECTION_REQUIRED, listing the connections this bearer may name, because nothing picks one for a request that does not say (design §14.8). Any other — another organisation’s, or another person’s — is 404 CONNECTION_NOT_FOUND.
The versions of the organisation’s helper libraries the import keeps (“Keep v3 for this import”), which this request evaluates in place of the current ones: comma-separated libraryId:version, one per library, as the resolved configuration names each library (libraryId) — at most as many as an import may keep (200). Each is read from the organisation’s own stored publish — nothing a request sends is run. One that names no publish of a library the organisation holds now is 409 KEPT_VERSION_NOT_FOUND, with missing; one that cannot be read is 400 BAD_INPUT. Absent, every library runs as it currently is.
Example
0199a1b2-7c3d-7e4f-8a9b-0c1d2e3f4a5b:3The versions of the organisation’s helper libraries the import keeps (“Keep v3 for this import”), which this request evaluates in place of the current ones: comma-separated libraryId:version, one per library, as the resolved configuration names each library (libraryId) — at most as many as an import may keep (200). Each is read from the organisation’s own stored publish — nothing a request sends is run. One that names no publish of a library the organisation holds now is 409 KEPT_VERSION_NOT_FOUND, with missing; one that cannot be read is 400 BAD_INPUT. Absent, every library runs as it currently is.
Header Parameters
Section titled “Header Parameters”The organisation you believe this session is in. When it is not the organisation the session is in NOW — POST /auth/session/org moves a session without issuing a new token — the request is refused with 409 ORG_CHANGED rather than served against the other organisation’s schema. Omit it and nothing changes.
The organisation you believe this session is in. When it is not the organisation the session is in NOW — POST /auth/session/org moves a session without issuing a new token — the request is refused with 409 ORG_CHANGED rather than served against the other organisation’s schema. Omit it and nothing changes.
Request Bodyrequired
Section titled “Request Bodyrequired”object
object
object
object
object
object
object
object
object
object
object
object
object
object
What to record as the question when the request asks none in words (a suggestion pressed, say). Absent, the route records the question the request asks.
The file the asker believes the import holds for the place, as the import last said it: the digest of its bytes (null for one stored before digests were kept) and how they are read — the source’s reader, options and worksheet as one string (fileReading in @sloose/core). The answer is made from the rows the request sends and its turn kept against the file the import holds, so a file replaced, or read again under other options, since the asker last read the import is refused before anything is asked or charged (409 FILE_CHANGED). Absent, the question is about whatever file the import holds.
object
The import’s version the asker’s picture of it was built from: what it last wrote or read, with nothing of its own left unwritten. What became of earlier answers is judged, and a new answer’s was recorded, from the import as the server holds it, so a question asked of a picture the import has moved on from — another person’s edit, or the asker’s own that was never saved — is refused before anything is asked or charged (409 IMPORT_CHANGED, with the version it is at and who changed it last). Absent, the question is about the import as it is.
The kept turn whose answer is live on the page — its newest that proposed anything, which an answer in words alone leaves standing — and which of its targets, by position, still wait on the page (waiting) or were turned down there (declined): what only the page knows. Read only at the formula editor’s place (formula), whose answer waits in the editor and nowhere else, and taken there only when it names the turn the question is judged against: the newest of the turns sent that proposed anything. At Source and every place of Map fields the import keeps its guesses stamped with the answer that made them, so what still waits and what was turned down is read off the stamps each file’s work keeps, and a last sent there is not read.
object
object
Responses
Section titled “Responses”What it made of the file. Nothing has been changed: the steps are yours to apply.
An answer in words, plus either a recipe (steps and willDo) or a generated file. With a conversation named, turn is the turn the answer was kept as, as the conversations list shows it.
object
This call’s id. It is also the ledger’s idempotency key.
Credits settled for this call.
Token counts, including cache reads and writes.
object
The model that answered.
object
object
object
object
object
object
object
object
object
object
Its position in the conversation at its place, from 0.
The AI route that answered it.
What the answer proposed, and where.
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
object
What the answer said that is not the answer: a caveat, what the server refused.
What of the file the answer was made from: its values (allow); the distinct values of list fields, a picklist’s or a multi-select’s, as Translate values sends them under Masked (values); their shapes (masked); or none of it (none) — counting the earlier turns it was sent with, since an answer can repeat what one of them said.
When the question was asked, which the history window counts from.
Who asked: a person, or the person whose API token asked. Null once they are deleted.
object
How the question was asked: a person’s session in the app (session), an organisation API token (api_token), or an agent over MCP (mcp).
Whether the next question at its place may send it to the model again. False for a turn before where replay starts, which a stricter AI data setting moves past everything already asked; only the newest 6 are ever sent.
Whether a draft asked it — Draft everything, Fill the gaps or Draft it anyway (draftScope): one call of the draft answers several parts, and each part’s share of the answer is kept at that part’s own place, as a turn saying so, so a later question there — and Go there — finds it (D6). A draft’s turn is sent with no earlier turns, and lands after whatever its place holds without moving where replay starts.
Which draft asked it — Draft everything, Fill the gaps or Draft it anyway: the same for every part’s turn of one draft, so the import’s AI activity lists the draft as one entry. Null for a turn no draft asked, and for a draft’s turn kept before drafts said so, which is an entry of its own.
How much of the import the draft that asked it was asked about: import, Draft everything; gaps, Fill the gaps, the parts a template’s check left open and no other; anyway, Draft it anyway, one file and module a draft found the file does not feed. Null for a turn no draft asked, and for a draft’s turn kept before drafts said, which reads as the whole import.
Said once, when the request named a conversation and this question starts afresh because the organisation’s AI data setting is stricter than the one its earlier turns were made from. Null otherwise.
Example
{ "turn": { "place": { "kind": "source" }, "route": "source", "targets": [ { "kind": "filter" } ], "samples": "allow", "askedVia": "session", "draft": false, "draftId": null, "draftScope": "import" }}The body did not match the schema (BAD_INPUT, with issues); the request named no connection (CONNECTION_REQUIRED, with connections); or keep cannot be read (BAD_INPUT); a grid was sent for an organisation that shares no rows with AI (SAMPLES_DENIED); or conversation names a place this route does not answer (PLACE_NOT_ANSWERED): it answers at a file’s Source.
object
Examplegenerated
{ "error": "example", "code": "example"}No bearer, or one that no longer resolves: a session that is unknown or expired (code: AUTH_REQUIRED), or an API token that was revoked or expired (TOKEN_REVOKED, TOKEN_EXPIRED), whose organisation is gone (ORG_NOT_FOUND) or whose member or user row is (MEMBERSHIP_GONE).
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"}Not enough AI credits (CREDITS_EXHAUSTED), or the organisation is suspended (SUSPENDED). balance shows what is left, needed what this asked for, planIncludesCredits whether the plan includes any each period, and renewsAt, where a subscription renews them, when they come back.
object
AI credits. Included credits reset each period; purchased ones do not.
object
Included + purchased − reserved
The least the action would hold: its price, or for an action priced by how much it reads, the cheapest band, since such an action holds what the balance covers of its dearest band. The balance fell short of it — which is not the same as nothing left.
When the credits ran short (CREDITS_EXHAUSTED) under a subscription that renews them — active, not set to cancel, and renewing on a plan with an allowance, whether charged to a card or billed by invoice (whose credits come as each invoice is issued, #1337): when that allowance comes back, the end of the current period. Absent on a plan that includes none, on a trial, under a subscription that is cancelled, set to cancel or past due, when the plan it moves to at the period’s end includes none, for a suspension, and when the plan could not be read.
When the credits ran short (CREDITS_EXHAUSTED): whether the organisation’s plan, as the catalogue has it, includes AI credits each period — a staff override changes this period’s limits, not that. Absent for a suspension, and when the plan could not be read — which says nothing either way.
Examplegenerated
{ "error": "example", "code": "example", "balance": { "included": 1, "purchased": 1, "reserved": 1, "available": 1, "periodStart": "example", "periodEnd": "example" }, "needed": 1, "renewsAt": "example", "planIncludesCredits": true}The conversation’s import is one this person may not change: an operator asks about only an import they started. Like every route behind a session: a session signed in but in no organisation is refused code: NO_ORG, a banned person code: BANNED, and a closed organisation code: ORG_CLOSED.
object
Example
{ "code": "NOT_YOURS"}No such organisation (ORG_NOT_FOUND); ?connector= names a connection this person may not use (CONNECTION_NOT_FOUND); the conversation’s import is not this organisation’s, or is being deleted (IMPORT_NOT_FOUND); the import does not hold the file its place names (SOURCE_NOT_FOUND); or the import or that file went, or the file was replaced or read again under other options, while the answer was written, so it was not kept and nothing was charged (CONVERSATION_GONE).
object
Example
{ "code": "ORG_NOT_FOUND"}The organisation has no module registry yet (ORG_NOT_CONFIGURED); you sent X-Sloose-Org and this session is in a different organisation now (ORG_CHANGED); a version keep names is not one the organisation holds now (KEPT_VERSION_NOT_FOUND, with missing); the conversation’s import writes to another connection than ?connector= names (CONNECTION_MISMATCH); conversation.file names another file than the import holds for the place — it was replaced, or read again under other options, since it was read — so the question was not asked and nothing was charged (FILE_CHANGED); conversation.version names another version than the import is at — somebody changed it since the asker read it — so the question was not asked and nothing was charged (IMPORT_CHANGED, with the version it is at, updatedBy and updatedAt); or another turn landed at the conversation’s place while this one was answered, so this answer was not kept and nothing was charged (CONVERSATION_MOVED_ON).
object
IMPORT_CHANGED only: the version the import is at now.
IMPORT_CHANGED only: who changed it last.
object
The app an agent changed it through over MCP, when its last write was one: userId is then the person whose agent it was.
IMPORT_CHANGED only: when it was last changed.
KEPT_VERSION_NOT_FOUND only: each kept publish keep names that the organisation does not hold now, by its library’s id and number.
object
Example
{ "code": "ORG_NOT_CONFIGURED"}The model declined. category says why.
object
Example
{ "code": "AI_REFUSED"}The model’s answer could not be used.
object
Example
{ "code": "AI_BAD_OUTPUT"}AI is not configured on this deployment (AI_NOT_CONFIGURED): unconfigured paths say so rather than failing. Or the model could not be asked just now (AI_UNAVAILABLE) — the gateway out of credits, rate limited or failing, or the provider unavailable: nothing was changed and nothing was charged, so the same request can be sent again shortly. Or the restore switch is on (code: MAINTENANCE): every route but /health and /robots.txt is refused before anything is read, with Retry-After (the operator’s ADMIN_TOKEN alone is let through to POST /staff/people/{id}/delete, and to nothing else).
Headers
Section titled “Headers”Seconds until asking again is worth it (300 while the switch is on).