Search documentation

Search across all documentation pages

Get API Key
Endpoints

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
POSThttps://api.zenode.ai/v1/parts/searchFree

Request

JSON
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": true
11 },
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": 100
23 },
24 "limit": 10
25}
ParameterTypeRequiredDescription
query
stringOptionalFree-text / keyword search. Omit to browse by filters alone
filters
PartFiltersOptionalAll filter dimensions — see PartFilters reference
sort
objectOptional{ 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
intOptionalResults per page, default 10, max 100. Out-of-range values are clamped, not rejected
offset
intOptionalZero-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

JSON
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}
ParameterTypeRequiredDescription
results
PartSummary[]RequiredRanked best-first (by relevance, or by sort/filter order). Summary data only — fetch the full record per part
total
int | nullOptionalParts 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
boolRequiredTrue 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
intRequiredZero-based offset of this page
has_more
boolRequiredTrue when another page is reachable — offset + page < min(total, 200)
next_offset
int | nullOptionalThe offset for the next page; null when there is none
request_id
stringRequiredFor 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 price or spec sort orders every part the query and filters match, not just the most relevant ones. With a query, a part is in scope when it matches the text well enough; without one, the whole filtered set is sorted. total is then the exact number of parts sorted.
  • Order. order is asc (default) or desc. 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 quantity pieces: each offer quotes the price of its largest break at or below quantity (breaks are "from N pieces up"), and an offer whose first break is above quantity doesn't count. quantity defaults to filters.price.min_quantity, else 1. Price filters (distributors, in_stock, min / max) also decide which offers count.
  • No deeper ranking pass runs on a price or spec sort — the sort decides the order.
  • Errors. An unknown or non-numeric spec name is a 400Bad Request invalid_request on sort.by; so is an unknown sort key or a quantity below 1.
JSON
1{
2 "query": "3.3V 500mA LDO",
3 "sort": {
4 "by": "price",
5 "quantity": 1000
6 }
7}
JSON
1{
2 "query": "LDO",
3 "sort": {
4 "by": "Current - Quiescent (Iq)",
5 "order": "asc"
6 }
7}

Query & filter handling

  • Send at least one input. query and filters are each optional on their own, but a request with neither is a 400Bad Request invalid_request — there is no "return the whole catalog" mode.
  • Filter-only search. Omit query to browse by filters alone; results are ordered by sort (default relevance, which with no query falls back to a stable catalog order). Parametric filters (specs, price) work with or without a categories filter — 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 with filters to 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).

Try itPOST
Query
Categories
Exclude categories
Manufacturers
Status

Search defaults to active when none are selected.

Price
Spec filters

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.

Request body
JSON
1{
2 "query": "low-noise jfet op-amp",
3 "limit": 10
4}
Request
cURL
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.

POSThttps://api.zenode.ai/v1/parts/search/facetsFree

Send the same query and filters as a search (no sort / limit):

JSON
1{
2 "query": "op-amp",
3 "filters": {
4 "categories": [
5 "amplifiers/operational-amplifiers"
6 ]
7 }
8}

Response

JSON
1{
2 "total": 1284,
3 "manufacturers": [
4 {
5 "slug": "texas-instruments",
6 "name": "Texas Instruments",
7 "count": 312
8 }
9 ],
10 "categories": [
11 {
12 "slug": "amplifiers/operational-amplifiers",
13 "name": "Operational Amplifiers",
14 "count": 1284
15 }
16 ],
17 "statuses": [
18 {
19 "status": "active",
20 "count": 1100
21 },
22 {
23 "status": "nrnd",
24 "count": 120
25 }
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 36
41 ],
42 "counts": [
43 420,
44 510,
45 354
46 ],
47 "labels": [
48 "1.8–5 V",
49 "5–12 V",
50 "12–36 V"
51 ]
52 }
53 },
54 "options": null
55 },
56 {
57 "name": "Mounting Type",
58 "type": "enum",
59 "unit": null,
60 "range": null,
61 "options": [
62 {
63 "value": "Surface Mount",
64 "count": 980
65 },
66 {
67 "value": "Through Hole",
68 "count": 304
69 }
70 ]
71 }
72 ],
73 "request_id": "req_44ab..."
74}
ParameterTypeRequiredDescription
total
intRequiredParts matching the query + filters
manufacturers
{slug,name,count}[]RequiredManufacturer facet counts
categories
{slug,name,count}[]RequiredCategory facet counts
statuses
{status,count}[]RequiredLifecycle-status facet counts
specs
SpecFacet[]RequiredPer-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

Try itPOST
Query
Categories
Exclude categories
Manufacturers
Status

Search defaults to active when none are selected.

Price
Spec filters

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.

Request body
JSON
1{
2 "query": "op-amp"
3}
Request
cURL
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