> ## 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. # Find alternate parts > Parts that could replace one part, up to five, each with its current stock, distributor count, lead time and lifecycle. Never the part itself or the same part in another package. The list is kept server-side for 48 hours, so repeat calls return quickly; stock is read fresh on every call. Responses carry `Cache-Control: no-store`. Confirm fit and specifications against the datasheets before substituting. ## OpenAPI ````yaml https://api.partfinder.dev/v1/openapi.json get /v1/alternates openapi: 3.1.0 info: title: PartFinder API version: 1.0.0 license: name: Proprietary url: https://partfinder.dev/terms description: >- Supply-chain intelligence for industrial parts: risk scoring, supply availability, datasheets, disruption events, BOM analysis, alternates, part search and part comparison. Responses are structured for an AI agent to read — every score carries its scale, direction and an interpretation, every measure carries its unit, every successful response carries `as_of`, and every error carries an `error` code, usually with a `summary` you can relay, except a 413 (request body too large), which has no body. servers: - url: https://api.partfinder.dev security: - bearerAuth: [] tags: - name: Authentication description: Confirm an API key works. - name: Parts description: 'Research one part: risk, supply, datasheet, events, alternates.' - name: BOMs description: Analyze a bill of materials line by line. - name: Events description: >- Supply-chain disruptions: events, the countries they hit, and port and sea-route activity. - name: Search description: >- Find parts for a part number or a description, with specifications and stock. - name: Compare description: >- Put parts side by side on their specifications, with a verdict per specification. - name: RFQs description: Send requests for quote to suppliers and read their replies. - name: Keys description: Give each of your own customers a key that sees only its own data. - name: Webhooks description: >- Be told when a supplier replies, or a search or a comparison ends, instead of polling. paths: /v1/alternates: get: tags: - Parts summary: Find alternate parts description: >- Parts that could replace one part, up to five, each with its current stock, distributor count, lead time and lifecycle. Never the part itself or the same part in another package. The list is kept server-side for 48 hours, so repeat calls return quickly; stock is read fresh on every call. Responses carry `Cache-Control: no-store`. Confirm fit and specifications against the datasheets before substituting. operationId: getAlternates parameters: - name: mpn in: query required: true schema: type: string example: TPS54331DR description: The manufacturer part number to find alternates for. - name: manufacturer in: query required: false schema: type: string example: Texas Instruments description: >- Only needed for a part number several manufacturers make, such as NE555N. Omit it otherwise. responses: '200': description: The alternates. The list can be empty. content: application/json: schema: $ref: '#/components/schemas/AlternatesReport' example: as_of: '2026-09-29T07:28:59.267Z' summary: >- 3 alternates for TPS54331DR: AP63301WU-7 (Diodes Incorporated), AP63300WU-7 (Diodes Incorporated), AP64351SP-13 (Diodes Incorporated). 3 of them are in stock at a distributor. Confirm fit against the datasheets before substituting. notice: >- Informational only. Risk scores, stock levels, lead times and alternate-part suggestions may be incomplete, delayed or inaccurate. Independently verify before making procurement, engineering, compliance, safety or sourcing decisions. part: mpn: TPS54331DR manufacturer: null alternates: - mpn: AP63301WU-7 manufacturer: Diodes Incorporated description: Adjustable 3 A step-down regulator, 6-pin package match: similar lifecycle: Active supply: stock: value: 81702 unit: units distributor_count: 3 lead_time_median: value: 101 unit: days - mpn: AP63300WU-7 manufacturer: Diodes Incorporated description: Adjustable 3 A step-down regulator, 6-pin package match: similar lifecycle: Active supply: stock: value: 54602 unit: units distributor_count: 4 lead_time_median: value: 129 unit: days - mpn: AP64351SP-13 manufacturer: Diodes Incorporated description: Adjustable 3.5 A step-down regulator, 8-pin package match: similar lifecycle: Active supply: stock: value: 78939 unit: units distributor_count: 6 lead_time_median: value: 84 unit: days headers: X-RateLimit-Limit: description: >- Calls allowed in the current window: the minute or the day, whichever has fewer calls left. schema: type: integer minimum: 1 X-RateLimit-Remaining: description: Calls left in that window. schema: type: integer minimum: 0 X-RateLimit-Reset: description: Seconds until that window resets. schema: type: integer minimum: 1 '400': description: The `mpn` parameter is missing. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-RateLimit-Limit: description: >- Calls allowed in the current window: the minute or the day, whichever has fewer calls left. schema: type: integer minimum: 1 X-RateLimit-Remaining: description: Calls left in that window. schema: type: integer minimum: 0 X-RateLimit-Reset: description: Seconds until that window resets. schema: type: integer minimum: 1 '401': description: Missing, unknown, revoked or expired key. content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: >- This request was not run and nothing was charged. The error code names the case. `credits_exhausted`: your plan's credits for this month are used up; upgrade the plan in the PartFinder console. `payment_method_required`: your organization is on pay as you go with no payment method; add one in the console, or choose a plan. `payment_failed`: pay as you go is paused because the last payment failed; update the payment method in the console. `usage_limit_reached`: your organization, on pay as you go, has reached its limit for unpaid usage; calls resume once the current payment goes through. With a key made with `POST /v1/keys`, the `summary` tells your customer to contact your organization, and the answer carries no `billing_url`. The `summary` can be relayed as is; retry once the case is resolved. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: credits_exhausted summary: >- Your organization's credits for this month are used up, so this request was not run. Upgrade your plan in the PartFinder console at https://console.partfinder.dev/settings/billing, then try again. reason: This request needs 1 credit and 0 are left. billing_url: https://console.partfinder.dev/settings/billing headers: X-RateLimit-Limit: description: >- Calls allowed in the current window: the minute or the day, whichever has fewer calls left. schema: type: integer minimum: 1 X-RateLimit-Remaining: description: Calls left in that window. schema: type: integer minimum: 0 X-RateLimit-Reset: description: Seconds until that window resets. schema: type: integer minimum: 1 '403': description: >- The caller signed in through an AI app without the permission this call needs (`partfinder:read` to read, which includes looking up parts, alternates and events and uses credits for those; `partfinder:write` to change anything); the error is `insufficient_scope`. Or the AI app was disconnected in the console; the error is `app_disconnected`. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-RateLimit-Limit: description: >- Calls allowed in the current window: the minute or the day, whichever has fewer calls left. schema: type: integer minimum: 1 X-RateLimit-Remaining: description: Calls left in that window. schema: type: integer minimum: 0 X-RateLimit-Reset: description: Seconds until that window resets. schema: type: integer minimum: 1 '404': description: >- No distributor catalogue lists that part number exactly. Usually a typo or a partial part number. When listed part numbers begin with what you sent, `did_you_mean` carries up to five of them. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-RateLimit-Limit: description: >- Calls allowed in the current window: the minute or the day, whichever has fewer calls left. schema: type: integer minimum: 1 X-RateLimit-Remaining: description: Calls left in that window. schema: type: integer minimum: 0 X-RateLimit-Reset: description: Seconds until that window resets. schema: type: integer minimum: 1 '422': description: >- The input does not identify one specific part. When it described a class of parts, `did_you_mean` carries real part numbers to retry with. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-RateLimit-Limit: description: >- Calls allowed in the current window: the minute or the day, whichever has fewer calls left. schema: type: integer minimum: 1 X-RateLimit-Remaining: description: Calls left in that window. schema: type: integer minimum: 0 X-RateLimit-Reset: description: Seconds until that window resets. schema: type: integer minimum: 1 '429': description: >- Your organization has used its calls for this minute or this day. Wait the number of seconds in `Retry-After`, then retry. headers: Retry-After: description: Seconds until the limit resets. schema: type: integer minimum: 1 X-RateLimit-Limit: description: >- Calls allowed in the current window: the minute or the day, whichever has fewer calls left. schema: type: integer minimum: 1 X-RateLimit-Remaining: description: Calls left in that window. schema: type: integer minimum: 0 X-RateLimit-Reset: description: Seconds until that window resets. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: The alternates could not be produced right now. Retry shortly. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-RateLimit-Limit: description: >- Calls allowed in the current window: the minute or the day, whichever has fewer calls left. schema: type: integer minimum: 1 X-RateLimit-Remaining: description: Calls left in that window. schema: type: integer minimum: 0 X-RateLimit-Reset: description: Seconds until that window resets. schema: type: integer minimum: 1 '503': description: >- We could not confirm the part number is real right now. No list is produced for a part that cannot be verified. Temporary — retry shortly. content: application/json: schema: $ref: '#/components/schemas/Error' headers: X-RateLimit-Limit: description: >- Calls allowed in the current window: the minute or the day, whichever has fewer calls left. schema: type: integer minimum: 1 X-RateLimit-Remaining: description: Calls left in that window. schema: type: integer minimum: 0 X-RateLimit-Reset: description: Seconds until that window resets. schema: type: integer minimum: 1 components: schemas: AlternatesReport: type: object properties: as_of: type: string format: date-time description: ISO 8601. How current the data in this response is. summary: type: string description: Plain language an agent can relay without re-deriving it. notice: type: string description: Informational-use notice. Always present. part: type: object properties: mpn: type: string description: The part number you sent. manufacturer: description: The `manufacturer` you sent, or null. anyOf: - type: string - type: 'null' required: - mpn - manufacturer alternates: type: array items: $ref: '#/components/schemas/Alternate' description: >- Parts that could replace this one, up to five. Never this part itself or the same part in another package or ordering variant. Not ranked: the order carries no meaning, so compare them on `match`, `supply` and the datasheets. Empty when none was found. required: - as_of - summary - notice - part - alternates Error: type: object properties: error: type: string enum: - authentication_required - invalid_key - invalid_request - not_a_specific_part - part_not_found - verification_unavailable - generation_failed - bom_too_large - bom_not_found - bom_columns_not_found - event_not_found - rate_limited - supplier_opted_out - send_failed - rfq_not_found - rfq_bounced - message_refused - key_not_allowed - insufficient_scope - app_disconnected - key_not_found - key_name_taken - webhook_endpoint_not_found - not_a_parts_query - search_not_found - compare_not_found - credits_exhausted - payment_method_required - payment_failed - usage_limit_reached description: >- `authentication_required` when no bearer token was sent. `invalid_key` when the key or sign-in is unknown, revoked or expired — deliberately indistinguishable — or the sign-in names no organization you belong to (the `summary` says what to do). `invalid_request` when a required parameter is missing. `not_a_specific_part` when the input does not identify one specific part. `part_not_found` when no supplier lists that part number exactly — usually a typo or a partial number. `verification_unavailable` when we could not check whether the part is real, and so declined to describe it; temporary, safe to retry. `generation_failed` when the report could not be produced, or a search or a comparison could not be started. `bom_too_large` when one call carries more lines than the limit; `reason` states both numbers. `bom_not_found` when no BOM with that id belongs to your organization (with a key made with `POST /v1/keys`, to that customer). `bom_columns_not_found` when an uploaded file has no column we can identify as part numbers; `reason` lists the headers seen. `event_not_found` when no active event has that id. `rate_limited` when your organization has used its calls for this minute or this day; wait the seconds in the `Retry-After` header, then retry. `supplier_opted_out` when the supplier asked not to receive requests for quote from you, or from anyone through PartFinder. `send_failed` when the email could not be sent; nothing was stored, safe to retry. `rfq_not_found` when no request for quote with that id belongs to your organization (with a key made with `POST /v1/keys`, to that customer). `rfq_bounced` when the supplier's address could not receive the request; send a new request for quote to a working address. `message_refused` when the text was not sent; `summary` says what to change before sending again. `key_not_allowed` when a key that belongs to one of your customers calls an endpoint only your organization's own keys may call, or a caller signed in through an AI app manages keys or webhooks. `insufficient_scope` when an AI app signed in without the permission the call needs (`partfinder:read` to read, which includes looking up parts, alternates and events and uses credits for those; `partfinder:write` to change anything); the `summary` names it, and connecting the app again with it allowed fixes it. `app_disconnected` when the AI app the caller signed in through was disconnected in the console; signing in again does not help, allowing the app again in the console does. `key_not_found` when no live end-customer key with that id belongs to your organization. `key_name_taken` when a key with that name already exists in your organization, revoked keys included. `webhook_endpoint_not_found` when no webhook endpoint with that id belongs to your organization (with a key made with `POST /v1/keys`, to that customer). `not_a_parts_query` when a search query is not about a part; send a part number or describe the part. `search_not_found` when no search with that id belongs to your organization (with a key made with `POST /v1/keys`, to that customer). `compare_not_found` when no comparison with that id belongs to your organization (with a key made with `POST /v1/keys`, to that customer). `credits_exhausted` when your plan's credits for this month are used up; this request was not run and nothing was charged. Upgrade the plan at `billing_url`, then retry. `payment_method_required` when your organization is on pay as you go with no payment method; this request was not run and nothing was charged. Add a payment method or choose a plan at `billing_url`, then retry. `payment_failed` when pay as you go is paused because the last payment failed; this request was not run and nothing was charged. Update the payment method at `billing_url`, then retry. `usage_limit_reached` when your organization, on pay as you go, has reached its limit for unpaid usage; this request was not run and nothing was charged. Calls resume once the current payment goes through; follow it at `billing_url`. With a key made with `POST /v1/keys`, these four carry no `billing_url`: the `summary` asks your customer to contact your organization. summary: description: >- One sentence you can relay to a user as-is, the same as `summary` on a successful response. Present whenever there is something useful to say about what went wrong. type: string reason: description: The specific detail behind the error. type: string billing_url: description: >- On `credits_exhausted`, `payment_method_required`, `payment_failed` and `usage_limit_reached`: the PartFinder console Billing page, where your organization manages its plan and payment method. Absent for a key made with `POST /v1/keys`, and for an organization whose plan is set by its contract. type: string format: uri did_you_mean: description: >- Real part numbers to retry with. On `not_a_specific_part` they are parts of the kind you described; on `part_not_found` they are the listed part numbers your input is a prefix of, so `TPS5433` returns TPS54331, TPS54332 and so on. Absent when there is nothing to suggest. Every entry is a real part number, never a guess. type: array items: type: string required: - error Alternate: type: object properties: mpn: type: string description: The alternate's manufacturer part number. manufacturer: anyOf: - type: string - type: 'null' description: description: A one-line description of the part. Null when none is available. anyOf: - type: string - type: 'null' lifecycle: anyOf: - type: string enum: - Active - Mature - NRND - EOL - Obsolete - type: 'null' description: Where the part is in its life. Null when no source states one. match: anyOf: - type: string enum: - direct - parametric_equivalent - similar - upgrade - type: 'null' description: >- How a supplier catalogue classifies this part against the one you asked about: `direct`, `parametric_equivalent`, `similar` or `upgrade`. Null when the catalogue gives no classification. Confirm fit and specifications against both datasheets before substituting. supply: type: object properties: stock: $ref: '#/components/schemas/Measure' description: Units held across the distributors we can see. distributor_count: anyOf: - type: integer minimum: 0 - type: 'null' description: >- Distributors holding stock. Null when supply could not be read; `stock` says why. lead_time_median: $ref: '#/components/schemas/Measure' required: - stock - distributor_count - lead_time_median required: - mpn - manufacturer - description - lifecycle - match - supply Measure: type: object properties: value: anyOf: - type: number - type: 'null' unit: type: string reason: description: Present only when value is null. type: string required: - value - unit securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key created in the PartFinder console at https://console.partfinder.dev, or a customer key created with `POST /v1/keys`. Send as `Authorization: Bearer `. Revocation takes effect within approximately one minute. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.