Home/

API Documentation

v2

Critical Spares Express API

Programmatic access to the world's largest industrial bearing cross-reference database. Look up part equivalences, find substitutes, and integrate cross-reference data into your ERP, CMMS, or procurement systems.

Fast

Sub-100ms response times. Lookup any part number and get cross-references instantly.

Secure

API key authentication with SHA-256 hashing. Per-key rate limits and usage logging.

Comprehensive

172,000+ parts, 260,000+ cross-references, 400+ manufacturers from OEM interchange data.

Base URL

https://cse-parts.com/api/v2
API v1 is deprecated and will sunset on January 1, 2027. All v1 responses include Deprecation and Sunset headers. Please migrate to v2.

Quick Start

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://cse-parts.com/api/v2/lookup?pn=6205"

What's New in v2

  • Pagination on manufacturers endpoint (page, page_size, search)
  • New endpoint: GET /api/v2/part/:pn for direct part details
  • New endpoint: GET /api/v2/stats for database statistics
  • Enhanced metadata: data_sources, api_version, pagination info in every response
  • Status field in batch results (found/not_found/error)
  • Net votes included in equivalence responses

Authentication

All API requests require authentication via a Bearer token in the Authorization header. API keys are issued by the CSE team and follow the format cse_live_<48 hex chars>.

# Include your API key in every request
curl -H "Authorization: Bearer cse_live_abc123..." \
  "https://cse-parts.com/api/v2/lookup?pn=6205"

Keep your API key secret

Never expose your API key in client-side code, public repositories, or browser requests. Always make API calls from your server backend.

Getting an API Key

  1. Contact the CSE team to request partner access
  2. You'll receive a one-time API key — save it securely
  3. The key prefix (e.g., cse_live_abc1) is used for identification
  4. If compromised, contact us to revoke and reissue

Rate Limiting

Each API key has per-minute and per-day rate limits. Limits are returned in response headers so you can implement client-side throttling.

HeaderDescription
X-RateLimit-Limit-MinuteMaximum requests per minute
X-RateLimit-Remaining-MinuteRemaining requests this minute
X-RateLimit-Limit-DayMaximum requests per day
X-RateLimit-Remaining-DayRemaining requests today
X-RateLimit-ResetUnix timestamp when the minute window resets

When you exceed a rate limit, the API returns 429 Too Many Requests. Wait until the reset timestamp before retrying.

Part Lookup

GET/api/v2/lookup

Look up a single part number and get all known cross-references, equivalences, and dimensional data. Returns the best match plus alternatives if the exact part isn't found.

Parameters

NameTypeRequiredDescription
pnstringRequiredPart number to look up (e.g., 6205, 22310-E1, NA4905)
manufacturerstringOptionalFilter by manufacturer name (e.g., SKF, FAG, NTN)

Code Examples

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://cse-parts.com/api/v2/lookup?pn=6205&manufacturer=SKF"

Example Response

{
  "success": true,
  "data": {
    "part": {
      "id": 33,
      "part_number": "6205",
      "manufacturer": "SKF",
      "category": "bearing",
      "bearing_type": "ball",
      "dimensions": {
        "inner_diameter_mm": 25,
        "outer_diameter_mm": 52,
        "width_mm": 15
      },
      "seal_type": null,
      "tolerance_class": null,
      "source_count": 2
    },
    "equivalences": [
      {
        "part_number": "6205",
        "manufacturer": "FAG",
        "tier": "verified_exact",
        "confidence": 0.95,
        "bearing_type": "ball",
        "dimensions": {
          "inner_diameter_mm": 25,
          "outer_diameter_mm": 52,
          "width_mm": 15
        },
        "votes": { "up": 3, "down": 0 },
        "justification": "OEM interchange confirmed by Schaeffler and NTN-SNR"
      },
      {
        "part_number": "6205",
        "manufacturer": "NTN",
        "tier": "exact",
        "confidence": 0.88,
        "bearing_type": "ball",
        "dimensions": {
          "inner_diameter_mm": 25,
          "outer_diameter_mm": 52,
          "width_mm": 15
        },
        "votes": { "up": 1, "down": 0 },
        "justification": "Tier 1 (direct interchange): NTN-SNR cross-reference"
      }
    ],
    "other_matches": []
  },
  "meta": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "query": { "pn": "6205", "manufacturer": "SKF" },
    "result_count": 2,
    "timestamp": "2026-02-08T12:00:00.000Z"
  }
}

Batch Lookup

POST/api/v2/batch-lookup

Look up multiple part numbers in a single request. Maximum 50 parts per batch. Each part is resolved independently — failures for one part don't affect others.

Request Body

{
  "parts": [
    { "pn": "6205" },
    { "pn": "22310", "manufacturer": "SKF" },
    { "pn": "NA4905" },
    { "pn": "51105" }
  ]
}

Code Examples

curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parts":[{"pn":"6205"},{"pn":"22310","manufacturer":"SKF"}]}' \
  "https://cse-parts.com/api/v2/batch-lookup"

Example Response

{
  "success": true,
  "data": {
    "results": [
      {
        "pn": "6205",
        "manufacturer": null,
        "part": { "id": 33, "part_number": "6205", "manufacturer": "Generic", ... },
        "equivalences": [ ... ]
      },
      {
        "pn": "22310",
        "manufacturer": "SKF",
        "part": { "id": 1205, "part_number": "22310", "manufacturer": "SKF", ... },
        "equivalences": [ ... ]
      }
    ]
  },
  "meta": {
    "request_id": "...",
    "query_count": 2,
    "total_equivalences": 45,
    "timestamp": "2026-02-08T12:00:00.000Z"
  }
}

Manufacturers

GET/api/v2/manufacturers

List all manufacturers in the database with their part counts. Useful for building manufacturer dropdowns or understanding data coverage.

Code Examples

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://cse-parts.com/api/v2/manufacturers"

Example Response

{
  "success": true,
  "data": {
    "manufacturers": [
      { "name": "SKF", "part_count": 15615 },
      { "name": "Timken", "part_count": 14817 },
      { "name": "NTN", "part_count": 10845 },
      { "name": "FAG", "part_count": 7137 },
      { "name": "NSK", "part_count": 5842 },
      { "name": "KOYO", "part_count": 4231 },
      { "name": "INA", "part_count": 3156 }
    ]
  },
  "meta": {
    "request_id": "...",
    "total_manufacturers": 400,
    "timestamp": "2026-02-08T12:00:00.000Z"
  }
}

Part Detailv2 New

GET/api/v2/part/:pn

Get detailed information about a specific part number, including all manufacturer variants. Unlike lookup, this returns all variants of the same part number across different manufacturers.

Code Examples

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://cse-parts.com/api/v2/part/6205"

Example Response

{
  "success": true,
  "data": {
    "part_number": "6205",
    "variants": [
      {
        "id": 1234,
        "part_number": "6205",
        "manufacturer": "SKF",
        "bearing_type": "Deep Groove Ball Bearing",
        "dimensions": { "inner_diameter_mm": 25, "outer_diameter_mm": 52, "width_mm": 15 },
        "data_sources": ["schaeffler_interchange", "ntn_snr_interchange"]
      },
      {
        "id": 5678,
        "part_number": "6205",
        "manufacturer": "NTN",
        "bearing_type": "Deep Groove Ball Bearing",
        "dimensions": { "inner_diameter_mm": 25, "outer_diameter_mm": 52, "width_mm": 15 },
        "data_sources": ["ntn_snr_interchange"]
      }
    ],
    "manufacturer_count": 2
  },
  "meta": {
    "api_version": "2.0.0",
    "request_id": "...",
    "variant_count": 2,
    "timestamp": "2026-02-08T12:00:00.000Z"
  }
}

Database Statsv2 New

GET/api/v2/stats

Get current database statistics including total parts, equivalences, manufacturers, and data source breakdown. Useful for monitoring data coverage and freshness.

Code Examples

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://cse-parts.com/api/v2/stats"

Example Response

{
  "success": true,
  "data": {
    "total_parts": 172925,
    "total_equivalences": 260254,
    "total_manufacturers": 400,
    "verified_equivalences": 21932,
    "data_sources": [
      { "name": "schaeffler_interchange", "part_count": 8060 },
      { "name": "ntn_snr_interchange", "part_count": 20356 },
      { "name": "john_deere_catalog", "part_count": 144509 }
    ]
  },
  "meta": {
    "api_version": "2.0.0",
    "request_id": "...",
    "timestamp": "2026-02-08T12:00:00.000Z"
  }
}

Error Codes

All errors follow a consistent JSON envelope. The error.code field provides a machine-readable error identifier.

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  },
  "meta": {
    "timestamp": "2026-02-08T12:00:00.000Z"
  }
}
HTTP StatusError CodeDescription
400MISSING_PARAMRequired parameter is missing from the request
400INVALID_BODYRequest body is malformed or missing required fields
400BATCH_TOO_LARGEBatch request exceeds the 50-part limit
401UNAUTHORIZEDAPI key is missing, invalid, or malformed
403KEY_REVOKEDAPI key has been revoked by an administrator
403KEY_EXPIREDAPI key has passed its expiration date
429RATE_LIMIT_MINUTEPer-minute rate limit exceeded
429RATE_LIMIT_DAYPer-day rate limit exceeded
429QUOTA_EXCEEDEDMonthly quota exceeded — upgrade your tier
500INTERNAL_ERRORUnexpected server error — contact support

Webhooks

Register a webhook URL on your API key to receive real-time notifications when new cross-references are added for parts you've previously queried. This enables proactive inventory updates without polling.

Event: new_cross_reference

Fired when a new equivalence edge is added for a part number you've looked up in the past 30 days.

POST https://your-server.com/webhooks/cse
Content-Type: application/json
X-CSE-Signature: sha256=abc123...

{
  "event": "new_cross_reference",
  "timestamp": "2026-02-08T12:00:00.000Z",
  "data": {
    "part_number": "6205",
    "manufacturer": "SKF",
    "new_equivalence": {
      "part_number": "6205-2RS1",
      "manufacturer": "SKF",
      "tier": "exact",
      "confidence": 0.92
    }
  }
}

Signature Verification

Each webhook delivery includes an X-CSE-Signature header containing an HMAC-SHA256 signature of the request body using your webhook secret.

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), payload, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Webhook Setup

Contact the CSE team to configure your webhook URL and receive your webhook secret. Webhooks are delivered with exponential backoff retry (3 attempts).

SDKs & Client Libraries

Download our official SDKs to integrate the CSE Parts API into your application in minutes. Both packages include full type definitions, automatic retry on rate limits, and webhook signature verification.

🐍 Python SDK
v2.0.0

Full-featured Python client with requests library. Supports all v2 endpoints, automatic retry, and webhook verification.

# Install dependency
pip install requests
# Quick start
from
cse_parts_sdk
import
CSEPartsClient
client = CSEPartsClient("cse_live_...")
Download cse_parts_sdk.py
⚡ JavaScript SDK
v2.0.0

Zero-dependency JavaScript client using native fetch. Works in Node.js 18+ and modern browsers. Includes TypeScript definitions.

// No dependencies needed!
import { CSEPartsClient } from './cse-parts-sdk.js';
// Quick start
const client = new CSEPartsClient('cse_live_...');
.js.d.ts

SDK Features

Auto-Retry
Automatically retries on rate limit (429) with exponential backoff
Type Safety
Full TypeScript definitions included. Python SDK has JSDoc-style annotations.
Webhook Verification
Built-in HMAC-SHA256 signature verification for webhook payloads

Try It Live

Test the Part Lookup endpoint directly from this page. Enter your API key and a part number below.

Try It Live

Need help? Contact us at [email protected]