Propose descriptions, formats, examples, cases and rules for a module’s fields, and which to exclude from AI
const url = 'https://api.sloose.com/ai/field-setup?connector=con_8f2a';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"module":"Deals","fields":["example"],"want":["description"],"pasted":[{"field":"example","values":["example"]}],"version":1,"preview":true}'};
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/field-setup?connector=con_8f2a' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "module": "Deals", "fields": [ "example" ], "want": [ "description" ], "pasted": [ { "field": "example", "values": [ "example" ] } ], "version": 1, "preview": true }'Proposes, for up to 50 fields of one module, what an administrator might write about each: a description, a format, examples, the case its values are written in (writtenAs), a rule they must pass (mustBe), and whether its values look personal enough to exclude from AI (excludeFromAi, with why) — only what want asks for.
The model is shown the fields, and a sample of the module’s own records. Each field goes as the CRM describes it — label, kind, length, options, whether it is required — with whatever the org has already written about it. To show what the fields hold, one page of the module’s records — the 20 most recently changed, naming only the fields asked about — is read from the CRM through the connection, for the ask and for its preview, and kept nowhere — Sloose stores none of it, and the ask tells the AI gateway to keep its metadata (the org, the feature, a request id, the model, its size, tokens, cost and status) and not what it carried (cf-aig-collect-log-payload: false): each field’s distinct values among them, each up to its first 200 characters, go to the model as the org’s AI data setting allows — as they are under allow, as shapes under masked. Under deny nothing is read, and a field excluded from AI is never read under any setting. A CRM that does not answer leaves the ask to go on with the fields alone. Values the person pastes (pasted) follow the same setting, and are not shown for a field excluded from AI either. notes says what was read — none too, for a module with no records or a scope of excluded fields — and how it was shown. Since the records are read afresh, a preview shows them as they are when it is asked for.
The server decides what is offered. Only the fields asked about, each once, and only what was asked for. An example is offered only when its field would take it — a value of its kind, within its length, and for a picklist one of its options in the option’s own spelling — and never when it is, or holds, a value read from the records for the ask — any field’s, compared folded, a phone by its digits, a date as the date and a number as the number, and an address that keeps a read local part — and such an example is never quoted back: an example is made up. A proposal to exclude a field from AI is offered only for one not excluded already. A case only when the field’s kind takes it (text and a long text any, an email lower case only). A rule only when the server would store it (mustBeRefusal: it reads only the value, the org’s helpers and plain built-ins), never for a lookup, and only after it held for every example it is tried on — the proposal’s own and the ones the org has written for the field, each in the case in force once the proposal is taken, run in the sandbox with the org’s helpers as they are now. A rule that did not hold is told to the model once, for those fields alone, and its second answer stands for them; one that still does not hold is left out and the rest of its field’s proposal offered. A rule with no example to try it on is not offered. What is left out is said in dropped. An answer that offers nothing is not charged.
Nothing is kept or written. Write what the person takes through PATCH /orgs/{org}/config/fields/{module}, with proposedBy: 'ai' on each field taken as it was proposed, under registryVersion.
version is required — the registryVersion the fields were read at — and a configuration that moved since is refused before anything is spent (409 REGISTRY_CONFLICT), so the model is never shown other fields than the person was.
preview: true answers exactly what the model would be sent — the system prompt and the message — and sends nothing. It is free, and it is built by the same function as the request, so what the page shows is what goes.
Administrators only. What a module’s fields say is an administrator’s to write. An API token at the admin role may ask: the answer proposes and writes nothing.
Priced by the fields asked about (field_setup).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”The connection this is about, by id: one of the org’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 org’s, or another person’s — is 404 CONNECTION_NOT_FOUND.
Example
con_8f2aThe connection this is about, by id: one of the org’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 org’s, or another person’s — is 404 CONNECTION_NOT_FOUND.
Header Parameters
Section titled “Header Parameters”The org you believe this session is in. When it is not the org 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 org’s schema. Omit it and nothing changes.
The org you believe this session is in. When it is not the org 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 org’s schema. Omit it and nothing changes.
Request Bodyrequired
Section titled “Request Bodyrequired”object
The module, by its key or its API name — any module the connection holds, chosen for imports or not.
Example
DealsThe fields to ask about, by API name, at most 50. Any field the CRM still returns may be named, a hidden one or one the CRM fills in itself included. Omitted: every field the CRM returns that is neither hidden nor filled in by the CRM — refused (TOO_MANY_FIELDS) when that is more than 50, so the module is asked about in parts.
What to propose for each field.
Values the person pasted for a field — at most 20 a field, each at most 200 characters, and each field named once — shown to the model as the org’s AI data setting allows. Every field named must be one asked about (PASTED_NOT_ASKED).
object
The configuration version the fields were read at (registryVersion, as GET /orgs/{org}/config/fields/{module} answers it). Moved since, the ask is refused uncharged (409 REGISTRY_CONFLICT, with the current version), so the model is never shown fields other than the ones the person was.
True: answer exactly what the model would be sent, and send nothing. Free.
Responses
Section titled “Responses”The proposals, with what they cost; or, with preview, exactly what would be sent.
Proposals for the fields asked about.
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.
The configuration version the fields were read at: write what is taken under it (If-Match).
What is proposed for one field. Only what was asked for, and only where there is something to say.
object
The case every value is written in — only one the field’s kind takes.
A rule every value must pass, and what it says of one that does not. Offered only after it held for every example it was tried on, in the sandbox with the org’s helpers.
object
The field’s values look personal — they name, identify or reach a person — and why, in a few words that read after “This looks personal:”. Taken, it is written as excludeFromAi: true. Only for a field not excluded already.
object
What the model said that is not offered, in words: an example its field would not take, a case its kind does not take, a rule the server would not store or that did not hold for its examples, a field it was not asked about.
How the ask was made, where the person should know: how many of the module’s records were read and shown, and in what form, or why none were; and that their pasted values were shown as shapes, or not at all.
Exactly what the model would be sent. Nothing was sent, and nothing charged.
object
The model that would be asked.
The fields the ask is about, by API name.
The system prompt, exactly as it would be sent.
The message, exactly as it would be sent.
Example
{ "fields": [ { "writtenAs": "upper" } ]}The body did not match the schema (BAD_INPUT, with issues), or the request named no connection (CONNECTION_REQUIRED, with connections): every AI request names the connection whose modules and fields it is about (?connector=, design §14.8).
object
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"}Not enough AI credits (CREDITS_EXHAUSTED), or the org 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 org’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}Below an administrator (ROLE_REQUIRED): what a module’s fields say is an administrator’s to write, and so is asking for it. An API token at the admin role may ask, since the answer proposes and writes nothing. A read-only staff view of the org is refused (IMPERSONATION_READ_ONLY).
object
Examplegenerated
{ "error": "example", "code": "example"}No such org (ORG_NOT_FOUND); ?connector= names a connection this person may not use (CONNECTION_NOT_FOUND); or the connection has no such module (MODULE_NOT_FOUND).
object
Example
{ "code": "ORG_NOT_FOUND"}You sent X-Sloose-Org and this session is in a different org now (ORG_CHANGED); or the configuration moved since the version sent (REGISTRY_CONFLICT, with the current registryVersion). Neither is charged.
object
REGISTRY_CONFLICT only: the version the configuration is at now.
Example
{ "code": "ORG_CHANGED"}The model declined (AI_REFUSED, category says why). Or, before anything is spent: a field named that this module has no row for (UNKNOWN_FIELDS), or one the CRM no longer returns (DEPARTED_FIELDS); values pasted for a field not asked about (PASTED_NOT_ASKED); with no fields named, a module with none to fill in (NO_FIELDS), or more than 50 (TOO_MANY_FIELDS, with count and most) — name them in parts.
object
object
object
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.
object
Example
{ "code": "AI_NOT_CONFIGURED"}