> ## 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 disruption event > One event in full. The `id` is the one `GET /v1/events`, `/v1/parts` and `/v1/bom` return. ## OpenAPI ````yaml https://api.partfinder.dev/v1/openapi.json get /v1/events/{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/events/{id}: get: tags: - Events summary: Get a disruption event description: >- One event in full. The `id` is the one `GET /v1/events`, `/v1/parts` and `/v1/bom` return. operationId: getEvent parameters: - name: id in: path required: true schema: type: integer minimum: 1 description: The event id. responses: '200': description: The event. content: application/json: schema: $ref: '#/components/schemas/EventResponse' example: as_of: '2026-10-01T12:16:43.703Z' summary: >- Ukraine Black Sea port attacks disrupt grain logistics in Odesa (high severity, Ukraine). 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. event: id: 1205 title: >- Ukraine Black Sea port attacks disrupt grain logistics in Odesa summary: >- Military attacks on ports and logistics facilities in Ukraine's Odesa and Mykolaiv regions have crippled grain loading operations, bringing Black Sea grain shipments close to a standstill. The disruption creates immediate logistics bottlenecks and threatens shortages of Ukrainian grain commodities on global markets. Buyers of Ukrainian commodities should track port availability and explore alternative supply sources. severity: high report_status: confirmed country: Ukraine country_code: UA region: Europe categories: - commodities - logistics root_cause: geopolitical_action supply_chain_impact: - logistics_disruption - shortage sourcing_implication: >- Attacks on Odesa and Mykolaiv ports hinder Ukrainian grain shipments, prompting buyers of Ukrainian commodities to monitor port availability and consider alternative sources. recommended_action: monitor sourcing_urgency: critical regions_exposed: - Europe - North America - Asia-Pacific - Latin America - Africa lead_time: text: as much as 12 days source: sentence: >- Özdemir said waiting times at the Sulina entrance to the Danube had increased from two or three days to as much as 12 days, adding demurrage costs and making delivery schedules harder to manage. url: >- https://millermagazine.com/en/blog/black-sea-disruption-shifts-grain-trade-focus-from-price-to-reliable-delivery-7046 interpretation: >- Reported by millermagazine.com on September 30, 2026 for shipments affected by this event. shipping_check: null source_urls: - >- http://rmb.reuters.com/rmd/rss/item/tag:reuters.com,2026:newsml_KBN3VD06W?channel=BEQ259 - >- https://www.livemint.com/market/wheat-falls-as-markets-monitor-black-sea-export-prospects/amp-11790558644308.html published_date: '2026-09-28T00:00:00.000Z' first_seen: '2026-09-28T04:46:31.972Z' 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 active event has that id. 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: EventResponse: 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. event: $ref: '#/components/schemas/DisruptionEvent' required: - as_of - summary - notice - event 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 DisruptionEvent: type: object properties: id: type: integer minimum: 0 description: >- The event id. The same id `/v1/parts` and `/v1/bom` return for this event. title: type: string summary: description: What happened, in a few sentences. anyOf: - type: string - type: 'null' severity: anyOf: - type: string enum: - low - medium - high - critical - type: 'null' description: How serious the event is in itself, not its effect on any one part. report_status: anyOf: - type: string enum: - confirmed - developing - probable - rumor - risk - type: 'null' description: >- How firm the reporting is: `confirmed`, `developing`, `probable`, `rumor`, or `risk` (a warning about something that has not happened). country: description: Where it happens. Null when it spans several countries. anyOf: - type: string - type: 'null' country_code: description: ISO 3166-1 alpha-2 code of `country`. anyOf: - type: string - type: 'null' region: anyOf: - type: string enum: - Asia-Pacific - Europe - North America - Middle East - Latin America - Africa - Global - type: 'null' description: >- Regions as supply-chain news is grouped, not the UN regions on distributors; to match a distributor or a part's origin, filter by `country` (an ISO 3166-1 alpha-2 code, as `country_code` on distributors and `manufacturing_country_code` on parts and BOM lines). categories: type: array items: type: string enum: - semiconductors - electronics - pcb - connectors - sensors - motors - drives - power_supplies - batteries - cables_wire - rf_microwave - optics - bearings - mechanical - hydraulics - pneumatics - seals_gaskets - fluid_handling - thermal - industrial_automation - filtration - safety_equipment - metals - chemicals - petrochemicals - plastics - raw_materials - pharmaceuticals - active_ingredients - medical_devices - agriculture - fertilizers - commodities - automotive - energy - logistics description: Component categories the event affects. root_cause: anyOf: - type: string enum: - natural_disaster - geopolitical_action - regulatory_change - labor_disruption - industrial_incident - infrastructure_failure - cyber_attack - type: 'null' description: What kind of cause lies behind the event. supply_chain_impact: type: array items: type: string enum: - shortage - logistics_disruption - production_halt - capacity_reduction - cost_increase - demand_spike - trade_restriction - supplier_failure - quality_issue - allocation description: Kinds of effect on supply. sourcing_implication: description: What it means for a buyer of the affected categories. anyOf: - type: string - type: 'null' recommended_action: anyOf: - type: string enum: - monitor - diversify - qualify_alternate - reroute - urgent - type: 'null' sourcing_urgency: anyOf: - type: string enum: - low - medium - high - critical - type: 'null' description: How soon a buyer should act. regions_exposed: type: array items: type: string enum: - Asia-Pacific - Europe - North America - Middle East - Latin America - Africa - Global description: >- Regions whose supply is exposed to it. Regions as supply-chain news is grouped, not the UN regions on distributors; to match a distributor or a part's origin, filter by `country` (an ISO 3166-1 alpha-2 code, as `country_code` on distributors and `manufacturing_country_code` on parts and BOM lines). lead_time: anyOf: - $ref: '#/components/schemas/EventLeadTime' - type: 'null' description: Added lead time for affected parts. Null when none is available. shipping_check: anyOf: - type: object properties: change_from_normal_percent: type: integer description: >- Change in port calls in the event's country during the event's week, against their usual level for the same time of year, in percent. Negative is below usual, positive above. interpretation: type: string description: One line of plain language. required: - change_from_normal_percent - interpretation - type: 'null' description: >- Port activity in the event's country during the event's week, for events about ports or shipping. Null when there is none. source_urls: type: array items: type: string format: uri description: News reports of this event. published_date: anyOf: - type: string format: date-time - type: 'null' description: When the event was first reported. first_seen: type: string format: date-time description: When PartFinder first recorded the event. required: - id - title - summary - severity - report_status - country - country_code - region - categories - root_cause - supply_chain_impact - sourcing_implication - recommended_action - sourcing_urgency - regions_exposed - lead_time - shipping_check - source_urls - published_date - first_seen EventLeadTime: type: object properties: text: type: string description: >- The lead time or delay, as a range in words, for example "+2-4 weeks" or "as much as 12 days". source: anyOf: - type: object properties: sentence: type: string description: The sentence in the report that states the lead time. url: type: string format: uri description: The report. required: - sentence - url - type: 'null' description: >- The report that states `text`, as written there. Null when `text` is an estimate. interpretation: type: string description: >- One line of plain language: who states this lead time, or that it is an estimate. required: - text - source - interpretation 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.