Part Catalog search
Parametric catalog search
Search the catalog by a free-text query and/or parametric filters. Results are
PartSummary records — the overview data (MPN, manufacturer,
description, image, status), ranked best-first. Search is free; fetch the full record (specs,
pricing, availability) with GET /v1/parts/{manufacturer}/{mpn}
when you need it — see Usage billing.
parts:read
Search
https://api.zenode.ai/v1/parts/searchFreeRequest
1{2 "query": "low-noise jfet op-amp",3 "filters": {4 "status": [5 "active"6 ],7 "price": {8 "max": 1,9 "currency": "USD",10 "in_stock": true11 },12 "specs": {13 "Current - Input Bias": {14 "gte": 1e-12,15 "lle": 4e-8,16 "unit": "A"17 }18 }19 },20 "sort": {21 "by": "price",22 "quantity": 10023 },24 "limit": 1025}| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Optional | Free-text / keyword search. Omit to browse by filters alone |
filters | PartFilters | Optional | All filter dimensions — see PartFilters reference |
sort | object | Optional | { by: relevance | price | <numeric spec name>, order: asc | desc, quantity: int }; default relevance. order defaults to asc; quantity (price only) defaults to filters.price.min_quantity, else 1 — see Sorting below |
limit | int | Optional | Results per page, default 10, max 100. Out-of-range values are clamped, not rejected |
offset | int | Optional | Zero-based offset for paging, default 0. Reaches the first 200 matches; pass the response's next_offset for the next page. Clamped into 0–200, not rejected |
Response
1{2 "results": [ /* PartSummary, … */ ],3 "total": 1284,4 "total_is_capped": false,5 "offset": 0,6 "has_more": true,7 "next_offset": 10,8 "request_id": "req_9c12..."9}| Parameter | Type | Required | Description |
|---|---|---|---|
results | PartSummary[] | Required | Ranked best-first (by relevance, or by sort/filter order). Summary data only — fetch the full record per part |
total | int | null | Optional | Parts matching the query + filters. Exact for a filter-only search and for a price / spec sort; for a text query sorted by relevance it saturates at 200 (see total_is_capped). Null when unknown |
total_is_capped | bool | Required | True when total hit the 200-match cap of a relevance-ranked text query: more parts match, and the exact count isn't available. Add a filter (or use the facets endpoint) for an exact count |
offset | int | Required | Zero-based offset of this page |
has_more | bool | Required | True when another page is reachable — offset + page < min(total, 200) |
next_offset | int | null | Optional | The offset for the next page; null when there is none |
request_id | string | Required | For support / tracing |
Paging. Pass offset to page through results — has_more and next_offset say whether another
page exists and where it starts. Paging reaches the first 200 matches of a search; an offset
of 200 or more returns results: []. When total is larger, narrow the search with filters (the
facets endpoint shows what to filter on) rather than paging further.
Ranking. A query sorted by relevance always gets a deeper ranking pass that re-scores the top candidates to surface better-matching parts, which helps most on natural-language queries.
Sorting
sort.by is relevance (the default), price, or a numeric spec name exactly as the
facets list it (specs[].name, case-sensitive — e.g. "Current - Quiescent (Iq)").
- Every match is sorted. A
priceor spec sort orders every part thequeryandfiltersmatch, not just the most relevant ones. With aquery, a part is in scope when it matches the text well enough; without one, the whole filtered set is sorted.totalis then the exact number of parts sorted. - Order.
orderisasc(default) ordesc. Parts without the value (no price, or the spec not recorded) always come last. - Price at a quantity. A part has a price per distributor offer and quantity break. The price a
sort compares is the cheapest unit price, across distributors, for buying
quantitypieces: each offer quotes the price of its largest break at or belowquantity(breaks are "from N pieces up"), and an offer whose first break is abovequantitydoesn't count.quantitydefaults tofilters.price.min_quantity, else 1. Price filters (distributors,in_stock,min/max) also decide which offers count. - No deeper ranking pass runs on a
priceor spec sort — the sort decides the order. - Errors. An unknown or non-numeric spec name is a 400Bad Request
invalid_requestonsort.by; so is an unknownsortkey or aquantitybelow 1.
1{2 "query": "3.3V 500mA LDO",3 "sort": {4 "by": "price",5 "quantity": 10006 }7}1{2 "query": "LDO",3 "sort": {4 "by": "Current - Quiescent (Iq)",5 "order": "asc"6 }7}Query & filter handling
- Send at least one input.
queryandfiltersare each optional on their own, but a request with neither is a 400Bad Requestinvalid_request— there is no "return the whole catalog" mode. - Filter-only search. Omit
queryto browse byfiltersalone; results are ordered bysort(defaultrelevance, which with no query falls back to a stable catalog order). Parametric filters (specs,price) work with or without acategoriesfilter — a category just narrows the set and sharpens spec facets. - No matches returns
results: [](not an error). A broad query simply returns the top-ranked, bounded set — tighten withfiltersto focus it.
Search is free — results are PartSummary overview records,
not the billed full record. To get specs, pricing, and availability for a result, fetch it with
GET /v1/parts/{manufacturer}/{mpn} (1 part-record unit). See
Usage billing.
Scope to an approved-parts list. Set filters.list_filter to a lst_… id to search only
within one of your AVLs or a Zenode-curated list (an array unions several). List your ids with
GET /v1/lists.
Try it
Fill in a query and filters — search for categories and manufacturers to add them by slug — and the request JSON is built for you below (copy it, or send it live).
Search defaults to active when none are selected.
Keyed by spec display name (read live from the facets endpoint). Give values for an enum match, or a min/max for a numeric range.
1{2 "query": "low-noise jfet op-amp",3 "limit": 104}curl -X POST "https://api.zenode.ai/v1/parts/search" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "query": "low-noise jfet op-amp", "limit": 10}'Facets
Aggregate the matching set into available filter values and counts — for building checkbox counts, range sliders, and histograms. Free — returns filter metadata, not part records.
https://api.zenode.ai/v1/parts/search/facetsFreeSend the same query and filters as a search (no sort / limit):
1{2 "query": "op-amp",3 "filters": {4 "categories": [5 "amplifiers/operational-amplifiers"6 ]7 }8}Response
1{2 "total": 1284,3 "manufacturers": [4 {5 "slug": "texas-instruments",6 "name": "Texas Instruments",7 "count": 3128 }9 ],10 "categories": [11 {12 "slug": "amplifiers/operational-amplifiers",13 "name": "Operational Amplifiers",14 "count": 128415 }16 ],17 "statuses": [18 {19 "status": "active",20 "count": 110021 },22 {23 "status": "nrnd",24 "count": 12025 }26 ],27 "specs": [28 {29 "name": "Supply Voltage",30 "type": "numeric",31 "unit": "V",32 "range": {33 "min": 1.8,34 "max": 36,35 "histogram": {36 "buckets": [37 1.8,38 5,39 12,40 3641 ],42 "counts": [43 420,44 510,45 35446 ],47 "labels": [48 "1.8–5 V",49 "5–12 V",50 "12–36 V"51 ]52 }53 },54 "options": null55 },56 {57 "name": "Mounting Type",58 "type": "enum",59 "unit": null,60 "range": null,61 "options": [62 {63 "value": "Surface Mount",64 "count": 98065 },66 {67 "value": "Through Hole",68 "count": 30469 }70 ]71 }72 ],73 "request_id": "req_44ab..."74}| Parameter | Type | Required | Description |
|---|---|---|---|
total | int | Required | Parts matching the query + filters |
manufacturers | {slug,name,count}[] | Required | Manufacturer facet counts |
categories | {slug,name,count}[] | Required | Category facet counts |
statuses | {status,count}[] | Required | Lifecycle-status facet counts |
specs | SpecFacet[] | Required | Per-spec facet detail |
A SpecFacet is { name, type, unit, range, options } — type is numeric or enum; numeric
specs carry a range with a histogram, enum specs carry options with per-value counts. The name
is the key to use in filters.specs.
Try it
Search defaults to active when none are selected.
Keyed by spec display name (read live from the facets endpoint). Give values for an enum match, or a min/max for a numeric range.
1{2 "query": "op-amp"3}curl -X POST "https://api.zenode.ai/v1/parts/search/facets" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Content-Type: application/json" \ -d '{ "query": "op-amp"}'Next
- PartFilters — the full filter shape
- Approved-parts lists — scope a search with
filters.list_filter - Part detail — fetch one part by slug
- AI discovery — let the AI choose for you