---
title: "Search the materials database with a fuzzy/colloquial query and return ranked candidate materials, without forcing a single guess."
method: POST
path: "/tools/search_materials"
---

# Search the materials database with a fuzzy/colloquial query and return ranked candidate materials, without forcing a single guess.

`POST /tools/search_materials`

## Request

- Base URL: `https://api.mechanofab.com/v1`
- URL: `https://api.mechanofab.com/v1/tools/search_materials`
- Auth: HTTP bearer

Use to resolve a user's material description (industry grade name like 'PA12', a colloquial term like 'nylon', a Chinese term, or a vague description) into concrete materials.csv entries. Unlike compare_materials/find_equivalent_materials (which need an exact known ID), this tool accepts messy input and returns a ranked list of candidates — use it as the first step when you don't already know the exact material_id. If multiple candidates come back, ask the user to pick one rather than guessing. Optionally narrow by category_hint (Plastic/Metal/Rubber/Resin/Powder Metals/Powder Polymers) or process_filter (e.g. 'Selective Laser Sintering', 'SLS', 'Injection Molding') when the context already implies a manufacturing process.

## Request body

- object
  - `query` string, required: User's material description, ideally already normalized to English (e.g. 'PA12', 'nylon', '316 stainless steel').
  - `category_hint` 'Plastic' | 'Metal' | 'Rubber' | 'Resin' | 'Powder Metals' | 'Powder Polymers': Optional coarse category filter matched against Material_Category(L1)/Material_Sub-Category(L2).
  - `process_filter` string: Optional manufacturing process substring filter matched against Compatible_Processes, e.g. 'SLS', 'Selective Laser Sintering', 'Injection Molding'.
  - `limit` number: Max candidates to return. Defaults to 10.

## Response `200`

Tool result

- object
  - `candidates` unknown[], required
    - unknown
  - `count` number, required
  - `source_tag` string, required

## Other responses

- `400`: Invalid request/input.
- `401`: Missing/invalid credentials.
- `402`: Insufficient credits.
- `403`: Scope/tool forbidden.
- `404`: Unknown resource.
- `409`: Idempotency conflict.
- `429`: Rate limited.
- `503`: Control plane / runtime unavailable.

---

[API](https://skmtc.dev/mechanofab/apis/mechanofab-api.md) · [All operations](https://skmtc.dev/mechanofab/apis/mechanofab-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mechanofab/apis/mechanofab-api/revisions/5945a6fad621?raw)