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

# PartFinder API quickstart: your first authenticated call

> Create an API key in the console, send your first authenticated request to /v1/ping, and understand the response envelope every endpoint shares.

This guide takes you from no account to a verified, authenticated request. It should take about
five minutes.

> [!WARNING]
>
> Never hardcode API keys in client-side code, in version-controlled files, or anywhere reachable
> by someone who should not have them. Store keys in environment variables or a secrets manager and
> read them at runtime.

**1. Create an API key**

Sign in to the [PartFinder Console](https://console.partfinder.dev) and create a key in your
organization. Anyone can create an account at
[console.partfinder.dev/sign-up](https://console.partfinder.dev/sign-up) and pick pay as you go
or a monthly or yearly plan (see [pricing](https://partfinder.dev/pricing)). Pay as you go starts with
100 free credits, once per person and per company. To bring in teammates, see [Console](https://docs.partfinder.dev/console.md).

Keys belong to the organization rather than to you personally, so a key keeps working when
somebody leaves the team. The secret is shown once, when you create it, and cannot be shown
again. If you lose it, use **Rotate** on the key, or create a replacement and revoke the old one.

Keys look like `ak_` followed by 32 characters.

**2. Store it where your code can read it**

```bash theme={null}
export PARTFINDER_API_KEY="ak_..."
```

**3. Verify the key**

`/v1/ping` confirms your key is valid and tells you which organization it belongs to. It costs
no credits, so it is the right thing to call from a health check or a deployment smoke test.

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

import requests

res = requests.get(
    "https://api.partfinder.dev/v1/ping",
    headers={"Authorization": f"Bearer {os.environ['PARTFINDER_API_KEY']}"},
)
res.raise_for_status()
data = res.json()
```

```javascript JavaScript theme={null}
const res = await fetch("https://api.partfinder.dev/v1/ping", {
  headers: { Authorization: `Bearer ${process.env.PARTFINDER_API_KEY}` },
});

if (!res.ok) throw new Error(`PartFinder returned ${res.status}`);
const data = await res.json();
```

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

A valid key returns `200`:

```json theme={null}
{
  "as_of": "2026-09-18T10:00:55.303Z",
  "summary": "Authenticated. The PartFinder API is reachable and this key is valid.",
  "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.",
  "authenticated": {
    "organization_id": "org_2b7c...",
    "key_id": "ak_9f31..."
  }
}
```

A missing, unknown, revoked or expired key returns `401`. See [Errors](https://docs.partfinder.dev/errors.md).

## What every response looks like

Every endpoint returns the same envelope, so you can handle it once:

| Field | What it is |
| - | - |
| `as_of` | ISO 8601 timestamp for the data in this response |
| `summary` | One or two plain sentences your own agent or UI can relay directly |
| `notice` | Informational-use notice. Always present, always the same |

Beyond those, each endpoint adds its own payload. Scores and measures follow rules worth knowing
before you parse anything: see [Conventions](https://docs.partfinder.dev/conventions.md).

## Next

> [card] [Authentication](https://docs.partfinder.dev/authentication.md)
>
> Key lifecycle, revocation timing, and what the 401s mean.

> [card] [Conventions](https://docs.partfinder.dev/conventions.md)
>
> How scores, units, nulls and freshness work across every response.

> [card] [Errors](https://docs.partfinder.dev/errors.md)
>
> Status codes and how to handle them.

> [card] [API Reference](https://docs.partfinder.dev/api-reference/overview.md)
>
> Every endpoint, generated from our OpenAPI document.


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