> ## 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. # Research a part > Get a composite risk score, current supply, a datasheet, live disruption events and alternates for any manufacturer part number. One call returns everything we know about a part. This page covers what comes back, what to do when a part number is wrong, and how caching affects what you see. ## The call ```python Python theme={null} import os import requests response = requests.get( "https://api.partfinder.dev/v1/parts", headers={"Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}"}, params={"mpn": "STM32F103RBT6", "country": "SG"}, ) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.partfinder.dev/v1/parts?mpn=STM32F103RBT6&country=SG", { headers: { Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}` }, }); console.log(await response.json()); ``` ```bash cURL theme={null} curl "https://api.partfinder.dev/v1/parts?mpn=STM32F103RBT6&country=SG" \ -H "Authorization: Bearer $PARTFINDER_API_KEY" ``` `mpn` is the only required parameter. `country` is optional: see [Buying near you](#buying-near-you). > [!NOTE] > > The first request for a part can take tens of seconds; later ones answer quickly. Set your client > timeout to 90 seconds. ## What comes back ```json theme={null} { "as_of": "2026-09-24T16:01:19.747Z", "summary": "STM32F103RBT6 carries a supply-chain risk score of 32 out of 100 (medium). Flagged: manufacturing geography (medium), lead-time volatility (critical). 350,010 units are held across 28 distributors.", "notes": [], "part": { "mpn": "STM32F103RBT6", "manufacturer": "STMicroelectronics", "category": "32-bit ARM Cortex-M3 MCU", "lifecycle": "Active", "manufacturing_country": "Malaysia", "manufacturing_country_code": "MY" }, "risk": { "composite": { "value": 32, "scale": 100, "direction": "higher_is_worse", "interpretation": "Medium. Combined from manufacturing geography, lead-time volatility, live disruption exposure and how hard this part is to replace." }, "tier": "medium", "drivers": { "geography": { "tier": "medium", "interpretation": "Medium. Reflects the risk profile of Malaysia." }, "lead_time_volatility": { "tier": "critical", "interpretation": "Critical. Lead times for this part are highly unstable." }, "disruption_exposure": { "tier": "low", "interpretation": "Low. Little exposure to active disruptions. 2 active events are listed in `disruption_events`." }, "replacement_difficulty": { "tier": "low", "interpretation": "Low. Easy to source from several places." } } }, "supply": { "stock": { "value": 350010, "unit": "units" }, "lead_time_median": { "value": 364, "unit": "days" }, "lead_time_min": { "value": 52, "unit": "days" }, "lead_time_max": { "value": 364, "unit": "days" }, "distributor_count": 28, "distributors": [ { "name": "Win Source", "country": "United Kingdom", "country_code": "GB", "regions": [ "Europe" ], "subregion": "Northern Europe", "stock": { "value": 91714, "unit": "units" } } ], "nearby": { "country": "Singapore", "country_code": "SG", "region": "Asia", "summary": "2 distributors elsewhere in Asia hold 5,765 units.", "distributors": [ { "name": "Antrex", "country": "China", "country_code": "CN", "regions": [ "Asia" ], "subregion": "Eastern Asia", "stock": { "value": 3046, "unit": "units" }, "proximity": "same_region" } ] } }, "datasheet": { "url": "https://apexcomponent.com/wp-content/uploads/2026/05/STM32F103RBT6-STMicroelectronics-Datasheet.pdf", "source": "other" }, "alternates": [ { "mpn": "XMC4100F64F128BAXQMA1", "manufacturer": "Infineon Technologies", "description": "IC MCU 32BIT 128KB FLASH 64TQFP", "match": "similar", "lifecycle": "Active", "supply": { "stock": { "value": 0, "unit": "units" }, "distributor_count": 0, "lead_time_median": { "value": 91, "unit": "days" } } } ] } ``` Trimmed for length: `notice`, `risk.why_at_risk`, `risk.drivers_detail`, `disruption_events` and `recommended_actions` are omitted, and `distributors`, `nearby.distributors` and `alternates` are cut to their first entry. Every field is listed in [the reference](https://docs.partfinder.dev/api-reference/parts/research-a-part.md). ### Reading it without parsing it `summary` is one sentence covering the score, the drivers flagged medium or above and the stock position, taken from the same supply figures returned in this response. If you are relaying to a person or a model, that line is enough on its own. ### The risk score `risk.composite` combines the four drivers under `risk.drivers`, and `risk.tier` is the band it falls in: `low`, `medium`, `high` or `critical`. | Driver | What it measures | | - | - | | `geography` | Exposure carried by where the part is made | | `lead_time_volatility` | How unstable the lead times quoted for it are | | `disruption_exposure` | Exposure to the events and shipping conditions in `disruption_events` | | `replacement_difficulty` | How hard it would be to switch to something else | Each is a band (`tier`: `low`, `medium`, `high` or `critical`) and an `interpretation`, one sentence about this part, not a generic description of the driver. Drivers carry no number; the composite does. `tier` is `null` when there is no data for a driver, and the sentence says why. > [!NOTE] > > A part in a BOM can score differently: see [BOM analysis](https://docs.partfinder.dev/bom-analysis.md#each-line). ### Disruption events `disruption_events` lists the reported events and shipping conditions that most affect `disruption_exposure`, strongest first: ordered by effect on this part's score, not by `severity`. `severity` is how serious the event or slowdown is in itself, not its effect on this part. Each item has a `kind`: | `kind` | What it is | | - | - | | `news` | A reported disruption, with its `id`, `root_cause`, `country`, `published_date` and a source `url` (`null` when no source article could be confirmed). Open it in full with [`GET /v1/events/{id}`](https://docs.partfinder.dev/events) | | `port_activity` | Ship traffic at the ports of a country this part is made in or sold from is well under its usual level, e.g. `"Ports in Mexico: ship arrivals 21% below the usual level for this time of year"`; `country` names it | | `sea_route` | The same for a sea passage this part's trade uses, e.g. `"Panama Canal: ship transits 21% below the usual level for this time of year"` | For `port_activity` and `sea_route`, `id` and `url` are `null`, and `published_date` is the last day of the week the figure covers. The list is empty when nothing affects the score noticeably. ### Supply `stock` and the lead times can be more recent than `as_of`. `distributor_count` is the number of distributors holding stock of this part. `distributors` lists those holding the most, largest first, and is not exhaustive. `lead_time_min` and `lead_time_max` are the 25th and 75th percentiles of the quoted lead times: the middle half of quotes. They come back `null` with a reason when that middle half is a single figure: there is no range to report. ### Buying near you Send the buyer's country as a two-letter ISO 3166-1 code, `country=SG`, and `supply.nearby` lists the distributors holding stock in that country first, then elsewhere in its region, with a `summary` sentence you can relay as it is: ```json theme={null} { "country": "Singapore", "country_code": "SG", "region": "Asia", "summary": "2 distributors elsewhere in Asia hold 5,765 units.", "distributors": [ { "name": "Antrex", "country": "China", "country_code": "CN", "regions": [ "Asia" ], "subregion": "Eastern Asia", "stock": { "value": 3046, "unit": "units" }, "proximity": "same_region" }, { "name": "Lankamic", "country": "China", "country_code": "CN", "regions": [ "Asia" ], "subregion": "Eastern Asia", "stock": { "value": 2719, "unit": "units" }, "proximity": "same_region" } ] } ``` Each distributor in `nearby.distributors` carries `proximity`: `same_country` or `same_region`. Every distributor, here and in `supply.distributors`, also carries `regions` and `subregion`, the parts of the world its listing serves, following the UN geographic regions: a storefront that states a wider area than one country, such as Europe, Middle East and Africa, lists each region it covers, and `subregion` is `null` when no country is known. These are not the `region` values of the [events feed](https://docs.partfinder.dev/events.md); to find events affecting a distributor, filter events by its `country_code`. The `nearby` list is empty, and the sentence says so, when nobody near the buyer holds stock. The risk score and every other field are the same with or without `country`; without it, `nearby` is `null`. A value that is not a country code answers `400`. ### Alternates `alternates` lists up to five parts that could replace this one: the same list, in the same shape, as [Find alternate parts](https://docs.partfinder.dev/alternates.md). Each carries how a supplier catalogue classifies it (`match`), its lifecycle and what distributors hold now. The same part in another package or ordering variant is never an alternate, the list is not ranked, and it can be empty. Confirm fit against the datasheets before substituting. ### Datasheet `datasheet.url` links to this part number's datasheet: a PDF where one is published, otherwise a page carrying it. It may be hosted by a distributor rather than the manufacturer. `null` when no datasheet was found. ## When the part number is not right Three refusals, and none of them returns a report. ### The input is not a specific part: `422` ```json theme={null} { "error": "not_a_specific_part", "summary": "\"3A buck converter 28V\" describes a class of parts rather than one specific part. Try one of these real part numbers instead: NB682, AP3503F, AP3003.", "did_you_mean": ["NB682", "AP3503F", "AP3003"] } ``` ### No supplier lists that part number: `404` ```json theme={null} { "error": "part_not_found", "summary": "\"TPS5433\" was not found at any supplier — it looks like a partial part number. Did you mean TPS54331, TPS54332, TPS54331D?", "did_you_mean": ["TPS54331", "TPS54332", "TPS54331D"] } ``` `did_you_mean` carries real part numbers on both refusals: parts of the kind you described on a `422`, and the listed part numbers your input is a prefix of on a `404`. `TPS5433` is not an orderable part; `TPS54331` and `TPS54332` are. ### We could not check: `503` ```json theme={null} { "error": "verification_unavailable", "summary": "We could not confirm that \"6305-2RS\" is a real part number right now, so no report was produced. This is temporary — retry shortly." } ``` Retry with backoff. **This is not the same as the part not existing**: that answer is `404`. Here the part could not be checked. ## Parts several manufacturers make Some part numbers are made by more than one company. `NE555N` is listed by STMicroelectronics, Philips, Signetics and others. ```python Python theme={null} import os import requests response = requests.get( "https://api.partfinder.dev/v1/parts", headers={"Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}"}, params={"mpn": "NE555N", "manufacturer": "STMicroelectronics"}, ) print(response.json()) ``` ```javascript JavaScript theme={null} const response = await fetch("https://api.partfinder.dev/v1/parts?mpn=NE555N&manufacturer=STMicroelectronics", { headers: { Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}` }, }); console.log(await response.json()); ``` ```bash cURL theme={null} curl "https://api.partfinder.dev/v1/parts?mpn=NE555N&manufacturer=STMicroelectronics" \ -H "Authorization: Bearer $PARTFINDER_API_KEY" ``` Supplying it gives you **a different report**, not a filtered view of the same one: each manufacturer's part is assessed on its own supply position, and lead-time volatility follows from that. Manufacturing origin follows the manufacturer too, when where that manufacturer makes the part is known; otherwise it is the part number's origin. A manufacturer that does not list the part returns a report with no supply data rather than an error, and its lead-time volatility is correspondingly less certain. The response then carries a note saying so, with the makers that do list it: ```json theme={null} "notes": [ { "kind": "manufacturer_not_listed", "summary": "Texas Instruments isn't among the makers distributors list for NE555N. It's listed from STMicroelectronics, onsemi, Philips Semiconductors and others.", "suggestions": ["STMicroelectronics", "onsemi", "Philips Semiconductors"] } ] ``` `notes` is always present and empty when there is nothing to note. ## Freshness `as_of` is when the report was produced, up to 48 hours before your call. Read `as_of` rather than assuming the report was produced for your call. Supply figures are at most 24 hours old. Responses carry `Cache-Control: no-store`; what that means and what you may store is in [Freshness](https://docs.partfinder.dev/conventions.md#freshness-and-the-as_of-timestamp). > [card] [Conventions](https://docs.partfinder.dev/conventions.md) > > How scores, units and nulls work across every response. > [card] [Errors](https://docs.partfinder.dev/errors.md) > > Every status code and what to do about it. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.