Skip to content
SlooseSloose

Write or fix one expression

POST
/ai/formula
curl --request POST \
  --url 'https://api.sloose.com/ai/formula?connector=con_8f2a&keep=0199a1b2-7c3d-7e4f-8a9b-0c1d2e3f4a5b%3A3' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "moduleKey": "example", "apiName": "example", "purpose": "update_guard", "currentExpression": "example", "question": "example", "columns": [ "example" ], "sampleRows": [], "sampleRowNumbers": [ 1 ], "marked": [ { "sample": 1, "shouldBe": "example" } ], "outputs": { "rows": 1, "shapes": [ { "shape": "example", "count": 1, "failing": 1 } ], "otherShapes": 1, "otherRows": 1 }, "conversation": { "importId": "example", "place": { "kind": "source", "source": "example" }, "question": "example", "file": { "digest": "example", "reading": "example" }, "version": 1, "last": { "turnId": "example", "waiting": [ 1 ], "declined": [ 1 ] } } }'

Answers a question about one expression: a destination field’s value (apiName), or one of the expressions that write to no field — an update guard, an import gate or the row filter (purpose), each of which must return true or false.

The expression is compiled and run against your sample rows before it is returned, so what comes back is something that at least executes — not a plausible-looking string that fails on the first row. A guard that reads old or next, and an expression that reads records (rec.*), is compiled only: those exist during a run. Except the row filter, which runs before any record of the row exists: an answer that reads records is sent back to be rewritten, and when none of the answers can be used, the last comes back with valid false and the reason in error.

A conversation kept with the import. Name it with conversation — the import, and the formula editor’s place, { kind: 'formula', source, subject }, whose subject is the one expression it edits: a field’s formula, the value an existing record is recognised by or a lookup’s search value (editing, with its module and field), or an update guard’s, an import gate’s or the row filter’s (purpose). Any other place is 400 PLACE_NOT_ANSWERED, and a body whose moduleKey, apiName or purpose is not what the subject names is 400 SCOPE_NOT_PLACE, before anything is charged. The server reads the place’s earlier turns itself: the newest six from where replay starts, and for the newest that proposed anything, what became of it — used or changed by hand, read off the import’s recipe, and, where conversation.last says so, still waiting in the editor or turned down there: an answer waits in the editor that holds it, which nothing stores, so that is the asker’s word, taken when it names that same turn. The import and its file are checked as POST /ai/source checks them (404 IMPORT_NOT_FOUND, 403 NOT_YOURS, 409 CONNECTION_MISMATCH, 404 SOURCE_NOT_FOUND, 409 FILE_CHANGED, 409 IMPORT_CHANGED), none of it charged. The answer is kept as a turn and returned as turn, the expression it proposed as its one target — none for an answer with valid false; one another turn beat to its place is not kept, and not charged (409 CONVERSATION_MOVED_ON).

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.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
connector

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.

string
Example
con_8f2a

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.

keep

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.

string
Example
0199a1b2-7c3d-7e4f-8a9b-0c1d2e3f4a5b:3

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.

Header Parameters

Section titled “Header Parameters”
x-sloose-org

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.

string

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”
Media typeapplication/json
object
moduleKey

The module the expression belongs to. Required unless purpose is row_filter, which belongs to the file.

string
>= 1 characters
apiName

The destination field the expression writes to. One of apiName and purpose is required.

string
>= 1 characters
purpose

What the expression is for when it writes to no field: update_guard (true updates the matched record, false leaves it), import_gate (true imports this row’s record for the module, false skips it) or row_filter (true keeps the row, false drops it before anything is mapped). Each must return true or false.

string
Allowed values: update_guard import_gate row_filter
currentExpression
string | null
question
required

What you want the expression to do, in your own words.

string
>= 1 characters <= 4000 characters
columns
required

The source file’s column headings, in order.

Array<string>
>= 1 items <= 500 items
sampleRows

Sample rows for context. At most 3 are used, besides up to 5 the person marked as wrong (marked); the rest are ignored rather than refused. Columns named like a field excluded from AI are withheld (never sent, in any form), and an organisation whose AI sample policy is deny sends it none at all — the policy governs what the model sees, not what comes back to you.

Array<object>
default:

One source row: column name → cell value, always as a string.

object
key
additional properties
string
sampleRowNumbers

Each sample row’s number — its place in its file, from 1, which excluding or filtering rows never changes — one per row of sampleRows and in its order; a list of another length is refused. The model is shown each sample by it and names a row by it. Absent, a row is known only by its place among the samples.

Array<integer>
marked

Sample rows the person marked as coming out wrong, at most 5, each by its index in sampleRows and with what it should be, if they said. A marked row is used beyond the 3 others, and the model is told the person says it comes out wrong. What it should be is the person’s own words and is sent as they wrote it.

Array<object> | null
<= 5 items
object
sample
required

Its index in sampleRows.

integer
shouldBe

What the person says it should come out as, in their own words.

string
<= 200 characters
outputs

What the current expression makes of every row of the file, counted by shape — each output masked (digits 9, capitals X, other letters x, punctuation and spaces kept), a blank and an error each a shape of their own — the commonest 12 with how many rows of each fail the field’s check, and how many rows the rest hold. Shown to the model under the allow and masked settings; under deny only how many shapes there are.

object
rows
required
integer
shapes
required
Array<object>
<= 12 items
object
shape
required
string
<= 120 characters
count
required
integer
failing
required
integer
otherShapes
required
integer
otherRows
required
integer
conversation

A conversation kept with the import, at the formula editor’s place ({ kind: 'formula', source, subject }, the expression it edits; any other place is 400 PLACE_NOT_ANSWERED): the field, module or purpose the body names must be what the subject names (400 SCOPE_NOT_PLACE). See the operation description.

object
importId
required
string
>= 1 characters <= 100 characters
place
required
One of:
object
kind
required
string
Allowed values: source
source
required
string
/^[A-Za-z0-9_-]{1,64}$/
question

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.

string
>= 1 characters <= 8000 characters
file

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
digest
required
string | null
<= 128 characters
reading
required
string | null
<= 16384 characters
version

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.

integer
>= 1
last

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
turnId
required
string
>= 1 characters <= 100 characters
waiting
Array<integer>
<= 500 items
declined
Array<integer>
<= 500 items

Responses

Section titled “Responses”

200

Section titled “200”

The expression, an explanation, and what it produced on your sample rows. With a conversation, turn is the turn it was kept as.

Media typeapplication/json

An expression that compiled and ran against the samples.

object
requestId
required

This call’s id. It is also the ledger’s idempotency key.

string
credits
required

Credits settled for this call.

number
usage
required

Token counts, including cache reads and writes.

object
key
additional properties
model
required

The model that answered.

string
turn
object
id
required
string
place
required
One of:
object
kind
required
string
Allowed values: source
source
required
string
/^[A-Za-z0-9_-]{1,64}$/
seq
required

Its position in the conversation at its place, from 0.

integer
route
required

The AI route that answered it.

string
Allowed values: source chat auto-map match value-map formula explain
question
required
string
answer
required
string
targets
required

What the answer proposed, and where.

Array
<= 500 items
One of:
object
kind
required
string
Allowed values: filter
where
required
object
source
required
string
/^[A-Za-z0-9_-]{1,64}$/
what
required
string
was
required
string | null
notes
required

What the answer said that is not the answer: a caveat, what the server refused.

Array<string>
samples
required

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.

string
Allowed values: allow values masked none
askedAt
required

When the question was asked, which the history window counts from.

string
askedBy
required

Who asked: a person, or the person whose API token asked. Null once they are deleted.

object
userId
required
string
name
required
string
askedVia
required

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

string
Allowed values: session api_token mcp
replayed
required

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.

boolean
draft

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.

boolean
draftId

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.

string | null
draftScope

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.

string | null
Allowed values: import gaps anyway
turns
Array<object>
object
id
required
string
place
required
One of:
object
kind
required
string
Allowed values: source
source
required
string
/^[A-Za-z0-9_-]{1,64}$/
seq
required

Its position in the conversation at its place, from 0.

integer
route
required

The AI route that answered it.

string
Allowed values: source chat auto-map match value-map formula explain
question
required
string
answer
required
string
targets
required

What the answer proposed, and where.

Array
<= 500 items
One of:
object
kind
required
string
Allowed values: filter
where
required
object
source
required
string
/^[A-Za-z0-9_-]{1,64}$/
what
required
string
was
required
string | null
notes
required

What the answer said that is not the answer: a caveat, what the server refused.

Array<string>
samples
required

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.

string
Allowed values: allow values masked none
askedAt
required

When the question was asked, which the history window counts from.

string
askedBy
required

Who asked: a person, or the person whose API token asked. Null once they are deleted.

object
userId
required
string
name
required
string
askedVia
required

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

string
Allowed values: session api_token mcp
replayed
required

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.

boolean
draft

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.

boolean
draftId

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.

string | null
draftScope

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.

string | null
Allowed values: import gaps anyway
notice

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.

string | null
key
additional properties
Example
{
  "turn": {
    "place": {
      "kind": "source"
    },
    "route": "source",
    "targets": [
      {
        "kind": "filter"
      }
    ],
    "samples": "allow",
    "askedVia": "session",
    "draft": false,
    "draftId": null,
    "draftScope": "import"
  },
  "turns": [
    {
      "place": {
        "kind": "source"
      },
      "route": "source",
      "targets": [
        {
          "kind": "filter"
        }
      ],
      "samples": "allow",
      "askedVia": "session",
      "draft": false,
      "draftId": null,
      "draftScope": "import"
    }
  ]
}

400

Section titled “400”

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); the module or field is not the organisation’s (UNKNOWN_MODULE, UNKNOWN_FIELD); conversation names a place this route does not answer (PLACE_NOT_ANSWERED); or the field, module or purpose asked about is not the expression its place is about (SCOPE_NOT_PLACE).

Media typeapplication/json
object
error
required
string
code
required
string
key
additional properties
Examplegenerated
{
  "error": "example",
  "code": "example"
}

401

Section titled “401”

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

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"
}

402

Section titled “402”

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.

Media typeapplication/json
object
error
required
string
code
required
string
balance
required

AI credits. Included credits reset each period; purchased ones do not.

object
included
required
number
purchased
required
number
reserved
required
number
available
required

Included + purchased − reserved

number
periodStart
required
string
periodEnd
required
string
needed
required

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.

number
renewsAt

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.

string
planIncludesCredits

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.

boolean
key
additional properties
Examplegenerated
{
  "error": "example",
  "code": "example",
  "balance": {
    "included": 1,
    "purchased": 1,
    "reserved": 1,
    "available": 1,
    "periodStart": "example",
    "periodEnd": "example"
  },
  "needed": 1,
  "renewsAt": "example",
  "planIncludesCredits": true
}

403

Section titled “403”

The import conversation names is one this person may not change: an operator asks about only an import they started (NOT_YOURS). 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.

Media typeapplication/json
object
error
required
string
code
required
string
Allowed values: NOT_YOURS NO_ORG BANNED ORG_CLOSED
key
additional properties
Example
{
  "code": "NOT_YOURS"
}

404

Section titled “404”

No such organisation (ORG_NOT_FOUND); ?connector= names a connection this person may not use (CONNECTION_NOT_FOUND); the import named is not this organisation’s, or is being deleted (IMPORT_NOT_FOUND); it does not hold the file the place is about (SOURCE_NOT_FOUND); or the import or that file went, or the file was replaced or read again, while the answer was written, so it was not kept and nothing was charged (CONVERSATION_GONE).

Media typeapplication/json
object
error
required
string
code
required
string
Allowed values: ORG_NOT_FOUND CONNECTION_NOT_FOUND IMPORT_NOT_FOUND SOURCE_NOT_FOUND CONVERSATION_GONE
key
additional properties
Example
{
  "code": "ORG_NOT_FOUND"
}

409

Section titled “409”

The organisation has no module registry yet (ORG_NOT_CONFIGURED); the 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 import writes to another connection than ?connector= names (CONNECTION_MISMATCH); the file named is not the one the import holds (FILE_CHANGED); the import moved on from the version named (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 (CONVERSATION_MOVED_ON). None of these is charged.

Media typeapplication/json
object
error
required
string
code
required
string
Allowed values: ORG_NOT_CONFIGURED ORG_CHANGED KEPT_VERSION_NOT_FOUND CONNECTION_MISMATCH FILE_CHANGED IMPORT_CHANGED CONVERSATION_MOVED_ON
version

IMPORT_CHANGED only: the version the import is at now.

integer
updatedBy

IMPORT_CHANGED only: who changed it last.

object
userId
required
string | null
tokenId
required
string | null
scheduleId
required
string | null
app

The app an agent changed it through over MCP, when its last write was one: userId is then the person whose agent it was.

string | null
name
required
string | null
updatedAt

IMPORT_CHANGED only: when it was last changed.

string
missing

KEPT_VERSION_NOT_FOUND only: each kept publish keep names that the organisation does not hold now, by its library’s id and number.

Array<object>
object
library
required
string
version
required
number
key
additional properties
Example
{
  "code": "ORG_NOT_CONFIGURED"
}

422

Section titled “422”

The model declined. category says why.

Media typeapplication/json
object
error
required
string
code
required
string
Allowed values: AI_REFUSED
category
required
string
key
additional properties
Example
{
  "code": "AI_REFUSED"
}

502

Section titled “502”

The model’s answer could not be used.

Media typeapplication/json
object
error
required
string
code
required
string
Allowed values: AI_BAD_OUTPUT
key
additional properties
Example
{
  "code": "AI_BAD_OUTPUT"
}

503

Section titled “503”

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

Media typeapplication/json
One of:
object
error
required
string
code
required
string
Allowed values: AI_NOT_CONFIGURED AI_UNAVAILABLE
key
additional properties
Example
{
  "code": "AI_NOT_CONFIGURED"
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds until asking again is worth it (300 while the switch is on).

Report a problem with this page

sloose.com