Search documentation

Search across all documentation pages

Get API Key
Endpoints

AI alternates

AI alternative-part search and comparison

Find parts that can replace a given part — for an obsolete or out-of-stock component, a second source, a cheaper option, or an automotive grade — and get the best of them compared side by side with the original. It's the same search behind the Alternates view in the Zenode web app:

  1. The AI reads the original part's datasheet and derives what a replacement must match, plus your own requirements.
  2. Candidates are gathered from the catalog (cross-references, family and series members, parametric matches, AI search) and screened against their datasheets.
  3. A shortlist of finalists gets a full comparison — function, specs, pinout, package and footprint, price, availability, lifecycle, and each of your requirements — ending in a verdict (drop_in, near_match, needs_review, or not_recommended).
ai:run

A search takes several minutes, so it's asynchronous: the endpoint returns a job you poll or stream for progress and the result.

POSThttps://api.zenode.ai/v1/parts/{manufacturer}/{mpn}/alternatesAI tokens

202Accepted Job (type: alternates)

The part being replaced is the (manufacturer slug, mpn_slug) path pair, as in part detail. 404Not Found not_found if the pair — or a seed candidate — matches no part.

Request

Every field is optional; an empty body (or none) searches with the defaults.

JSON
1{
2 "requirements": "Must accept 6 V input. Must stay in SOT-23-5. Tell me whether it is AEC-Q100.",
3 "seed_candidates": [
4 {
5 "manufacturer": "texas-instruments",
6 "mpn": "TPS62841DLCR"
7 }
8 ],
9 "list_filter": "lst_9f2c...",
10 "max_evaluated": 3
11}
ParameterTypeRequiredDescription
requirements
stringOptionalWhat the replacement must satisfy, in plain language — every sentence becomes a requirement. Say how strict each is ('must be AEC-Q100' vs 'tell me whether it is AEC-Q100') and what may relax ('3 A is enough'). Empty: replace the part, nothing more
seed_candidates
{ manufacturer, mpn }[]OptionalUp to 10 parts you already have in mind (manufacturer slug + mpn_slug or raw MPN); they always join the candidates and get screened
list_filter
string | string[]OptionalKeep candidates inside your approved-parts list(s): one lst_… list_id, or an array (union). See Approved-parts lists
max_evaluated
intOptionalHow many finalists get the full side-by-side comparison, 1–5 (default 3). More takes longer and costs more

Write requirements the way you'd brief an engineer: state only what matters for your design. The AI already compares everything it can read from both datasheets, so restating the original part's features narrows the search without adding anything.

400Bad Request invalid_request for a max_evaluated outside 1–5 or more than 10 seed candidates (param names the field). A list_filter you can't use reads as 404Not Found not_found, as in catalog search.

An alternates search is billed from your AI allowance as it runs — the screening and comparison work it does for you. The job's usage is null (token counts are not broken out per job); check GET /v1/usage for your balance. A search won't start when your balance can't cover it (402Unknown usage_limit_exceeded, with a reason — for an organization's key, also its limits, such as member_limit; see Usage limits). Polling, streaming, listing, and cancelling jobs is free — see Usage billing.

Result

The job's result is an AlternatesResult (when type is alternates):

JSON
1{
2 "original": {
3 "mpn": "TPS62840DLCR",
4 "mpn_slug": "TPS62840DLCR",
5 "manufacturer": {
6 "slug": "texas-instruments",
7 "name": "Texas Instruments"
8 },
9 "status": "active",
10 "url": "https://zenode.ai/parts/..."
11 },
12 "alternates": [
13 {
14 "part": {
15 "mpn": "TPS62841DLCR",
16 "mpn_slug": "TPS62841DLCR",
17 "manufacturer": {
18 "slug": "texas-instruments",
19 "name": "Texas Instruments"
20 },
21 "status": "active",
22 "url": "https://zenode.ai/parts/..."
23 },
24 "stage": "evaluated",
25 "comparison_ready": true,
26 "tier": "drop_in",
27 "replacement_type": "pin_compatible",
28 "confidence": 0.9,
29 "overview": "Pin-for-pin replacement with a wider input range.",
30 "criteria_signals": {
31 "func": "green",
32 "specs": "green",
33 "pinout": "green",
34 "pkg": "green",
35 "price": "yellow",
36 "avail": "green",
37 "life": "green"
38 },
39 "spec_comparisons": [
40 {
41 "spec_name": "Input voltage (max)",
42 "prime_value": "5.5 V",
43 "candidate_value": "6.5 V",
44 "signal": "green"
45 }
46 ],
47 "custom_criteria": [
48 {
49 "name": "AEC-Q100",
50 "signal": "red",
51 "headline": "No",
52 "explanation": "Not listed as automotive qualified.",
53 "page_number": 1
54 }
55 ]
56 },
57 {
58 "part": {
59 "mpn": "MAX38640A",
60 "...": "..."
61 },
62 "stage": "screened",
63 "comparison_ready": false,
64 "screening": {
65 "verdict": "likely_fit",
66 "reasoning": "Same nano-power buck topology and 1.8–5.5 V input."
67 }
68 }
69 ],
70 "candidates_considered": 27,
71 "web_url": "https://zenode.ai/alts/ws-....run_...",
72 "notice": null
73}

alternates lists the fully compared candidates first, best verdict first — a not_recommended candidate was compared and ruled out, so it comes last and shouldn't be offered as an option — then the best of the rest of the candidates, which were only found or screened. Each item is an Alternate; its comparison fields are filled only when comparison_ready is true. Signals read green = matches, yellow = differs but is likely acceptable, red = incompatible.

web_url opens the same comparison in the Zenode web app, for a person to review in full. notice says when a shortlisted candidate couldn't be compared, or — when nothing came back — which single relaxation of your requirements would have found candidates.

Following the job

BASH
1# 1. Start the search
2curl https://api.zenode.ai/v1/parts/texas-instruments/TPS62840DLCR/alternates \\
3 -H "Authorization: Bearer <YOUR API KEY HERE>" -H "Content-Type: application/json" \\
4 -d '{ "requirements": "Must accept 6 V input.", "max_evaluated": 3 }'
5# → 202 { "job_id": "job_8f3a...", "type": "alternates", "status": "queued", ... }
6
7# 2. Poll until completed (or stream — see the Jobs page)
8curl https://api.zenode.ai/v1/jobs/job_8f3a... \\
9 -H "Authorization: Bearer <YOUR API KEY HERE>"

While it runs, the job's progress.message names the step it's on ("Found 27 candidates; screened 10", "Evaluating TPS62841DLCR"); the stream emits one progress event per step. progress.fraction is null for alternates jobs. Cancelling the job stops the search.

Next