Parts database API 21 million manufacturer part records over plain JSON. No key, no signup. The pitch, the live console and the whole reference, on one page.

THE REFERENCE

A read-only JSON API over 21.2 million manufacturer part records from 1,798 manufacturers. Every record carries a source URL and the date the record was last verified against it. Nothing is generated, inferred or guessed. A missing value means the source did not publish it.

Base URL   https://api.openspecindex.com
Auth       X-Api-Key: <key>      (or none: see Rate limits)
Format     JSON, UTF-8
Versioning /api/v1/ . A breaking change becomes /v2; v1 keeps answering.
Spec       https://api.openspecindex.com/openapi.json

What comes back is named after the endpoint. /parts returns parts. /values returns the valid values of one attribute. /count returns two numbers and no rows. /categories and /catalog.txt return the structure itself, not any data in it.

Path or query string? Required identity goes in the path, optional narrowing in the query. You cannot ask /values without saying values of what, so family and attribute are path segments. Every filter on /parts is optional, so they are all query parameters.

THE DATA MODEL, WHICH IS THE ONLY UNUSUAL PART

Raw catalogue data is inconsistent: every vendor describes a nut differently. So each part is classified into a normalised tree, and that tree is what you query.

FAMILY      the aisle            nut
  PART TYPE the shelf            nut/lock/nylon        (hierarchical: nut/lock includes nut/lock/nylon)
    GATES   identity attributes  thread_spec, material_class
    FACTS   everything else      grade_class, width_across_flats_in, ...

A gate is an identity claim, not a filter. Two parts must agree on every stated gate to be interchangeable. That distinction is what makes cross-referencing mean something: pooling happens on gates, scoring happens on the rest. Everything else on this page follows from it.

Coverage today: 75 families verified across 989 part types. A family that has not been through spec verification is not served, and says so.

WORKED EXAMPLE ONE: A LOCK NUT

1. WHICH FAMILY        grep it out of /api/v1/catalog.txt

     nut                      106102 parts   Fasteners
       nut/hex                          21962   thread_spec, material_class
       nut/lock/nylon                   10940   thread_spec, material_class

   The words after the type are its GATES: what defines identity for that part.

2. WHAT VALUES         GET /api/v1/values/nut/thread_spec?type=nut/lock/nylon
                       -> 1/4-20, 5/16-18, 3/8-16, 1/2-13, m6-1, m8-1.25, #10-32 ...

                       GET /api/v1/values/nut/material_class?type=nut/lock/nylon
                       -> steel (6879), stainless-steel (3440), brass (87), aluminum (76)

3. COUNT FIRST         GET /api/v1/count?family=nut&type=nut/lock/nylon
                           &attr.thread_spec=1/4-20&attr.material_class=stainless-steel
                       -> {"manufacturers": 31, "components": 140}

4. THE ROWS            same URL with /parts instead of /count

from openspec import OpenSpec
client = OpenSpec()

# 1. WHICH FAMILY. The plain-text catalog, same bytes as /api/v1/catalog.txt.
print(client.catalog_text())

#      nut                      106102 parts   Fasteners
#        nut/hex                          21962   thread_spec, material_class
#        nut/lock/nylon                   10940   thread_spec, material_class
#
#    The words after the type are its GATES: what defines identity for that part.

# 2. WHAT VALUES
client.values("nut", "thread_spec", type="nut/lock/nylon")
#   -> 1/4-20, 5/16-18, 3/8-16, 1/2-13, m6-1, m8-1.25, #10-32 ...
client.values("nut", "material_class", type="nut/lock/nylon")
#   -> steel (6879), stainless-steel (3440), brass (87), aluminum (76)

# 3. COUNT FIRST. Free and unlimited.
client.count(family="nut", type="nut/lock/nylon",
             thread_spec="1/4-20", material_class="stainless-steel")     # 140

# 4. THE ROWS. Same arguments, parts() instead of count().
page = client.parts(family="nut", type="nut/lock/nylon",
                    thread_spec="1/4-20", material_class="stainless-steel")

WORKED EXAMPLE TWO: A BALL VALVE

A completely different family, and note that not one gate is shared with the nut. There is no universal set of attributes: identity is defined per part type, which is why the tree has two levels.

1. WHICH FAMILY        valves                   652180 parts   Valves & Flow Control
                         ball-valve                      221962   connection_size_in, body_material_class,
                                                                  end1_connection_type, end2_connection_type
                         check-valve                      90216   connection_size_in, body_material_class, ...

2. WHAT VALUES         GET /api/v1/values/valves/connection_size_in?type=ball-valve
                       -> 1, 0.5, 0.75, 2, 1.5, 1.25, 3, 0.25          (inches, numeric)

                       GET /api/v1/values/valves/body_material_class?type=ball-valve
                       -> brass (36838), pvc (32770), stainless-steel (30637), bronze (25061)

3. COUNT FIRST         GET /api/v1/count?family=valves&type=ball-valve
                           &attr.body_material_class=brass&attr.connection_size_in=0.75
                       -> {"manufacturers": 72, "components": 2521}

4. THE ROWS            same URL with /parts instead of /count

# 1. WHICH FAMILY
cat = client.category("valves")
[t.type for t in cat.part_types][:3]     # 'ball-valve', 'check-valve', ...
[a.attr for a in cat.gates]              # the identity attributes

#      valves                   652180 parts   Valves & Flow Control
#        ball-valve                      221962   connection_size_in, body_material_class,
#                                                 end1_connection_type, end2_connection_type
#        check-valve                      90216   connection_size_in, body_material_class, ...

# 2. WHAT VALUES
client.values("valves", "connection_size_in", type="ball-valve")
#   -> 1, 0.5, 0.75, 2, 1.5, 1.25, 3, 0.25          (inches, numeric)
client.values("valves", "body_material_class", type="ball-valve")
#   -> brass (36838), pvc (32770), stainless-steel (30637), bronze (25061)

# 3. COUNT FIRST
client.count(family="valves", type="ball-valve",
             body_material_class="brass", connection_size_in=0.75)       # 2521

# 4. THE ROWS
page = client.parts(family="valves", type="ball-valve",
                    body_material_class="brass", connection_size_in=0.75)

Add one filter at a time and watch the count. Counts are free and unlimited, so when a number drops to zero you know exactly which filter did it. That is the whole debugging technique.

HOW VALUES MATCH

Text values are checked against a list; numbers are not. A misspelled text value returns 400 with the valid list. A number has no list to check against, so a dimension that nothing states returns an honest zero: attr.connection_size_in=0.8 finds nothing, and attr.airflow_cfm=32 matches only parts stating exactly 32. Read /values first. A value that is not a number at all returns 400 rather than an empty result.

A rating filters as a threshold, not an equality. Dimensions match exactly. Ratings do not: every attribute publishes a matches sentence, and the ones marked atLeast or atMost compare with ≥ and ≤. So attr.pressure_working_max_psi=175 returns everything rated 175 psi and higher. Ask for what the job needs, and a part rated higher still satisfies it. There is no operator to write, because the direction belongs to the attribute rather than to your query.

curl "https://api.openspecindex.com/api/v1/count?family=elbow&attr.pressure_working_max_psi=175"    # 8051
curl "https://api.openspecindex.com/api/v1/count?family=elbow&attr.pressure_working_max_psi=1000"   # 2163
curl "https://api.openspecindex.com/api/v1/count?family=elbow&attr.pressure_working_max_psi=5000"   #  338

# which behaviour applies: read the matches sentence on the attribute
curl "https://api.openspecindex.com/api/v1/values/elbow/pressure_working_max_psi"

client.count(family="elbow", pressure_working_max_psi=175)    # 8051
client.count(family="elbow", pressure_working_max_psi=1000)   # 2163
client.count(family="elbow", pressure_working_max_psi=5000)   #  338

# which behaviour applies
attr = client.category("elbow").attribute("pressure_working_max_psi")
attr.kind          # 'atLeast'
attr.is_threshold  # True
attr.matches       # 'Pass a number. Matches parts rated AT LEAST that number...'

pressure_class is not a pressure. It is an ASME class, which is a curve against temperature rather than a number: a Class 150 flange is rated 285 psi at 100°F and 75 psi at 800°F. Use it to identify a part, never to answer whether one is good for a given pressure.

DISCOVERY: YOU NEVER HAVE TO ASK US WHAT IS VALID

/api/v1/categories returns every family, its part types, the gates on each type, and every valid value with a count behind it. Build any query from this one response. The values it returns are exactly the values attr.<name>= accepts. Free and unlimited.

It is 3.7 MB in full, because every valid value of every gate on every type ships with its count. That is right for a client building a filter UI once and wrong for a person reading it. Two narrowings:

GET /api/v1/categories?slim=1              every family, no value lists      922 KB
GET /api/v1/categories?family=nut         one family, all its values        112 KB
GET /api/v1/categories?family=nut&slim=1  one family, types and gates        10 KB   <- start here

client.categories(slim=True)              # every family, no value lists      922 KB
client.categories("nut")                  # one family, all its values        112 KB
client.categories("nut", slim=True)       # one family, types and gates        10 KB   <- start here

client.category("nut")                    # the same one family, unwrapped, raises NotFound
client.values("nut", "thread_spec")       # one attribute only, about 1 KB

ENDPOINTS

FILTERS ON /parts AND /count

The Python client takes the same names as keyword arguments. Anything that is not one of the built-ins below is sent as attr.<name>, so client.parts(family="nut", thread_spec="1/4-20") and ?family=nut&attr.thread_spec=1/4-20 are the same request.

Paging is the same idea either way: ask for a page, then ask for the next one. The Python client wraps it, stops on the first empty page, and stops rather than hammering once the free tier is spent.

curl "https://api.openspecindex.com/api/v1/parts?family=screw&attr.thread_spec=1/4-20&limit=15&offset=0"
curl "https://api.openspecindex.com/api/v1/parts?family=screw&attr.thread_spec=1/4-20&limit=15&offset=15"

for part in client.iter_parts(family="screw", thread_spec="1/4-20", max_parts=500):
    print(part.mpn, part.source_url)

WHAT COMES BACK

{
  "mpn": "1061-10278-0042",
  "manufacturer": { "slug": "albany-county-fasteners", "name": "Albany County Fasteners" },
  "partType": "nut/lock/nylon",
  "specs":  { ... },          // the SOURCE's own labels, in the source's order
  "facts":  [ { "attr": "thread_spec", "value": "#10-32", "tier": 1, "sourceKey": "Thread Size" } ],
  "assets": { "cad": [...], "datasheets": [...], "images": [...] },
  "priceEach": 0.24,
  "package": { "stated": "Box of 100", "qty": 100 },
  "source":  { "url": "https://...", "checkedAt": "2026-07-05T00:00:00.000Z" }
}

specs is what the vendor wrote. facts is the normalised view, tiered: tier 1 is gates, tier 2 scored specs, tier 3 the rest. sourceKey says which raw field each fact came from, so you can always get back to the original. package exists because a published price is often for a box, not a piece, and an integration that assumes otherwise will be wrong by 100x.

Reading the same record, field by field:

curl -s "https://api.openspecindex.com/api/v1/parts/bufab/104621020110" \
  | jq '.part | {mpn, source: .source.url, checked: .source.checkedAt, priceEach}'

part = client.part("bufab", "104621020110")

part.source.url          # the manufacturer page this record cites
part.source.checked_at   # when the record was last verified
part.price_each
part.spec("thread_spec")
part.assets_of("cadFiles")

Cite the source. A specification with no source is a rumour, and removing rumours is the entire point of the index.

ERRORS: A TYPO IS AN ERROR, NOT AN EMPTY RESULT

Zero results is a wrong answer to a mistyped filter, and the caller cannot tell the difference from the outside. So unknown families, types and attributes return 400 with the valid options listed. The Python client keeps that message text verbatim.

GET /api/v1/parts?family=nut&attr.color=red
400  { "error": "unknown attribute \"color\" for family \"nut\"; valid: thread_spec,
        thread_dia_unspec, material_class, material_grade, grade_class, ..." }

GET /api/v1/find/flux-capacitor
404  { "not_combed_yet": ["capacitor"],
        "message": "We have not combed capacitors yet, so we will not guess..." }

from openspec import BadRequest, NotFound

try:
    client.parts(family="tee", material_class="carbon-steel")
except BadRequest as e:
    print(e)
    # unknown value "carbon-steel" for attr.material_class in family "tee".
    # Valid values: pvc, cast-iron, stainless-steel, copper, steel, brass, ...

The status codes are 400 bad request, 404 not found, 429 rate limited, 5xx server error. In Python those are BadRequest, NotFound, RateLimited and ServerError, all subclasses of OpenSpecError.

understood.ignored_words on /find lists the words that matched nothing and were not applied as filters. Show them to your user. A filter silently dropped is worse than a filter refused, because the caller believes it was applied.

curl -s "https://api.openspecindex.com/api/v1/find/cheap-4-inch-grooved-carbon-steel-tee" \
  | jq '{total, family: .understood.family, ignored: .understood.ignored_words}'
# { "total": 9, "family": "tee", "ignored": ["cheap", "carbon"] }

result = client.find("cheap 4 inch grooved carbon steel tee")
result.total          # 9
result.family         # 'tee'
result.ignored_words  # ('cheap', 'carbon')

RATE LIMITS

Counts, categories and discovery are free and unlimited, with or without a key. Row pulls are metered. Without a key you are identified by IP and get 100 lifetime row pulls to try it. Over the limit a data request degrades to a free match count rather than a 429, so an integration always receives an answer. Keyed accounts have configurable per-minute, hour, day and lifetime limits.

A degraded response is a real answer to a question the API declined to fully answer, so read the count before you read the rows. In Python that is page.limited, which never raises; iterating a limited page raises RateLimited rather than yielding nothing, because looping over it as if it were zero results would turn "out of budget" into "no such parts exist".

curl -s "https://api.openspecindex.com/api/v1/parts?family=nut" | jq '{total, limited, rows: (.parts | length)}'
# { "total": 106102, "limited": true, "rows": 0 }

page = client.parts(family="nut")
if page.limited:
    print(f"{page.total} matches, but out of free row pulls")

part.mpn
part.manufacturer.name
part.part_type
part.source.url         # the manufacturer page this record cites
part.source.checked_at  # when the record was last verified
part.source_url         # shorthand for the same URL
part.price_each
part.spec("thread_spec")     # one value out of the source's own labels
part.fact("thread_spec")     # the normalised Fact, with its tier and source key
part.gates                   # the tier-1 facts: what defines identity
part.assets_of("cadFiles")
part.raw                     # the untouched JSON, always kept

for family in ("tee", "elbow", "reducer", "nipple", "coupling"):
    print(family, client.count(family=family, size_in=4, material_class="steel"))

client.category("reducer").resolve("size_in")   # 'size_large_in'

a, b = client.part("bufab", "104621020110"), client.part("ace-hardware", "101134")

cmp = client.compare(a, b)                                          # Part objects
cmp = client.compare("bufab/104621020110", "ace-hardware/101134")   # or strings
cmp = client.compare(("bufab", "104621020110"), ("ace-hardware", "101134"))   # or tuples

print(cmp)                                  # 2 parts, 3 shared, 53 differing
for row in cmp.normalized_differences():
    print(row)                              # head style: pan | flat

price = cmp.supply_row("price_each")
price.values    # ('0.24', '11.49')
price.notes[1]  # 'the source states "Number in Package: 100 pack", so this price may be...'

for part in client.iter_parts(family="screw", thread_spec="1/4-20", max_parts=500):
    ...

page = client.parts(family="nut")
if page.limited:
    print(f"{page.total} matches, but out of free row pulls")

from openspec import BadRequest

try:
    client.parts(family="tee", material_class="carbon-steel")
except BadRequest as e:
    print(e)
    # unknown value "carbon-steel" for attr.material_class in family "tee".
    # Valid values: pvc, cast-iron, stainless-steel, copper, steel, brass, ...

LIMITATIONS, STATED PLAINLY

• 75 of ~890 families are verified. Anything else is refused as an unknown family rather than answered from an adjacent one.
• Match quality tracks gate depth. A part stating eight gates is pinned down precisely; a part stating three generic ones pools broadly with its neighbours. Count the tier-1 facts on a record to see which you are looking at.
• Row responses cap at 15. Counts are unlimited, so paginate against a count.
• Pricing is partial. Where a source published a price we carry it, with the package it applies to. Many did not.
• No SLA today. Ask before you depend on it.

EVERY CATEGORY AND ITS GATES

Rendered live from /api/v1/categories, so it is never out of date with the database. Every category listed has been through spec verification. The GATES are the identity attributes that define the part (two parts must agree on every gate to be interchangeable); the rest are scored, filterable specs. It is a long list, which is the point: this is the whole queryable surface in one place. Last on the page on purpose, so it is something you scroll to rather than something you scroll past.

Machine-readable spec at openapi.json. Agent-oriented instructions at llms.txt. Python client details, install and paging behaviour are in the Python client section.