Smart catalog search
Recommended first endpoint for natural-language catalog search.
Use this endpoint when the request contains product names, family names, dimensions, insert model prefixes, compatibility questions, or ambiguous catalog wording.
The search agent interprets the user query, chooses the best structured catalog search, applies filters, retries when useful, and returns a concise result based only on catalog data.
Use POST /v1/catalog/search instead when you already know the structured parameters or when you need raw fields such as nextSuggestedFilters, columnDefinitions, responseDefinitions, hasMore, or nextOffset.
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Smart catalog search › Request Body
queryNatural-language catalog search request. The Dify Agent will convert this into the best structured catalog search.
limitMaximum number of matching items to return.
languageconversation_idOptional Dify conversation id for follow-up questions.
Smart catalog search › Responses
Smart catalog search result.
queryOriginal natural-language query.
Agent response or structured workflow output.
Raw Dify workflow outputs.
workflow_run_idtask_idSearch catalog items
Advanced structured catalog search.
Use this endpoint when the search parameters are already clear, or when you need raw search-control fields such as nextSuggestedFilters, columnDefinitions, responseDefinitions, hasMore, nextOffset, returnedCount, and resultCount.
For normal natural-language requests, use POST /v1/catalog/smart-search first.
Common structured parameters:
- search_mode: general, item_number, description, series, application, dimension, compatible_insert, metadata
- main_application: ExternalTurning, InternalTurning, Grooving_and_Parting, Threading, Milling, Holemaking, Boring, ToolingSystem
- filters: array of field/operator/value objects, such as [{"field":"DC","op":"eq","value":10}]
Use nextSuggestedFilters to narrow broad result sets. Use hasMore and nextOffset for pagination.
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Search catalog items › Request Body
search_modeSearch mode hint.
qFree text fallback query. Prefer structured fields such as series, description, main_application, compatible_insert, and filters when possible.
item_numberItem number search term.
descriptionProduct description search term.
seriesSeries or family name.
main_applicationMain application category.
sub_applicationSub application category.
compatible_insertInsert model for reverse lookup from insert to compatible tools. Do not use this when searching for the insert item itself; use description plus ITEMTYPE=I instead.
Structured dimensional or attribute filters. Use an array of objects such as [{"field":"DC","op":"eq","value":10}]. Multiple filters are treated as AND conditions.
response_profileResponse detail level.
include_definitionsInclude top-level and item field definitions.
limitMaximum number of records to return.
offsetZero-based pagination offset.
Search catalog items › Responses
Search result.
Normalized request parameters used for the query.
searchModeSearch mode used by the backend.
resultCountTotal matched item count before pagination.
returnedCountNumber of items returned in this response.
hasMoreWhether additional results are available.
Catalog records or metadata records.
warningsNon-fatal warnings.
nextOffsetOffset for the next page, or null when no next page exists.
Definitions for top-level response fields.
Definitions for fields inside items.
Suggested filters that can be added to a follow-up search when resultCount is much larger than returnedCount.
Get catalog item by item number
Get one or more catalog records that exactly match a Tungaloy item number.
path Parameters
item_numberTungaloy item number.
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Get catalog item by item number › Responses
Item lookup result.
Normalized request parameters used for the query.
searchModeSearch mode used by the backend.
resultCountTotal matched item count before pagination.
returnedCountNumber of items returned in this response.
hasMoreWhether additional results are available.
Catalog records or metadata records.
warningsNon-fatal warnings.
nextOffsetOffset for the next page, or null when no next page exists.
Definitions for top-level response fields.
Definitions for fields inside items.
Suggested filters that can be added to a follow-up search when resultCount is much larger than returnedCount.
Get catalog search metadata
Get search metadata such as main applications, sub applications, series, filterable columns, or column definitions.
query Parameters
metadata_typeMetadata category to return.
main_applicationMain application filter, such as Milling or ExternalTurning.
sub_applicationSub application filter.
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Get catalog search metadata › Responses
Metadata result.
Normalized request parameters used for the query.
searchModeSearch mode used by the backend.
resultCountTotal matched item count before pagination.
returnedCountNumber of items returned in this response.
hasMoreWhether additional results are available.
Catalog records or metadata records.
warningsNon-fatal warnings.
nextOffsetOffset for the next page, or null when no next page exists.
Definitions for top-level response fields.
Definitions for fields inside items.
Suggested filters that can be added to a follow-up search when resultCount is much larger than returnedCount.