> ## Documentation Index
> Fetch the complete documentation index at: https://docs.partfinder.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> The PartFinder API is served at https://api.partfinder.dev. Authenticate with `Authorization: Bearer $PARTFINDER_API_KEY`; create an account at https://console.partfinder.dev/sign-up and pick pay as you go or a monthly or yearly plan (see https://partfinder.dev/pricing), then create a key. Pay as you go starts with 100 free credits, once per person and per company.
> Install the PartFinder agent skill with `npx skills add https://docs.partfinder.dev` (skill file: https://docs.partfinder.dev/skill.md).
> The OpenAPI document at https://api.partfinder.dev/v1/openapi.json is the source of truth for request and response schemas.
> What each call costs and current plans: https://api.partfinder.dev/llms.txt.

# Compare parts

> Put parts side by side on the specifications that matter for that kind of part, read from each datasheet, with a verdict per specification and current stock.

A comparison puts parts side by side on the specifications that matter for that kind of part, with the
values read from each part's datasheet. One part is the reference. Every other part gets one verdict per
specification against it, a count of the specifications that are the same or covered, and what
distributors hold now.

Use it to check a substitute before you qualify it, or to choose between parts you already have in mind.
To find candidates first, use [Find alternate parts](https://docs.partfinder.dev/alternates.md) or [Search for parts](https://docs.partfinder.dev/search.md).

## Start a comparison

Send your own list in `parts`: 2 to 6 parts, compared as given. The first is the reference the others are
compared with.

```python Python theme={null}
import os
import uuid

import requests

response = requests.post(
    "https://api.partfinder.dev/v1/compare",
    headers={
        "Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"parts": [{"mpn": "TPS54331DR"}, {"mpn": "TPS5430DDAR"}]},
)
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.partfinder.dev/v1/compare", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ parts: [{ mpn: "TPS54331DR" }, { mpn: "TPS5430DDAR" }] }),
});
console.log(await response.json());
```

```bash cURL theme={null}
curl https://api.partfinder.dev/v1/compare \
  -X POST \
  -H "Authorization: Bearer $PARTFINDER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"parts": [{"mpn": "TPS54331DR"}, {"mpn": "TPS5430DDAR"}]}'
```

Or send one part in `mpn` to compare it with its alternates, the list
[`GET /v1/alternates`](https://docs.partfinder.dev/alternates) returns:

```python Python theme={null}
import os
import uuid

import requests

response = requests.post(
    "https://api.partfinder.dev/v1/compare",
    headers={
        "Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"mpn": "TPS54331DR"},
)
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.partfinder.dev/v1/compare", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({ mpn: "TPS54331DR" }),
});
console.log(await response.json());
```

```bash cURL theme={null}
curl https://api.partfinder.dev/v1/compare \
  -X POST \
  -H "Authorization: Bearer $PARTFINDER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"mpn": "TPS54331DR"}'
```

Send `mpn` or `parts`, not both. `manufacturer` is only needed when several companies make a part with
that number: beside `mpn` in the first shape, inside each part in the second
(`{"mpn": "NE555N", "manufacturer": "STMicroelectronics"}`).

The answer is `202` with the comparison's `id`, a `Location` header pointing at it, and `Retry-After: 10`.

`Idempotency-Key` is optional: send a new value for each comparison, and the same value only when retrying
that same comparison after a timeout. The retry returns the comparison the first call started.

## When a comparison is refused

Every part you send is checked before anything starts. A refusal names the part in its `summary`, and
nothing is started:

* `400 invalid_request`: neither or both of `mpn` and `parts`, `parts` with fewer than 2 or more than 6
  parts, or a `manufacturer` beside `parts` instead of inside each part.
* `404 part_not_found`: no distributor lists a part number you sent exactly, usually a typo or a partial
  number. `did_you_mean` carries listed part numbers that begin with what you sent, when there are any.
* `422 not_a_specific_part`: a part you sent is a question, a category or a generic specification, not one
  part. When it described a class of parts, `did_you_mean` carries real part numbers to retry with.
* `503 verification_unavailable`: we could not confirm a part number is real right now. Retry shortly.

Every code is on the [Errors](https://docs.partfinder.dev/errors.md) page.

## Get the result

Read `GET /v1/compare/{id}` after the 10 seconds in `Retry-After`. While `status` is still `processing`, the answer's
`summary` and `Retry-After` give the wait before the next read, 9 seconds:

```python Python theme={null}
import os

import requests

response = requests.get(
    "https://api.partfinder.dev/v1/compare/f2d22c25-e694-428b-bbb8-3948e60d3c7b",
    headers={"Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}"},
)
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.partfinder.dev/v1/compare/f2d22c25-e694-428b-bbb8-3948e60d3c7b", {
  headers: { Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}` },
});
console.log(await response.json());
```

```bash cURL theme={null}
curl https://api.partfinder.dev/v1/compare/f2d22c25-e694-428b-bbb8-3948e60d3c7b \
  -H "Authorization: Bearer $PARTFINDER_API_KEY"
```

`status` ends as `complete`, with the parts, or `failed`, when the comparison could not be completed:
submit it again. Every poll counts toward your [rate limit](https://docs.partfinder.dev/errors.md#rate-limits). To be told instead of
polling, register a [webhook](https://docs.partfinder.dev/webhooks.md): `compare.completed` names the comparison when it ends.

## What comes back

```json theme={null}
{
  "as_of": "2026-10-12T02:49:29.479Z",
  "summary": "TPS54331DR compared with 1 part. TPS5430DDAR: Same or covers on 1 of 4 specs both datasheets state.",
  "notice": "Informational only. ...",
  "id": "f2d22c25-e694-428b-bbb8-3948e60d3c7b",
  "status": "complete",
  "created_at": "2026-10-12T02:48:51.204Z",
  "completed_at": "2026-10-12T02:49:29.479Z",
  "columns": ["Input Voltage Range", "Output Voltage", "Output Current", "Package Type"],
  "parts": [
    {
      "mpn": "TPS54331DR",
      "manufacturer": "Texas Instruments",
      "reference": true,
      "match": null,
      "lifecycle": "Active",
      "specs": {
        "Input Voltage Range": "3.5 V to 28 V",
        "Output Voltage": "Adjustable down to 0.8 V",
        "Output Current": "3 A continuous",
        "Package Type": "SOIC-8"
      },
      "datasheet_url": "https://www.ti.com/lit/gpn/tps54331",
      "supply": {
        "stock": { "value": 1148628, "unit": "units" },
        "distributor_count": 22,
        "lead_time_median": { "value": 84, "unit": "days" }
      },
      "comparison": null
    },
    {
      "mpn": "TPS5430DDAR",
      "manufacturer": "Texas Instruments",
      "reference": false,
      "match": null,
      "lifecycle": "Active",
      "specs": {
        "Input Voltage Range": "5.5 V to 36 V",
        "Output Voltage": "adjustable down to 1.22 V",
        "Output Current": "3 A continuous",
        "Package Type": "SO PowerPAD DDA 8-pin"
      },
      "datasheet_url": "https://www.ti.com/lit/ds/symlink/tps5430.pdf",
      "supply": {
        "stock": { "value": 1192476, "unit": "units" },
        "distributor_count": 22,
        "lead_time_median": { "value": 140, "unit": "days" }
      },
      "comparison": {
        "verdicts": {
          "Input Voltage Range": "narrower",
          "Output Voltage": "narrower",
          "Output Current": "same",
          "Package Type": "different"
        },
        "stated": 4,
        "same_or_covers": 1,
        "summary": "Same or covers on 1 of 4 specs both datasheets state."
      }
    }
  ]
}
```

* **`summary`** is one sentence you can relay as it is. When no part to compare with was found, it says so
  and `parts` holds the reference alone.
* **`columns`** are the specifications chosen for this kind of part. Every part's `specs` has one entry per
  column: the value its datasheet states, or `null` when it states none. `datasheet_url` is the datasheet
  the values were read from.
* **`parts`** lists the reference first (`reference: true`, `comparison: null`), then each part compared
  with it. For an alternate of the part you sent in `mpn`, `match` is the parts catalogue's classification,
  as on [alternates](https://docs.partfinder.dev/alternates.md); it is `null` for the reference and for your own list.
* **`supply`** is what distributors hold now, in the same shape as [alternates](https://docs.partfinder.dev/alternates.md).
* **`comparison`** holds one verdict per column, `stated` (the specifications both datasheets state),
  `same_or_covers` (how many of those are `same` or `covers`) and a one-sentence `summary`.

## What each verdict means

| Verdict | Meaning |
| - | - |
| `same` | The same value, however written. |
| `covers` | Its range contains the reference's value or range. |
| `narrower` | Its range does not contain the reference's whole range. |
| `higher` / `lower` | A single value above or below; whether that is better depends on the specification. |
| `different` | The two cannot be put on one scale. |
| `not_stated` | One of the datasheets states none. |

> [!WARNING]
>
> A verdict compares what the datasheets state; it is not a qualification. Confirm fit against the
> datasheets before you buy or substitute.

## List and delete

[`GET /v1/compare`](https://docs.partfinder.dev/api-reference/compare/list-your-comparisons) lists your comparisons, newest first, one
page at a time, the same way as [BOMs](https://docs.partfinder.dev/bom-analysis.md).
[`DELETE /v1/compare/{id}`](https://docs.partfinder.dev/api-reference/compare/delete-a-comparison) removes a comparison and its
results. With a key you created for one of your customers
([Serving your own customers](https://docs.partfinder.dev/authentication.md#serving-your-own-customers)), a customer sees only its own
comparisons.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.