Part matching

Turn a partial or full part number into a canonical Zenode part. This is the BOM / part-identification workhorse.

Match a part

Request

1{
2  "query": "TL072",
3  "manufacturer": "TI",
4  "description": "dual jfet op-amp",
5  "limit": 10
6}

Response

1{
2  "query": "TL072",
3  "ambiguous": true,
4  "results": [
5    {
6      "part": {
7        "mpn": "TL072CP",
8        "mpn_slug": "TL072CP",
9        "manufacturer": {
10          "slug": "texas-instruments-inc",
11          "name": "Texas Instruments"
12        },
13        "description": "...",
14        "image": "https://cdn.zenode.ai/...",
15        "status": "active",
16        "url": "https://zenode.ai/part/texas-instruments-inc/TL072CP"
17      },
18      "confidence": 88,
19      "exact": false
20    }
21  ],
22  "request_id": "req_8f3a..."
23}

Each MatchResult is { part, confidence, exact }:

Try it

1{
2  "query": "TL072",
3  "limit": 10
4}

curl -X POST "https://ix.zenode.ai/zenode-api/v1/parts/match" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "TL072",
  "limit": 10
}'

Confidence, exact, and ambiguous

confidence (0–100) is a calibrated probability that the result is the part you meant — the candidate scores normalized into a distribution (a softmax with a built-in "no match" alternative). Because that alternative holds back some probability, the confidences in a response need not sum to 100: the remainder is the chance that none of the results is right. Two close matches split the mass (each lands well under 100 → ambiguous); a clean exact match takes almost all of it. exact and ambiguous remain the hard signals to branch on:

• Unambiguous exact match — ambiguous is false and exactly one result has exact: true, ranked first with high confidence. Safe to auto-accept results[0].
• Ambiguous — the input matches a family or several plausible parts. ambiguous is true, every result has exact: false, and confidence is spread across them. Surface a chooser, or tighten with manufacturer / description.
• No match — results is empty and ambiguous is false.

confidence is a within-response probability; don't compare a confidence value across different queries as if it were an absolute score.

Input handling

• Empty query — a missing or empty query is a 400Bad Request invalid_request for the single endpoint; in a batch it's a per-line error (the rest of the batch still runs).
• Gibberish / no plausible part — a well-formed but unmatchable query returns results: [] with ambiguous: false (not an error).
• Very broad query — a query that matches many parts returns the top-ranked, bounded set (limit, max 50) with ambiguous: true; narrow it with manufacturer / description.

Match a BOM (batch)

Resolve many lines in one request. Each line is matched independently, so one bad line never fails the batch.

Request

1{
2  "queries": [
3    {
4      "id": "line-1",
5      "query": "TL072CP",
6      "manufacturer": "TI"
7    },
8    {
9      "id": "line-2",
10      "query": "GRM188R71C104KA01",
11      "description": "0603 100nF X7R"
12    }
13  ],
14  "limit": 5
15}

Each BatchQuery has the single-match fields plus an optional client-supplied id, echoed back so you can re-join results to your own rows. Over 250 lines returns a top-level 400Bad Request.

Response

One entry per input line, in the same order — each with the same ambiguous / results shape, or a per-line error:

1{
2"results": [
3  { "id": "line-1", "query": "TL072CP", "ambiguous": false, "results": [ /* MatchResult */ ], "error": null },
4  { "id": "line-3", "query": "", "ambiguous": false, "results": [], "error": { "type": "invalid_request", "message": "Field 'query' is required.", "param": "query" } }
5],
6"request_id": "req_5c40..."
7}

A 200OK is returned even when individual lines fail — inspect each line's error. See Errors.

Try it

1{
2  "limit": 5,
3  "queries": [
4    {
5      "id": "line-1",
6      "query": "TL072CP",
7      "manufacturer": "TI"
8    },
9    {
10      "id": "line-2",
11      "query": "GRM188R71C104KA01",
12      "description": "0603 100nF X7R"
13    }
14  ]
15}

curl -X POST "https://ix.zenode.ai/zenode-api/v1/parts/match/batch" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "limit": 5,
  "queries": [
    {
      "id": "line-1",
      "query": "TL072CP",
      "manufacturer": "TI"
    },
    {
      "id": "line-2",
      "query": "GRM188R71C104KA01",
      "description": "0603 100nF X7R"
    }
  ]
}'

Next

• Manufacturers — resolve a manufacturer name to a slug
• Part Catalog search — discovery by query + filters