Skip to content
SlooseSloose

Explain validation problems, and propose fixes

POST
/ai/explain
curl --request POST \
  --url https://api.sloose.com/ai/explain \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "problems": [ { "id": "example", "severity": "error", "where": "example", "module": "example", "apiName": "example", "message": "example", "rows": [ 1 ] } ], "columns": [ "example" ], "sampleRows": [], "enabledModules": [ "example" ], "mappings": { "additionalProperty": { "additionalProperty": "example" } } }'

Takes the problems the engine reported and explains them in the org’s own vocabulary, proposing a fix where there is one the widget can apply.

This is the moment AI earns its place: not at the start, where the free matcher is already good, but here, where somebody is stuck. Proposals are returned for a person to accept — nothing is applied.

Fields the org has annotated as personal data are masked before any sample leaves the server, and an org whose AI sample policy is deny sends no rows at all.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

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

The validation problems in front of the user. At most 40.

Array<object>
>= 1 items <= 40 items
object
id
required
string
>= 1 characters <= 120 characters
severity
required
string
Allowed values: error warning
where
required
string
>= 1 characters <= 40 characters
module
string
<= 80 characters
apiName
string
<= 120 characters
message
required
string
>= 1 characters <= 2000 characters
rows
Array<integer>
<= 50 items
columns
required

The source file’s column headings, in order.

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

Sample rows for context. At most 5 are used; the rest are ignored rather than refused. Fields annotated as personal data are masked before anything leaves the server, and an org whose AI sample policy is deny sends none at all.

Array<object>
default:

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

object
key
additional properties
string
enabledModules
Array<string>
mappings

The current mappings, so the explanation can refer to them.

object
key
additional properties
object
key
additional properties

Responses

Section titled “Responses”

200

Section titled “200”

One explanation per problem, with a proposed fix where one is possible.

Media typeapplication/json

Explanations, and applicable fixes where they exist.

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
key
additional properties
Examplegenerated
{
  "requestId": "example",
  "credits": 1,
  "usage": {
    "additionalProperty": "example"
  },
  "model": "example"
}

400

Section titled “400”

The body did not match the schema (BAD_INPUT, with issues), or a named module or field does not exist.

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

402

Section titled “402”

Not enough AI credits, or the org is suspended. balance shows what is left.

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
key
additional properties
Examplegenerated
{
  "error": "example",
  "code": "example",
  "balance": {
    "included": 1,
    "purchased": 1,
    "reserved": 1,
    "available": 1,
    "periodStart": "example",
    "periodEnd": "example"
  }
}

404

Section titled “404”

No such org.

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

409

Section titled “409”

The org has no module registry yet — run discovery and enable some modules first.

Media typeapplication/json
object
error
required
string
code
required
string
Allowed values: ORG_NOT_CONFIGURED
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. Unconfigured paths say so rather than failing.

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