# PartFinder API > ## 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. - [PartFinder API: Supply-Chain Intelligence for Industrial Parts](https://docs.partfinder.dev/index.md): Research parts, find alternates, scan BOMs, track disruptions and request quotes from suppliers. Designed for backend engineers and the agents they build. - [PartFinder API quickstart: your first authenticated call](https://docs.partfinder.dev/quickstart.md): Create an API key in the console, send your first authenticated request to /v1/ping, and understand the response envelope every endpoint shares. - [PartFinder API Authentication: Create and Use API Keys](https://docs.partfinder.dev/authentication.md): PartFinder uses organization-scoped API keys sent as Bearer tokens. Create and manage keys at console.partfinder.dev. - [PartFinder Console: Organization, Members and Roles](https://docs.partfinder.dev/console.md): How access to the PartFinder Console works: your organization, the Admin and Member roles, usage and the request log, webhooks, and inviting teammates. - [Error responses and status codes in the PartFinder API](https://docs.partfinder.dev/errors.md): PartFinder returns machine-readable JSON error codes alongside standard HTTP status codes, with a sentence you can relay. Learn what each code means and how to handle errors in code. - [Response conventions: scores, units, nulls, and freshness](https://docs.partfinder.dev/conventions.md): How PartFinder structures every response: scores with context, measures with units, explicit nulls with reasons, and an as_of freshness timestamp. - [Research a part](https://docs.partfinder.dev/part-lookup.md): Get a composite risk score, current supply, a datasheet, live disruption events and alternates for any manufacturer part number. - [Find alternate parts](https://docs.partfinder.dev/alternates.md): Get up to five parts that could replace a manufacturer part number, each with its current stock, distributor count, lead time and lifecycle. - [Search for parts](https://docs.partfinder.dev/search.md): Search by part number or by description and get the part and comparable parts, with their datasheets, key specifications and stock. - [Compare parts](https://docs.partfinder.dev/compare.md): 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. - [Analyze a BOM](https://docs.partfinder.dev/bom-analysis.md): Submit a bill of materials and get a risk score, drivers, gap flags and current supply for every line we can score, plus the BOM's own average, distribution and country breakdown. - [Track supply-chain disruptions](https://docs.partfinder.dev/events.md): List active supply-chain disruption events, open one in full, see which countries are hit, and read current port and sea-route activity. - [Requests for quote](https://docs.partfinder.dev/rfq.md): Email a request for quote to a supplier, read their replies with the quote laid out, and answer in the same email thread. - [Webhooks](https://docs.partfinder.dev/webhooks.md): Be told when a supplier replies to one of your requests for quote, when one bounces, or when a search or a comparison ends, instead of polling. - [Connect your AI agent to the PartFinder MCP server](https://docs.partfinder.dev/mcp-server.md): Add the PartFinder MCP server to your AI app and sign in: the server address, the two permissions you approve, what each tool call costs, how jobs are read, how to disconnect an app and how to use your own API key instead. - [Agent skill: give your AI agent the PartFinder API](https://docs.partfinder.dev/agent-skills.md): Add the PartFinder skill so your AI agent knows which endpoint answers which sourcing question, how to authenticate, how to poll jobs and how to handle refusals. - [Use PartFinder as an agent tool](https://docs.partfinder.dev/ai-agent-integration.md): Wire the PartFinder API into an agent: generate the tool from our OpenAPI document, hand the response straight to the model, and handle refusals without inventing parts. - [Use PartFinder with OpenAI tool calling](https://docs.partfinder.dev/tools-openai.md): Give a model on the OpenAI Responses API the PartFinder API as function tools built from the OpenAPI document. - [Use PartFinder with Anthropic tool calling](https://docs.partfinder.dev/tools-anthropic.md): Give Claude the PartFinder API as tools built from the OpenAPI document, run by the Anthropic SDK's tool runner. - [Connect the ChatGPT desktop app and Codex to the PartFinder MCP server](https://docs.partfinder.dev/mcp-chatgpt-desktop.md): Add the PartFinder MCP server to the ChatGPT desktop app, the Codex CLI and the Codex IDE extension through ~/.codex/config.toml and sign in with codex mcp login, or use your own API key from PARTFINDER_API_KEY. - [Connect Claude Code to the PartFinder MCP server](https://docs.partfinder.dev/mcp-claude-code.md): Add the PartFinder MCP server to Claude Code and sign in from the /mcp command, or use your own API key from PARTFINDER_API_KEY in a .mcp.json file. - [Connect Claude and Claude Desktop to the PartFinder MCP server](https://docs.partfinder.dev/mcp-claude-desktop.md): Add the PartFinder MCP server to Claude as a custom connector and sign in, or use your own API key in Claude Desktop's claude_desktop_config.json. - [Connect Cursor to the PartFinder MCP server](https://docs.partfinder.dev/mcp-cursor.md): Add the PartFinder MCP server to Cursor with a .cursor/mcp.json file and sign in, or use your own API key from PARTFINDER_API_KEY. - [Use PartFinder with the AI SDK by Vercel](https://docs.partfinder.dev/tools-ai-sdk.md): Give a model in the AI SDK by Vercel the PartFinder API as tools built from the OpenAPI document with jsonSchema. - [PartFinder REST API: reference overview and endpoints](https://docs.partfinder.dev/api-reference/overview.md): PartFinder REST API: base URL, versioning, Bearer auth, JSON request/response format, and all available supply-chain intelligence endpoints. - [Verify an API key](https://docs.partfinder.dev/api-reference/authentication/verify-an-api-key.md): Returns the organization the key belongs to. Use it to confirm an integration is wired correctly before calling an endpoint that does real work. - [Research a part](https://docs.partfinder.dev/api-reference/parts/research-a-part.md): Supply-chain intelligence for one industrial part: a composite risk score with its four drivers, current distributor availability, a datasheet link, the live disruption events that touch it, alternate parts, and recommended actions. - [Find alternate parts](https://docs.partfinder.dev/api-reference/parts/find-alternate-parts.md): 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. - [List your BOMs](https://docs.partfinder.dev/api-reference/boms/list-your-boms.md): Every BOM your organization has submitted (with a key made with `POST /v1/keys`, only that customer's), newest first, with its status, one page at a time. When `next_cursor` is not null, call again with `cursor` set to it for the next page. - [Analyze a BOM](https://docs.partfinder.dev/api-reference/boms/analyze-a-bom.md): Submit a bill of materials for supply-chain risk analysis. Use it whenever your user asks to scan or analyze a BOM or a list of parts, even a list of one line. Every line is identified, its origin and current distributor availability resolved, and a risk score computed from manufacturing geography,… - [Upload a BOM file](https://docs.partfinder.dev/api-reference/boms/upload-a-bom-file.md): Submit a bill of materials as a CSV or XLSX file. We find the part-number column and the other columns we recognise (manufacturer, quantity, supplier, description, and more), then run the same analysis as `POST /v1/bom`: the call answers `202` with the BOM id and `GET /v1/bom/{id}` carries the repor… - [Get a BOM report](https://docs.partfinder.dev/api-reference/boms/get-a-bom-report.md): The report for one BOM: a risk average and distribution, the gaps across the BOM, where it is made, and every line with its own score, drivers and current supply. While `bom.status` is `processing` the lines already analyzed are scored and the rest are `pending`; poll until it is `complete`. Each po… - [Delete a BOM](https://docs.partfinder.dev/api-reference/boms/delete-a-bom.md): Removes the BOM and every line. Irreversible. - [List disruption events](https://docs.partfinder.dev/api-reference/events/list-disruption-events.md): Active supply-chain disruption events, newest first, one page at a time: what happened, where, how serious, which component categories it affects, what it means for a buyer, and the news reports of it. Filter by country, region, category or how recently it was first recorded. When `next_cursor` is n… - [Get a disruption event](https://docs.partfinder.dev/api-reference/events/get-a-disruption-event.md): One event in full. The `id` is the one `GET /v1/events`, `/v1/parts` and `/v1/bom` return. - [Disruptions by country](https://docs.partfinder.dev/api-reference/events/disruptions-by-country.md): The countries on the risk map on partfinder.dev right now: recent events still unfolding, how many, and the worst severity among them. It is not every country with an active event: a country absent here can still have active events, listed by `GET /v1/events?country=`. Open the most severe of a coun… - [Port and sea-route activity](https://docs.partfinder.dev/api-reference/events/port-and-sea-route-activity.md): Port calls per country and ship transits per sea route over the latest week, as a change in percent against their usual level for this time of year. A drop at a port or a strait delays shipments through it. - [List your searches](https://docs.partfinder.dev/api-reference/search/list-your-searches.md): Every search your organization has run (with a key made with `POST /v1/keys`, only that customer's), newest first, one page at a time. When `next_cursor` is not null, call again with `cursor` set to it for the next page. Read one with `GET /v1/search/{id}` for its rows. - [Search for parts](https://docs.partfinder.dev/api-reference/search/search-for-parts.md): Find parts for a part number or a description: the part itself and comparable parts from the same or other makers, each with its product page, datasheet, the specifications that matter for this kind of part, and its stock and lead time at distributors. Answers `202` at once; read `GET /v1/search/{id… - [Get a search](https://docs.partfinder.dev/api-reference/search/get-a-search.md): A search and, once `status` is `complete`, the parts it found. While `status` is `processing`, read it again after 15 seconds, the wait `summary` and `Retry-After` state; each read counts as a call. `failed` means the search could not be completed: submit it again. - [Delete a search](https://docs.partfinder.dev/api-reference/search/delete-a-search.md): Removes the search and its results. Irreversible. - [List your comparisons](https://docs.partfinder.dev/api-reference/compare/list-your-comparisons.md): Every comparison your organization has run (with a key made with `POST /v1/keys`, only that customer's), newest first, one page at a time. When `next_cursor` is not null, call again with `cursor` set to it for the next page. Read one with `GET /v1/compare/{id}` for its parts. - [Compare parts](https://docs.partfinder.dev/api-reference/compare/compare-parts.md): Put parts side by side on the specifications that matter for this kind of part, read from each part's datasheet. To compare parts you name with each other, send them all in `parts`, the first being the reference. Send `mpn` alone only to compare one part with its alternates. Every other part gets on… - [Get a comparison](https://docs.partfinder.dev/api-reference/compare/get-a-comparison.md): 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:… - [Delete a comparison](https://docs.partfinder.dev/api-reference/compare/delete-a-comparison.md): Removes the comparison and its results. Irreversible. - [List your requests for quote](https://docs.partfinder.dev/api-reference/rfqs/list-your-requests-for-quote.md): Every request for quote your organization has sent (with a key made with `POST /v1/keys`, only that customer's), newest first, with its status, one page at a time. When `next_cursor` is not null, call again with `cursor` set to it for the next page. Read one with `GET /v1/rfq/{id}` for its messages. - [Send a request for quote](https://docs.partfinder.dev/api-reference/rfqs/send-a-request-for-quote.md): Email a request for quote to a supplier you name, under the requester's name. This sends a real email to `supplier.email`: every address and name in the request must come from your user, never be guessed or suggested; ask your user for any that are missing. Only these are required: the supplier's em… - [Get a request for quote](https://docs.partfinder.dev/api-reference/rfqs/get-a-request-for-quote.md): A request for quote and its email thread, oldest first: what was sent and every reply from the supplier. `status` is `replied` once the supplier has answered. Poll this to see new replies. - [Delete a request for quote](https://docs.partfinder.dev/api-reference/rfqs/delete-a-request-for-quote.md): Removes the request for quote and every message in its thread. Irreversible. A reply the supplier sends afterwards is not kept, and the supplier is not told. - [Send a message in a request for quote](https://docs.partfinder.dev/api-reference/rfqs/send-a-message-in-a-request-for-quote.md): Answer the supplier, or send a reminder, in the same email thread as the request for quote. The text is sent as written, under the requester's name. - [List customer keys](https://docs.partfinder.dev/api-reference/keys/list-customer-keys.md): Every key your organization created for its customers and has not revoked, newest first. Secrets are never listed. - [Create a key for a customer](https://docs.partfinder.dev/api-reference/keys/create-a-key-for-a-customer.md): Create an API key for one of your own customers. Requests for quote, BOMs, searches and comparisons made with it belong to that customer: its keys see only those, while your organization's own keys see everything. Its calls count against your organization's rate limit and its credits too. The respon… - [Revoke a customer key](https://docs.partfinder.dev/api-reference/keys/revoke-a-customer-key.md): Revoke one key of one of your customers. It stops working within about a minute. The customer's requests for quote, BOMs, searches and comparisons stay, and its other keys keep working. Your organization's own keys are not managed here. - [List webhook endpoints](https://docs.partfinder.dev/api-reference/webhooks/list-webhook-endpoints.md): Every endpoint your organization registered, newest first; with a key made with `POST /v1/keys`, only the endpoints registered with that customer's keys. Secrets are never listed. - [Register a webhook endpoint](https://docs.partfinder.dev/api-reference/webhooks/register-a-webhook-endpoint.md): Register an https:// address on your server. Each time a supplier replies to one of your requests for quote, an address bounces, or a search or a comparison ends, we send that address a signed event naming the request, the search or the comparison, so you read it with `GET /v1/rfq/{id}`, `GET /v1/se… - [Delete a webhook endpoint](https://docs.partfinder.dev/api-reference/webhooks/delete-a-webhook-endpoint.md): Stops sending events to the endpoint. Irreversible; register it again for a new secret. With a key made with `POST /v1/keys`, only that customer's endpoints can be deleted; any other id answers `404`. - [A supplier replied](https://docs.partfinder.dev/api-reference/webhooks/a-supplier-replied.md): Sent when a supplier replies to one of your requests for quote. Read the reply, and its quote when it is one, with `GET /v1/rfq/{id}`. - [A request for quote bounced](https://docs.partfinder.dev/api-reference/webhooks/a-request-for-quote-bounced.md): Sent when a request for quote, or a message in its thread, could not be delivered to the supplier's address. Send a new request for quote to a working address. - [A search ended](https://docs.partfinder.dev/api-reference/webhooks/a-search-ended.md): Sent when a search you started with `POST /v1/search` has ended. Read its rows with `GET /v1/search/{id}` when `data.status` is `complete`; when it is `failed`, submit the search again. - [A comparison ended](https://docs.partfinder.dev/api-reference/webhooks/a-comparison-ended.md): Sent when a comparison you started with `POST /v1/compare` has ended. Read its parts with `GET /v1/compare/{id}` when `data.status` is `complete`; when it is `failed`, submit the comparison again. ## OpenAPI Specs - [openapi](https://api.partfinder.dev/v1/openapi.json) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.