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

# Response conventions: scores, units, nulls, and freshness

> How PartFinder structures every response: scores with context, measures with units, explicit nulls with reasons, and an as_of freshness timestamp.

PartFinder responses are built to be used as they are. Scores explain themselves, measures include their units, unknown values are explicit rather than absent, and every response says how fresh its data is. Pass them straight to an agent, a UI or business logic.

## Scores

Every score in a PartFinder response is a structured object, never a bare number: the scale and the direction travel with the value.

A score object always contains four fields:

**value** `number` *required*

The numeric score.

**scale** `number` *required*

The maximum value the score can take. `100` means the score runs from 0 to 100.

**direction** `string` *required*

Which end of the scale is worse. One of `higher_is_worse` or `higher_is_better`.

**interpretation** `string` *required*

A plain-language sentence summarizing what this score means for this specific part. It can be relayed as-is, without re-deriving it.

A complete score object looks like this:

```json theme={null}
{
  "value": 72,
  "scale": 100,
  "direction": "higher_is_worse",
  "interpretation": "High. Concentrated manufacturing origin and long replenishment times."
}
```

The composite risk score is explained by four drivers:

| Driver | Field | What it measures |
| - | - | - |
| Geography | `geography` | Concentration of manufacturing and supply in geopolitically sensitive or disaster-prone regions. |
| Lead-time volatility | `lead_time_volatility` | Historical and projected variability in quoted lead times across distributors. |
| Disruption exposure | `disruption_exposure` | The part's exposure to active and recent supply chain disruption events. |
| Replacement difficulty | `replacement_difficulty` | How hard it is to substitute an equivalent part if this one becomes unavailable. |

A driver carries no number. Each is a band and a sentence:

```json theme={null}
{
  "tier": "high",
  "interpretation": "High. Reflects the risk profile of Mexico."
}
```

`tier` is `low`, `medium`, `high` or `critical`, or `null` when there is no data for the driver, in
which case `interpretation` says why. Read it as "where to look", not as a figure to compute with; the
composite is the number.

## Units

Every measure carries its unit inline. Stock levels, lead times, pricing, and other quantities are never bare numbers: each is an object pairing a value with its unit.

Examples of measure objects:

```json theme={null}
{
  "stock": {
    "value": 12400,
    "unit": "units"
  },
  "lead_time": {
    "value": 14,
    "unit": "days"
  }
}
```

A measure object renders correctly without anyone guessing whether `14` means days, weeks, or hours.

## Unknown values and nulls

When a value is not known, PartFinder represents it as an explicit `null` with an accompanying `reason` field explaining the data gap. Fields are never omitted. Read `reason` on any `null` value to see why it is unknown.

```json theme={null}
{
  "lead_time": {
    "value": null,
    "unit": "days",
    "reason": "No distributor currently quotes a lead time for this part."
  }
}
```

Common reasons for null values include:

* No distributor has current stock or pricing for the part
* The part has reached end-of-life and distributor data has aged out
* The data source for this attribute has not yet been indexed for this MPN

> [!NOTE]
>
> Every field in the schema is always present. A missing key is an error: report it.

## Freshness and the as\_of timestamp

Every successful PartFinder response includes an `as_of` field: an ISO 8601 UTC timestamp for the data in that response. Errors carry `error` and `summary` instead: see [Errors](https://docs.partfinder.dev/errors.md).

```json theme={null}
{
  "as_of": "2026-09-19T14:23:00Z"
}
```

`as_of` says when the data in the response was produced. It can be earlier than the moment you
receive it.

If freshness matters for your use case, such as real-time procurement decisions or active disruption
monitoring, read `as_of` and apply your own tolerance rather than assuming every field was
fetched at that instant.

You may store any response you receive and reuse it for as long as you like. Its figures are as of its `as_of`; call again for current ones. Responses carry `Cache-Control: no-store`, which tells proxies and CDNs not to keep a copy. It does not limit what you store in your own systems.

> [!TIP]
>
> Show `as_of` alongside anything you pass to users or downstream systems.

## Informational-use notice

Every successful PartFinder response carries a `notice` field with a consistent informational-use disclaimer:

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

This field is always present and always contains the same text. You can display it in your UI, include it in agent outputs, or log it alongside results. It is provided as a field rather than only in API documentation, so a consumer that never read the docs still has the disclaimer in context.

> [!NOTE]
>
> Pass `notice` through to whoever consumes the data.


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