Skip to main content
POST
AI-suggest a mapping/1 document for one entry — verified, but required fields the source cannot provide stay unmapped (reported via omissions) rather than fabricated.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
roots
Roots · object
required

alias -> source-dialect schema for the mapping's roots.

target
any
required

Target anchor: a registry $id string or an inline target document.

mode
enum<string>
default:structure

What the model may see: source structure only, or structure plus the pasted sample values.

Available options:
structure,
structure_with_sample
sample
Sample · object | null

alias -> value sample input line; required (and only used) in structure_with_sample mode.

mapping
Mapping · object | null

The entry's current mapping/1 document when partially authored; preserved verbatim.

pins
Pins · object

Target pointer -> pipeline-owned pin; stamped canonically into every suggestion.

heading
string | null

Entry UI heading, for model context.

required_paths
Required Paths · object | null

UI target path -> label of fields the policy's enforcement facet queries (annotate-only priorities: the model binds them when plausible; unmappable ones land in omissions, never failures).

Response

Successful Response

verified
boolean
required
findings
MappingFinding · object[]
required

Last verify findings when verified is false.

suggested_paths
string[]
required

Newly suggested target paths (UI convention, [] = element scope).

rationales
Rationales · object
required

Target path -> one-line model rationale, suggested paths only.

attempts
integer
required
usage
MappingSuggestUsage · object
required
document
Document · object | null

The merged, verified mapping/1 document (required fields the source cannot provide may be left unmapped — see omissions); null when nothing verified.

omissions
Omissions · object

Required target paths the model deliberately left unmapped -> its one-line reason.

message
string | null

Human-readable outcome note when verified is false.