Copy page

Documentation

Search Examples

This page shows how to search the Tungaloy catalog and how to read the returned values.

Use POST /v1/catalog/smart-search for normal natural-language questions. Use POST /v1/catalog/search when you need structured filters, pagination, columnDefinitions, or nextSuggestedFilters.

Response Basics

Most catalog search responses contain these top-level fields:

Field	Meaning
query	Normalized search conditions used by the backend.
searchMode	Search mode actually used, such as dimension, description, or compatible_insert.
resultCount	Total number of matched records before pagination.
returnedCount	Number of records included in this response.
hasMore	true when more results are available.
nextOffset	Offset to use for the next page.
columnDefinitions	Human-readable meanings and units for item fields.
items	Matched catalog records.
warnings	Non-fatal warnings.
nextSuggestedFilters	Suggested filters for narrowing broad result sets.

Each item normally includes:

Field	Meaning
ITEMNUM	Tungaloy item number.
DESCRIPTION	Product/model description.
MainApplication	Main application category.
SubApplication	Sub application category.
product_name	Product name group.
series	Product series or family.
ITEMTYPE	Item type. Common values: I insert, T tool, S solid tool, H holder, A accessory, K kit.
compatible_insert	Compatible insert model, when available.
itemSpec.E-catalog_url	Tungaloy E-catalog URL for the item.

Application And Returned Values

The same response schema is used across all applications, but the most useful returned values differ by application.

Main application	Typical sub applications	Common search filters	Common returned values
ExternalTurning	Inserts, For 55deg Rhombic insert, For 80deg Rhombic insert, For Round insert, For Square insert, For 80deg Trigon insert, For Triangular insert	H, B, LF, LH, HF, WF, RE, KAPR, HAND, compatible_insert, ITEMTYPE, Grade	Shank size, holder geometry, hand, approach angle, compatible insert, tightening torque, insert grade and corner radius.
InternalTurning	Inserts, For 55deg Rhombic insert, For 80deg Rhombic insert, For Triangular insert, For Miniature machining	DMIN, DCONMS, LF, LH, H, WF, RE, HAND, compatible_insert, ITEMTYPE	Minimum bore diameter, connection diameter, bar length, hand, insert shape compatibility.
Grooving_and_Parting	External grooving, Internal grooving, Face grooving, Parting-off, Inserts	CW, CWN, CWX, CDX, CUTDIA, DMIN, DCONMS, HAND, ITEMTYPE, Grade, RE	Groove width, max cutting depth, cut-off diameter, hand, insert grade.
Threading	Ext-Threading, Internal Threading, Ext. Thread-Milling, Int. Thread-Milling, Taps, Inserts	TP, TPN, TPX, TPI, DC, LF, NOF, DCONMS, ITEMTYPE, Grade	Thread pitch, pitch range, tap/thread-mill diameter, number of flutes, insert grade.
Milling	Face Milling, Shoulder Milling, High-Feed Milling, Slot Milling, Profile Milling, Multi-Functional tools, Inserts	cutter_diameter, DC, DCX, CW, APMX, LF, OAL, NOF, ZEFP, RE, KAPR, DCONMS, compatible_insert	Cutter diameter, max diameter, slot width, depth of cut, flute count, approach angle, shank diameter, compatible insert.
Holemaking	General Drilling, Chamfering, Reaming, Gundrill, BTA_system, Accessories	DC, DCN, DCX, DCONMS, LF, OAL, LU, LPR, PL, SIG, ULDR, Oil hole	Drill diameter, min/max cutting diameter, pilot length, lead angle, usable length, oil-hole availability.
Boring	Boring_Bars, Cartridges, SwissBore_tools, PINZBOHR_tools, Face contact interface	DCN, DCX, DCONMS, LF, LPR, D1, OAL, SS	Min/max boring diameter, connection diameter, protruding length, shank size.
ToolingSystem	Face contact interface, Straight shape, Tapered shape interface, Accessories, Devices, Tools	SS, DCONMS, DCONWS, DCSFMS, LF, OAL, LPR, CSP, CSI, KWW	Interface size, connection diameters, overall length, key width, accessory/device details.

Example 1: Natural-Language Search

Use POST /v1/catalog/smart-search when the user asks a normal product question.

Code
{
  "query": "Find 1 mm end mills",
  "limit": 10,
  "language": "en"
}

Typical result:

Code
{
  "query": "Find 1 mm end mills",
  "result": "Found matching milling tools with 1 mm cutter diameter. Examples include EPD05R100U0100W05, ELD05R100U0100W03, and TECA010H3-04C06CF-R.05. Narrow by square end mill, ball end mill, shoulder milling, profile milling, flute count, overall length, shank diameter, or corner radius."
}

Use this endpoint first when the query contains ambiguous terms, mixed dimensions, product family names, or natural-language wording.

Example 2: Milling Tools With 1 mm Cutter Diameter

Use structured search when you need raw values such as resultCount, hasMore, nextOffset, and columnDefinitions.

Request:

Code
{
  "search_mode": "dimension",
  "main_application": "Milling",
  "filters": [
    {
      "field": "cutter_diameter",
      "op": "eq",
      "value": 1
    }
  ],
  "limit": 3,
  "offset": 0,
  "include_definitions": true
}

Response excerpt:

Code
{
  "searchMode": "dimension",
  "resultCount": 123,
  "returnedCount": 3,
  "hasMore": true,
  "nextOffset": 3,
  "columnDefinitions": {
    "DC": "Cutting Diameter [mm]",
    "DCX": "Max Cutting Diameter [mm]",
    "NOF": "Number of Flutes",
    "APMX": "Max Depth of Cut [mm]",
    "KAPR": "Approach Angle [deg]",
    "DCONMS": "Connection Diameter [mm]"
  },
  "items": [
    {
      "ITEMNUM": "3106317",
      "DESCRIPTION": "EPD05R100U0100W05",
      "MainApplication": "Milling",
      "SubApplication": "Shoulder Milling",
      "product_name": "TungQuad",
      "series": "EPD05",
      "ITEMTYPE": "T",
      "DC": 1,
      "DCX": 1,
      "NOF": 5,
      "APMX": 0.157,
      "KAPR": 90,
      "DCONMS": 1,
      "compatible_insert": "SDMT050204PN-MJ / SD*T050204..."
    },
    {
      "ITEMNUM": "3112200",
      "DESCRIPTION": "ELD05R100U0100W03",
      "MainApplication": "Milling",
      "SubApplication": "Shoulder Milling",
      "product_name": "TungQuad",
      "series": "ELD05",
      "ITEMTYPE": "T",
      "DC": 1,
      "DCX": 1,
      "NOF": 3,
      "APMX": 0.953,
      "KAPR": 90,
      "DCONMS": 1,
      "compatible_insert": "SDMT050204PN-MJ / SD*T050204..."
    },
    {
      "ITEMNUM": "3323808",
      "DESCRIPTION": "TECA010H3-04C06CF-R.05",
      "MainApplication": "Milling",
      "SubApplication": "Shoulder Milling",
      "product_name": "VariableMeister Square",
      "series": "TECA-H3-CF-R",
      "ITEMTYPE": "S",
      "DC": 1,
      "DCX": 1,
      "NOF": 3,
      "APMX": 4,
      "RE": 0.05,
      "DCONMS": 6,
      "Grade": "KS15F"
    }
  ]
}

Notes:

• cutter_diameter is a virtual Milling search alias. It matches either DC or DCX.
• DC is the effective cutting diameter.
• DCX is the maximum outside cutting diameter.
• For slot width or cutter width, use CW, not cutter_diameter.

Example 3: DrillMeister 10 mm Drill Heads

Request:

Code
{
  "search_mode": "dimension",
  "main_application": "Holemaking",
  "series": "DrillMeister",
  "filters": [
    {
      "field": "DC",
      "op": "eq",
      "value": 10
    }
  ],
  "limit": 3,
  "include_definitions": true
}

Response excerpt:

Code
{
  "searchMode": "dimension",
  "resultCount": 17,
  "returnedCount": 3,
  "hasMore": true,
  "nextOffset": 3,
  "columnDefinitions": {
    "DC": "Cutting Diameter [mm]",
    "DCN": "Min Cutting Diameter [mm]",
    "DCX": "Max Cutting Diameter [mm]",
    "LF": "Overall Length [mm]",
    "PL": "Pilot Length [mm]",
    "LPR": "Protruding Length [mm]",
    "SIG": "Lead Angle [deg]"
  },
  "items": [
    {
      "ITEMNUM": "6758038",
      "DESCRIPTION": "DMH100",
      "MainApplication": "Holemaking",
      "SubApplication": "General Drilling",
      "product_name": "DrillMeister",
      "series": "DrillMeister",
      "ITEMTYPE": "I",
      "DC": 10,
      "DCN": 10,
      "DCX": 10,
      "LF": 4.58,
      "PL": 1.47,
      "LPR": 6.05,
      "SIG": 140
    },
    {
      "ITEMNUM": "6758135",
      "DESCRIPTION": "DMC100",
      "MainApplication": "Holemaking",
      "SubApplication": "General Drilling",
      "product_name": "DrillMeister",
      "series": "DrillMeister",
      "ITEMTYPE": "I",
      "DC": 10,
      "DCN": 10,
      "DCX": 10,
      "LF": 4.58,
      "PL": 2.09,
      "LPR": 6.67,
      "SIG": 136
    }
  ]
}

Notes:

• For DrillMeister head diameter, use series=DrillMeister and DC.
• Do not search description=head; the word "head" is not specific enough.
• ITEMTYPE=I can appear because drill heads are cataloged as replaceable cutting items.

Example 4: External Turning Holders With Shank Height At Least 20 mm

Request:

Code
{
  "search_mode": "dimension",
  "main_application": "ExternalTurning",
  "filters": [
    {
      "field": "H",
      "op": "gte",
      "value": 20
    }
  ],
  "limit": 3,
  "include_definitions": true
}

Response excerpt:

Code
{
  "searchMode": "dimension",
  "resultCount": 743,
  "returnedCount": 3,
  "hasMore": true,
  "nextOffset": 3,
  "columnDefinitions": {
    "H": "Shank Height [mm]",
    "B": "Shank Width [mm]",
    "LF": "Overall Length [mm]",
    "LH": "Functional Part Length [mm]",
    "WF": "Functional Part Width [mm]",
    "KAPR": "Approach Angle [deg]",
    "MIID": "Compatible Insert Model",
    "Torque": "Tightening Torque [N*m]"
  },
  "items": [
    {
      "ITEMNUM": "3314761",
      "DESCRIPTION": "ADJNL2525X-15-CHP-MC",
      "MainApplication": "ExternalTurning",
      "SubApplication": "For 55deg Rhombic insert",
      "product_name": "TungTurnJet",
      "series": "ADJNR/L-X-CHP-MC",
      "ITEMTYPE": "T",
      "H": 25,
      "B": 25,
      "LF": 125,
      "LH": 40,
      "WF": 32,
      "HAND": "L",
      "KAPR": 93,
      "MIID": "DNMG150608",
      "Torque": 4,
      "compatible_insert": "DNMG150608"
    },
    {
      "ITEMNUM": "3336572",
      "DESCRIPTION": "ACLNL2525X-12-CHP-MC",
      "MainApplication": "ExternalTurning",
      "SubApplication": "For 80deg Rhombic insert",
      "product_name": "TungTurnJet",
      "series": "ACLNR/L-X-CHP-MC",
      "ITEMTYPE": "T",
      "H": 25,
      "B": 25,
      "LF": 120,
      "LH": 35,
      "WF": 32,
      "HAND": "L",
      "KAPR": 95,
      "MIID": "CNMG120408",
      "Torque": 4,
      "compatible_insert": "CNMG120408"
    }
  ]
}

Notes:

• For external turning holder size, H and B are usually important.
• MIID and compatible_insert show the insert model accepted by the holder.
• Use HAND to distinguish right-hand and left-hand tools.

Example 5: CNMG Inserts With 0.4 mm Corner Radius

When searching for insert items themselves, use description plus ITEMTYPE=I.

Request:

Code
{
  "search_mode": "description",
  "description": "CNMG",
  "filters": [
    {
      "field": "ITEMTYPE",
      "op": "eq",
      "value": "I"
    },
    {
      "field": "RE",
      "op": "eq",
      "value": 0.4
    }
  ],
  "limit": 3,
  "include_definitions": true
}

Response excerpt:

Code
{
  "searchMode": "description",
  "resultCount": 241,
  "returnedCount": 3,
  "hasMore": true,
  "nextOffset": 3,
  "columnDefinitions": {
    "RE": "Corner Radius [mm]",
    "IC": "Inscribed Circle Diameter [mm]",
    "S": "Insert Thickness [mm]",
    "LE": "Cutting Edge Length [mm]",
    "Grade": "Grade",
    "ITEMTYPE": "Item Type"
  },
  "items": [
    {
      "ITEMNUM": "6707274",
      "DESCRIPTION": "CNMG120404-TQ",
      "MainApplication": "ExternalTurning",
      "SubApplication": "Inserts",
      "product_name": "TungTurn",
      "series": "CNMG-TQ",
      "ITEMTYPE": "I",
      "RE": 0.4,
      "IC": 12.7,
      "S": 4.76,
      "LE": 12.08357,
      "Grade": "GT9530",
      "ap(min)": 0.5,
      "ap(max)": 2,
      "ft(min)": 0.15,
      "ft(max)": 0.3
    },
    {
      "ITEMNUM": "6707284",
      "DESCRIPTION": "CNMG120404-TQ",
      "MainApplication": "ExternalTurning",
      "SubApplication": "Inserts",
      "product_name": "TungTurn",
      "series": "CNMG-TQ",
      "ITEMTYPE": "I",
      "RE": 0.4,
      "IC": 12.7,
      "S": 4.76,
      "Grade": "NS9530"
    }
  ]
}

Do not use compatible_insert when searching for the insert item itself.

Example 6: External Turning Holders Compatible With CNMG120408

When searching for tools or holders that accept an insert, use compatible_insert.

Request:

Code
{
  "search_mode": "compatible_insert",
  "main_application": "ExternalTurning",
  "compatible_insert": "CNMG120408",
  "limit": 3,
  "include_definitions": true
}

Response excerpt:

Code
{
  "searchMode": "compatible_insert",
  "resultCount": 108,
  "returnedCount": 3,
  "hasMore": true,
  "nextOffset": 3,
  "items": [
    {
      "ITEMNUM": "3336572",
      "DESCRIPTION": "ACLNL2525X-12-CHP-MC",
      "MainApplication": "ExternalTurning",
      "SubApplication": "For 80deg Rhombic insert",
      "product_name": "TungTurnJet",
      "series": "ACLNR/L-X-CHP-MC",
      "ITEMTYPE": "T",
      "H": 25,
      "B": 25,
      "LF": 120,
      "HAND": "L",
      "KAPR": 95,
      "MIID": "CNMG120408",
      "compatible_insert": "CNMG120408"
    },
    {
      "ITEMNUM": "3346687",
      "DESCRIPTION": "ACLNR2525X-12-CHP-MC",
      "MainApplication": "ExternalTurning",
      "SubApplication": "For 80deg Rhombic insert",
      "product_name": "TungTurnJet",
      "series": "ACLNR/L-X-CHP-MC",
      "ITEMTYPE": "T",
      "H": 25,
      "B": 25,
      "LF": 120,
      "HAND": "R",
      "KAPR": 95,
      "MIID": "CNMG120408",
      "compatible_insert": "CNMG120408"
    }
  ]
}

Do not add ITEMTYPE=I in this case. ITEMTYPE=I restricts results to insert item rows, not compatible tools.

Example 7: Other Application Search Recipes

These examples show common structured search patterns and the key values to inspect in the response.

Internal Turning Minimum Bore Diameter

Code
{
  "search_mode": "dimension",
  "main_application": "InternalTurning",
  "filters": [
    {
      "field": "DMIN",
      "op": "lte",
      "value": 16
    }
  ],
  "limit": 10,
  "include_definitions": true
}

Inspect returned values:

• DMIN: minimum machining or bore diameter
• DCONMS: connection diameter
• LF, LH, LPR: length-related fields
• HAND: hand direction
• compatible_insert: insert model accepted by the tool

Grooving And Parting By Groove Width

Code
{
  "search_mode": "dimension",
  "main_application": "Grooving_and_Parting",
  "sub_application": "External grooving",
  "filters": [
    {
      "field": "CW",
      "op": "eq",
      "value": 3
    }
  ],
  "limit": 10,
  "include_definitions": true
}

Inspect returned values:

• CW: cutting or groove width
• CDX: maximum cutting depth
• HAND: hand direction
• Grade, RE: useful for insert rows
• compatible_insert: useful for tool rows

Threading By Pitch

Code
{
  "search_mode": "dimension",
  "main_application": "Threading",
  "filters": [
    {
      "field": "TP",
      "op": "eq",
      "value": 1.5
    }
  ],
  "limit": 10,
  "include_definitions": true
}

Inspect returned values:

• TP: thread pitch
• TPN, TPX: pitch range
• IC, RE, Grade: common threading insert fields
• DC, NOF, DCONMS: common thread milling or tap fields

Boring By Diameter Range

Code
{
  "search_mode": "dimension",
  "main_application": "Boring",
  "filters": [
    {
      "field": "DCN",
      "op": "lte",
      "value": 20
    },
    {
      "field": "DCX",
      "op": "gte",
      "value": 20
    }
  ],
  "limit": 10,
  "include_definitions": true
}

Inspect returned values:

• DCN: minimum boring diameter
• DCX: maximum boring diameter
• DCONMS: connection diameter
• LF, LPR, OAL: length-related fields

Tooling System By Connection Diameter

Code
{
  "search_mode": "dimension",
  "main_application": "ToolingSystem",
  "filters": [
    {
      "field": "DCONMS",
      "op": "eq",
      "value": 32
    }
  ],
  "limit": 10,
  "include_definitions": true
}

Inspect returned values:

• DCONMS: machine-side or primary connection diameter
• DCONWS, DCSFMS: other connection diameters when present
• SS: shank size
• LF, OAL, LPR: length-related fields
• CSP, CSI, KWW: interface-specific values

Example 8: Discover Filterable Columns

Use metadata when you are unsure which field to use for a dimension or attribute.

Code
GET /v1/catalog/metadata?metadata_type=filterable_columns&main_application=Milling&sub_application=Slot%20Milling

You can also call the MCP tool:

Code
{
  "queryParams": {
    "metadata_type": "filterable_columns",
    "main_application": "Milling",
    "sub_application": "Slot Milling"
  }
}

Use the returned columns to build a follow-up search_catalog request.

How To Narrow Broad Results

If resultCount is much larger than returnedCount, do not simply increase limit. Prefer narrowing the query.

Use:

• nextSuggestedFilters to choose a narrower follow-up filter
• hasMore and nextOffset to request the next page
• columnDefinitions to explain dimensions and units
• main_application, sub_application, series, compatible_insert, and filters to reduce ambiguity

Example follow-up pagination request:

Code
{
  "search_mode": "dimension",
  "main_application": "Milling",
  "filters": [
    {
      "field": "cutter_diameter",
      "op": "eq",
      "value": 1
    }
  ],
  "limit": 10,
  "offset": 10,
  "include_definitions": true
}

Common Mistakes

Mistake	Better approach
Passing a full natural-language request into q	Use smart_search_catalog, or convert the request into structured fields.
Searching description=DrillMeister for drill heads	Use series=DrillMeister and a DC filter.
Using compatible_insert to search insert items	Use description=<insert prefix> plus ITEMTYPE=I.
Adding ITEMTYPE=I when looking for compatible holders	Use compatible_insert=<insert model> and omit ITEMTYPE=I.
Using cutter_diameter for slot width	Use CW for slot or cutter width.
Ignoring columnDefinitions	Use it to display units and explain fields such as DC, DCX, H, B, LF, and RE.