> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solo.one/llms.txt
> Use this file to discover all available pages before exploring further.

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



## OpenAPI

````yaml POST /v1/furnishing/mapping/suggest
openapi: 3.1.0
info:
  title: SOLO Network API
  version: v1
servers:
  - url: https://api.solo.one
    description: Production
  - url: https://api.sandbox.solo.one
    description: Sandbox
security: []
paths:
  /v1/furnishing/mapping/suggest:
    post:
      tags:
        - Furnishing — Mapping Dry-Run
      summary: >-
        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.
      operationId: mapping_suggest_v1_furnishing_mapping_suggest_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MappingSuggestRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingSuggestResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    MappingSuggestRequest:
      properties:
        roots:
          additionalProperties: true
          type: object
          title: Roots
          description: alias -> source-dialect schema for the mapping's roots.
        target:
          title: Target
          description: 'Target anchor: a registry $id string or an inline target document.'
        mode:
          type: string
          enum:
            - structure
            - structure_with_sample
          title: Mode
          description: >-
            What the model may see: source structure only, or structure plus the
            pasted sample values.
          default: structure
        sample:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Sample
          description: >-
            alias -> value sample input line; required (and only used) in
            structure_with_sample mode.
        mapping:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Mapping
          description: >-
            The entry's current mapping/1 document when partially authored;
            preserved verbatim.
        pins:
          additionalProperties:
            $ref: '#/components/schemas/MappingSuggestPin'
          type: object
          title: Pins
          description: >-
            Target pointer -> pipeline-owned pin; stamped canonically into every
            suggestion.
        heading:
          anyOf:
            - type: string
            - type: 'null'
          title: Heading
          description: Entry UI heading, for model context.
        required_paths:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Required Paths
          description: >-
            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).
      type: object
      required:
        - roots
        - target
      title: MappingSuggestRequest
    MappingSuggestResponse:
      properties:
        document:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Document
          description: >-
            The merged, verified mapping/1 document (required fields the source
            cannot provide may be left unmapped — see omissions); null when
            nothing verified.
        verified:
          type: boolean
          title: Verified
        findings:
          items:
            $ref: '#/components/schemas/MappingFinding'
          type: array
          title: Findings
          description: Last verify findings when verified is false.
        suggested_paths:
          items:
            type: string
          type: array
          title: Suggested Paths
          description: Newly suggested target paths (UI convention, [] = element scope).
        rationales:
          additionalProperties:
            type: string
          type: object
          title: Rationales
          description: Target path -> one-line model rationale, suggested paths only.
        omissions:
          additionalProperties:
            type: string
          type: object
          title: Omissions
          description: >-
            Required target paths the model deliberately left unmapped -> its
            one-line reason.
        attempts:
          type: integer
          title: Attempts
        usage:
          $ref: '#/components/schemas/MappingSuggestUsage'
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: Human-readable outcome note when verified is false.
      type: object
      required:
        - verified
        - findings
        - suggested_paths
        - rationales
        - attempts
        - usage
      title: MappingSuggestResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    MappingSuggestPin:
      properties:
        kind:
          type: string
          enum:
            - const
            - root
          title: Kind
        value:
          anyOf:
            - {}
            - type: 'null'
          title: Value
          description: Constant value (const pins).
        root:
          anyOf:
            - type: string
            - type: 'null'
          title: Root
          description: Root alias the pin reads (root pins).
        pointer:
          type: string
          title: Pointer
          description: JSON Pointer into the root; empty = whole-root read.
          default: ''
      type: object
      required:
        - kind
      title: MappingSuggestPin
    MappingFinding:
      properties:
        ast_path:
          type: string
          title: Ast Path
        code:
          type: string
          title: Code
        expected:
          anyOf:
            - type: string
            - type: 'null'
          title: Expected
        found:
          anyOf:
            - type: string
            - type: 'null'
          title: Found
        hint:
          anyOf:
            - type: string
            - type: 'null'
          title: Hint
        label:
          anyOf:
            - type: string
            - type: 'null'
          title: Label
      type: object
      required:
        - ast_path
        - code
      title: MappingFinding
    MappingSuggestUsage:
      properties:
        input_tokens:
          type: integer
          title: Input Tokens
        output_tokens:
          type: integer
          title: Output Tokens
        cache_read_input_tokens:
          type: integer
          title: Cache Read Input Tokens
        cache_creation_input_tokens:
          type: integer
          title: Cache Creation Input Tokens
      type: object
      required:
        - input_tokens
        - output_tokens
        - cache_read_input_tokens
        - cache_creation_input_tokens
      title: MappingSuggestUsage
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.