> ## 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. # Get a comparison > A comparison and, once `status` is `complete`, its parts: the reference first, then each part compared with it. While `status` is `processing`, read it again after 9 seconds, the wait `summary` and `Retry-After` state; each read counts as a call. `failed` means the comparison could not be completed: submit it again. ## OpenAPI ````yaml https://api.partfinder.dev/v1/openapi.json get /v1/compare/{id} 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/compare/{id}: get: tags: - Compare summary: Get a comparison description: >- A comparison and, once `status` is `complete`, its parts: the reference first, then each part compared with it. While `status` is `processing`, read it again after 9 seconds, the wait `summary` and `Retry-After` state; each read counts as a call. `failed` means the comparison could not be completed: submit it again. operationId: getComparison parameters: - name: id in: path required: true schema: type: string format: uuid description: The comparison id. responses: '200': description: The comparison. headers: Retry-After: description: >- Sent only while `status` is `processing`: seconds to wait before reading the comparison again, 9. 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/Compare' example: 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. 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. 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. '401': description: Missing, unknown, revoked or expired key. content: application/json: schema: $ref: '#/components/schemas/Error' '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 comparison with that id belongs to your organization (with a key made with `POST /v1/keys`, to that customer). 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' components: schemas: Compare: 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. id: type: string format: uuid status: type: string enum: - processing - complete - failed description: >- `processing` until the comparison ends; `complete` with its parts; `failed` when it could not be completed (submit it again). created_at: type: string format: date-time completed_at: anyOf: - type: string format: date-time - type: 'null' description: When the comparison ended. Null while processing. columns: type: array items: type: string description: >- The specification names every part's `specs` and `verdicts` use. Empty until the comparison is complete, and also when the reference has nothing to be compared with. parts: type: array items: $ref: '#/components/schemas/ComparePart' description: >- The reference first, then the parts compared with it. Empty until the comparison is complete; a completed comparison of a part with no alternates carries the reference alone. required: - as_of - summary - notice - id - status - created_at - completed_at - columns - parts 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 ComparePart: type: object properties: mpn: type: string manufacturer: anyOf: - type: string - type: 'null' reference: type: boolean description: True for the part the others are compared with. match: anyOf: - type: string enum: - direct - parametric_equivalent - similar - upgrade - type: 'null' description: >- For an alternate of the part you sent: the parts catalogue's classification. Null for the reference, for your own list, and when none is given. 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. specs: type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: 'null' description: >- One entry per name in `columns`: the value the part's datasheet states, or null when it states none. datasheet_url: anyOf: - type: string format: uri - type: 'null' description: The datasheet the values were read from. Null when none was found. 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 comparison: anyOf: - type: object properties: verdicts: type: object propertyNames: type: string additionalProperties: type: string enum: - same - covers - narrower - higher - lower - different - not_stated description: >- How this part's value stands against the reference part's. `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. description: One verdict per name in `columns`. stated: type: integer minimum: 0 description: Specifications both datasheets state. same_or_covers: type: integer minimum: 0 description: Of those, `same` or `covers`. summary: type: string required: - verdicts - stated - same_or_covers - summary - type: 'null' description: Against the reference part. Null on the reference itself. required: - mpn - manufacturer - reference - match - lifecycle - specs - datasheet_url - supply - comparison 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.