> ## 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.

# Search for parts

> Search by part number or by description and get the part and comparable parts, with their datasheets, key specifications and stock.

One search returns the part you named, or the parts that match your description, and comparable parts
from the same or other makers. Each part comes with its product page, its datasheet, the specifications that matter
for that kind of part, and what distributors hold now.

Use it when you know roughly what you need but not the exact part, or to compare a part with its
neighbours. To research one known part in depth, use [Research a part](https://docs.partfinder.dev/part-lookup.md).

## Start a search

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

import requests

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

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

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

`query` is a part number (`TPS54331DR`) or a description (`3A buck converter 28V`, `6205 bearing`).
The answer is `202` with the search's `id`, a `Location` header pointing at it, and `Retry-After: 35`.
A query that is not about a part is refused with `422 not_a_parts_query`, and nothing is started.

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

## Get the result

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

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

import requests

response = requests.get(
    "https://api.partfinder.dev/v1/search/e8413914-cea8-46b0-9c6b-8207a4157fc0",
    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/search/e8413914-cea8-46b0-9c6b-8207a4157fc0", {
  headers: { Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}` },
});
console.log(await response.json());
```

```bash cURL theme={null}
curl https://api.partfinder.dev/v1/search/e8413914-cea8-46b0-9c6b-8207a4157fc0 \
  -H "Authorization: Bearer $PARTFINDER_API_KEY"
```

`status` ends as `complete`, with the rows, or `failed`, when the search 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): `search.completed` names the search when it ends.

## What comes back

```json theme={null}
{
  "as_of": "2026-10-10T13:20:39.606Z",
  "summary": "2 parts found for \"TPS54331DR\": TPS54331DR (Texas Instruments), TPS5430DDAR (Texas Instruments). 2 of them are in stock at a distributor.",
  "notice": "Informational only. ...",
  "id": "e8413914-cea8-46b0-9c6b-8207a4157fc0",
  "status": "complete",
  "query": "TPS54331DR",
  "created_at": "2026-10-10T13:19:57.082Z",
  "completed_at": "2026-10-10T13:20:39.606Z",
  "columns": ["Input Voltage Range", "Output Voltage", "Output Current", "Efficiency"],
  "rows": [
    {
      "name": "TPS54331DR",
      "manufacturer": "Texas Instruments",
      "product_url": "https://www.ti.com/product/TPS54331/part-details/TPS54331DR",
      "datasheet_url": "https://www.ti.com/lit/gpn/tps54331",
      "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",
        "Efficiency": null
      },
      "supply": {
        "stock": { "value": 1148628, "unit": "units" },
        "distributor_count": 22,
        "lead_time_median": { "value": 84, "unit": "days" }
      }
    },
    {
      "name": "TPS5430DDAR",
      "manufacturer": "Texas Instruments",
      "product_url": "https://www.ti.com/product/TPS5430/part-details/TPS5430DDAR",
      "datasheet_url": "https://www.ti.com/lit/ds/symlink/tps5430.pdf",
      "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",
        "Efficiency": "up to 95 %"
      },
      "supply": {
        "stock": { "value": 1192476, "unit": "units" },
        "distributor_count": 22,
        "lead_time_median": { "value": 140, "unit": "days" }
      }
    }
  ],
  "insights": {
    "key_specs": ["Input Voltage Range", "Output Voltage", "Output Current", "Efficiency"],
    "applications": [
      "Portable electronics requiring 3 A continuous output current",
      "Systems operating with input voltages ranging from 3.5 V to 36 V"
    ]
  }
}
```

* **`summary`** is one sentence you can relay as it is.
* **`columns`** are the specifications chosen for what you searched. Every row's `specs` has one entry
  per column: the value the datasheet states, or `null` when it states none.
* **`rows`** are the parts found. For a part-number search the part you named comes first. An empty
  list means nothing matched; that is an answer, not an error.
* **`supply`** is what distributors hold now, in the same shape as [alternates](https://docs.partfinder.dev/alternates.md);
  `distributor_count` counts distributors holding stock. A figure we could not read is `null` with a
  `reason`, never a zero.
* **`insights`** lists the specifications to compare across the parts and where parts like these are used.

> [!WARNING]
>
> A row is a candidate, not a qualification. Confirm fit against the datasheets before you buy or
> substitute.

## List and delete

[`GET /v1/search`](https://docs.partfinder.dev/api-reference/search/list-your-searches) lists your searches, newest first, one page
at a time, the same way as [BOMs](https://docs.partfinder.dev/bom-analysis.md). [`DELETE /v1/search/{id}`](https://docs.partfinder.dev/api-reference/search/delete-a-search)
removes a search 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
searches.


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