Map to Talonic Types

Anchor custom doctypes to Talonic base types: list the type catalog, get embedding-ranked mapping suggestions, and preview published classifier doctypes.

Every custom doctype anchors to a Talonic type (a type in the Ontology's Talonic base) so the dual-axis classifier always has a built-in anchor alongside your custom label. These endpoints help you build and verify those anchors. List the full Talonic type catalog — several hundred types, each with an ontology_type_id, a display name, and a canonical_path breadcrumb — to populate a picker, embedding-match a set of your doctypes to get ranked suggestions, and preview the published custom doctypes the classifier will actually apply.

Suggest-mappings is stateless: it runs over the doctypes you post and persists nothing, so an authoring UI can call it on unsaved edits (it carries read scope for the same reason). For each doctype it returns the current_maps_to you already authored, a confident auto target (or null), an ambiguous flag, and ranked candidates with cosine-similarity scores. The auto decision is conservative: the top candidate must clear an auto-apply similarity threshold and beat the runner-up by a clear margin — otherwise auto is null and, when two or more candidates are plausible, ambiguous is true so a human picks.

The same matcher runs inside [POST /v1/customer-ontologies/import](import-customer-ontology) to auto-fill blank maps_to anchors, so what you see from suggest-mappings is exactly what import would apply. maps_to itself is advisory free-text: an anchor the catalog does not contain is stored, not rejected, so a typo shows up as a doctype that never gains its Talonic-axis anchor — validate your anchors against the talonic-types catalog when importing definitions from code.

Matching is embedding-based over the doctype's key, name, and signals versus each Talonic type. It degrades safely: when the embedding model is unavailable, suggest-mappings returns empty candidates (auto: null, ambiguous: false) instead of erroring, and the manual maps_to path keeps working. An empty candidates array therefore means either "nothing plausible" or "matching unavailable" — in both cases, pick from the catalog by hand.

curl -s -X POST https://api.talonic.com/v1/customer-ontologies/suggest-mappings \
  -H "Authorization: Bearer tlnc_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"doctypes":[{"key":"delivery_note","name":"Lieferschein","signals":{"keywords":["Lieferschein","Warenausgang"]}}]}'

[
  {
    "key": "delivery_note",
    "name": "Lieferschein",
    "current_maps_to": null,
    "auto": "delivery_note",
    "ambiguous": false,
    "candidates": [
      {
        "ontology_type_id": "delivery_note",
        "name": "Delivery Note",
        "canonical_path": "Logistics & Shipping > Delivery Note",
        "score": 0.812
      },
      {
        "ontology_type_id": "packing_list",
        "name": "Packing List",
        "canonical_path": "Logistics & Shipping > Packing List",
        "score": 0.641
      }
    ]
  }
]

[
  {
    "ontology_type_id": "request_for_quotation",
    "name": "Request for Quotation",
    "canonical_path": "Sales & Ordering > Request for Quotation"
  },
  {
    "ontology_type_id": "purchase_order",
    "name": "Purchase Order",
    "canonical_path": "Sales & Ordering > Purchase Order"
  }
]