> ## 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.

# Track supply-chain disruptions

> List active supply-chain disruption events, open one in full, see which countries are hit, and read current port and sea-route activity.

Four calls cover disruption watch:

| Call | Returns |
| - | - |
| `GET /v1/events` | Active disruption events, newest first, filterable and paged |
| `GET /v1/events/{id}` | One event in full |
| `GET /v1/events/countries` | The countries on the risk map right now: how many events, and the worst severity |
| `GET /v1/events/shipping` | Port activity per country and ship transits per sea route, against their usual level for this time of year |

The event `id` is the same one [Research a part](https://docs.partfinder.dev/part-lookup.md) and [BOM analysis](https://docs.partfinder.dev/bom-analysis.md)
return in their events, so an agent can open any event it was handed.

## List events

```python Python theme={null}
import os

import requests

response = requests.get(
    "https://api.partfinder.dev/v1/events",
    headers={"Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}"},
    params={"country": "UA", "limit": 2},
)
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.partfinder.dev/v1/events?country=UA&limit=2", {
  headers: { Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}` },
});
console.log(await response.json());
```

```bash cURL theme={null}
curl "https://api.partfinder.dev/v1/events?country=UA&limit=2" \
  -H "Authorization: Bearer $PARTFINDER_API_KEY"
```

Every filter is optional:

* **`country`**: ISO 3166-1 alpha-2 code, for example `CN`.
* **`region`**: `Asia-Pacific`, `Europe`, `North America`, `Middle East`, `Latin America`, `Africa` or `Global`. These group
  supply-chain news, not the UN regions on distributors; to match the two, filter by `country`.
* **`category`**: a component category such as `semiconductors`, `bearings` or `logistics`. The full
  list is on the reference page, and a value outside it answers `400` with the list.
* **`days`**: only events first recorded in the last 1 to 90 days. Omit it for every active event.
* **`limit`** (1 to 100, default 50) and **`cursor`**: when `next_cursor` is not null, call again
  with `cursor` set to it for the next page.

## One event

```python Python theme={null}
import os

import requests

response = requests.get(
    "https://api.partfinder.dev/v1/events/1205",
    headers={"Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}"},
)
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.partfinder.dev/v1/events/1205", {
  headers: { Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}` },
});
console.log(await response.json());
```

```bash cURL theme={null}
curl "https://api.partfinder.dev/v1/events/1205" \
  -H "Authorization: Bearer $PARTFINDER_API_KEY"
```

```json theme={null}
{
  "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. ...",
  "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, ...",
    "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": ["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"
  }
}
```

Shortened. The full field reference is the "Get a disruption event" page in the API Reference tab.

* **`severity`** is how serious the event is in itself, not its effect on any one of your parts.
  For that, use [Research a part](https://docs.partfinder.dev/part-lookup.md) or [BOM analysis](https://docs.partfinder.dev/bom-analysis.md).
* **`report_status`** is how firm the reporting is: `confirmed`, `developing`, `probable`, `rumor`,
  or `risk` (a warning about something that has not happened).
* **`lead_time`** is the added lead time for affected shipments. When a report states one, `source`
  carries the sentence and its link, and `interpretation` says who reported it. When `source` is
  `null`, `text` is an estimate and `interpretation` says so. Relay it as an estimate.
* **`shipping_check`** is port activity in the event's country during the event's week, for events
  about ports or shipping.
* **`source_urls`** are news reports of the event.

## Which countries are hit

```python Python theme={null}
import os

import requests

response = requests.get(
    "https://api.partfinder.dev/v1/events/countries",
    headers={"Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}"},
)
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.partfinder.dev/v1/events/countries", {
  headers: { Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}` },
});
console.log(await response.json());
```

```bash cURL theme={null}
curl "https://api.partfinder.dev/v1/events/countries" \
  -H "Authorization: Bearer $PARTFINDER_API_KEY"
```

These are the countries on the risk map on partfinder.dev right now: recent events still unfolding,
with how many and their `worst_severity`, most severe first. It is not every country with an active
event: a country absent here can still have active events, so to answer "what is happening in this
country", call `GET /v1/events?country=`. Open the most severe of a country's listed events with
`GET /v1/events/{id}` and `top_event_id`.

## Port and sea-route activity

```python Python theme={null}
import os

import requests

response = requests.get(
    "https://api.partfinder.dev/v1/events/shipping",
    headers={"Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}"},
)
print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.partfinder.dev/v1/events/shipping", {
  headers: { Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}` },
});
console.log(await response.json());
```

```bash cURL theme={null}
curl "https://api.partfinder.dev/v1/events/shipping" \
  -H "Authorization: Bearer $PARTFINDER_API_KEY"
```

Each reading is `change_from_normal_percent`: how a country's port calls or a sea route's ship
transits over the latest week compare with their usual level for the same time of year. Negative is
below usual (`-96` is 96% below), positive above (`108` is more than twice the usual traffic). Each
reading also carries the last day it covers (`through`) and a sentence saying the same in words. Both
lists run furthest below usual first. A drop at a country's ports or at a strait delays shipments
through it.

## Errors

A filter outside its allowed values answers `400` with the allowed values in `summary`; an unknown event id answers `404 event_not_found`. Every code is on the [Errors](https://docs.partfinder.dev/errors.md) page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.