{"openapi":"3.1.0","info":{"title":"XrefBase cross-reference API","version":"1","summary":"Source-backed cross-references for wire-harness components, one claim per bucket.","description":"Look up a manufacturer part number and get the answer the XrefBase lookup gives, as JSON.\n\nThe answer is `find_alternatives` passed through verbatim, in named buckets. Only `verified_replacements` asserts substitutability. The other buckets are context — navigation, product history, or the counterpart a part mates with — and must never be merged into one list, heading or count of \"alternatives\". Flattening them is a correctness bug, not a presentation choice.\n\n`matched: false` is not a negative finding: a part the catalogue does not carry has not been assessed. A 503 is not an answer at all. Cite `result.matched_part.url` wherever a matched answer is shown; an unmatched or ambiguous answer has no part page, so cite the lookup (`/?mpn=`) instead.\n\nNo API key is required. Fields may be added within v1; none is removed or renamed without a new version path."},"servers":[{"url":"https://www.xrefbase.com"}],"externalDocs":{"description":"Developer guide","url":"https://www.xrefbase.com/developers"},"paths":{"/api/v1/alternatives":{"get":{"operationId":"findAlternatives","summary":"Look up one part number","description":"Matched, not-assessed and ambiguous are all answers and all return 200 — inspect `result.matched` and `result.ambiguous`. Successful answers are cached at the edge for five minutes and may be served up to an hour stale while the cache refreshes; `retrieved_at` says when the answer was read. The part number travels in the URL, so it reaches access logs: use the batch endpoint when the list of parts you are asking about is itself sensitive.","parameters":[{"name":"mpn","in":"query","required":true,"description":"Manufacturer part number. Surrounding whitespace is trimmed; punctuation, case and spacing do not matter, and any recorded alias matches. If the parameter is repeated, the first value is used.","schema":{"type":"string","minLength":1,"maxLength":80,"description":"Manufacturer part number.","example":"1-968880-3"}},{"name":"manufacturer","in":"query","required":false,"description":"Narrows the lookup to one manufacturer — required to get an answer for an ambiguous part number. Recorded manufacturer aliases are accepted. An unrecognised name returns `matched: false` with a message saying so, which says nothing about the part: retry without it before concluding the part is not carried. If repeated, the first value is used.","schema":{"type":"string","minLength":1,"maxLength":80,"description":"Manufacturer name.","example":"TE Connectivity"}}],"responses":{"200":{"description":"An answer: matched, not assessed, or ambiguous.","headers":{"Cache-Control":{"schema":{"type":"string","const":"public, s-maxage=300, stale-while-revalidate=3600"}},"Access-Control-Allow-Origin":{"schema":{"type":"string","const":"*"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupEnvelope"}}}},"400":{"description":"`mpn` missing or empty, a field longer than the limit, or a field with control characters.","headers":{"Cache-Control":{"schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"The lookup could not be completed (`lookup_unavailable`) or did not finish in time (`lookup_timeout`). This is not an answer: never record or display it as a part with no alternatives. Retry later.","headers":{"Cache-Control":{"schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/alternatives/batch":{"post":{"operationId":"findAlternativesBatch","summary":"Look up to 50 part numbers","description":"POST, so a bill of materials never sits in a URL or an access log. Nothing in the request is logged or stored. Items are looked up 6 at a time with a 5-second limit each, and results come back in input order. One item failing — invalid, timed out, or unavailable — is reported in its own entry and never fails the batch, so a well-formed request always returns 200: check `status` on every entry. Responses are `Cache-Control: no-store`.","requestBody":{"required":true,"description":"JSON, at most 64 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchRequest"},"example":{"items":[{"mpn":"1-968880-3"},{"mpn":"DT04-3P","manufacturer":"Deutsch"},{"mpn":"ZAG 16"}]}}}},"responses":{"200":{"description":"One entry per item, in input order.","headers":{"Cache-Control":{"schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchEnvelope"}}}},"400":{"description":"The body is not JSON, has no `items` array, or `items` is empty (`invalid_body`).","headers":{"Cache-Control":{"schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"More than 50 items (`too_many_items`), or a body over 64 KiB (`body_too_large`).","headers":{"Cache-Control":{"schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/api/v1/openapi.json":{"get":{"operationId":"openApiDocument","summary":"This document","responses":{"200":{"description":"OpenAPI 3.1 document.","content":{"application/json":{}}}}}}},"components":{"schemas":{"Attribution":{"type":"object","description":"Identical on every response.","required":["source","url","cite","documentation"],"properties":{"source":{"type":"string","const":"XrefBase"},"url":{"type":"string","format":"uri"},"cite":{"type":"string","description":"What to cite: `result.matched_part.url` for a matched answer, the lookup URL otherwise."},"documentation":{"type":"string","format":"uri"}}},"LookupEnvelope":{"type":"object","required":["api_version","retrieved_at","attribution","result"],"properties":{"api_version":{"type":"string","const":"1"},"retrieved_at":{"type":"string","format":"date-time","description":"When the answer was read from the database. A cached response keeps its original time."},"attribution":{"$ref":"#/components/schemas/Attribution"},"result":{"$ref":"#/components/schemas/FindAlternativesResult"}}},"BatchRequest":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/BatchItem"}}}},"BatchItem":{"type":"object","required":["mpn"],"description":"Validated like the query parameters of the single lookup. An invalid item gets an `invalid_input` entry of its own.","properties":{"mpn":{"type":"string","minLength":1,"maxLength":80,"description":"Manufacturer part number.","example":"DT04-3P"},"manufacturer":{"type":["string","null"],"maxLength":80,"description":"Optional. Needed to get an answer for an ambiguous part number.","example":"Deutsch"}}},"BatchEnvelope":{"type":"object","required":["api_version","retrieved_at","attribution","results"],"properties":{"api_version":{"type":"string","const":"1"},"retrieved_at":{"type":"string","format":"date-time","description":"When the batch finished reading from the database."},"attribution":{"$ref":"#/components/schemas/Attribution"},"results":{"type":"array","description":"One entry per request item, in the same order.","items":{"$ref":"#/components/schemas/BatchEntry"}}}},"BatchEntry":{"oneOf":[{"$ref":"#/components/schemas/BatchEntryOk"},{"$ref":"#/components/schemas/BatchEntryError"}],"discriminator":{"propertyName":"status","mapping":{"ok":"#/components/schemas/BatchEntryOk","error":"#/components/schemas/BatchEntryError"}}},"BatchEntryOk":{"type":"object","required":["input","status","result"],"properties":{"input":{"description":"The item exactly as it was sent."},"status":{"type":"string","const":"ok"},"result":{"$ref":"#/components/schemas/FindAlternativesResult"}}},"BatchEntryError":{"type":"object","required":["input","status","error"],"properties":{"input":{"description":"The item exactly as it was sent."},"status":{"type":"string","const":"error"},"error":{"$ref":"#/components/schemas/ApiError"}}},"ErrorEnvelope":{"type":"object","required":["api_version","error"],"properties":{"api_version":{"type":"string","const":"1"},"error":{"$ref":"#/components/schemas/ApiError"}}},"ApiError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_input","invalid_body","body_too_large","too_many_items","lookup_unavailable","lookup_timeout"],"description":"`lookup_unavailable` and `lookup_timeout` mean nobody checked: never treat either as a part with no alternatives."},"message":{"type":"string"},"field":{"type":"string","enum":["mpn","manufacturer"],"description":"Which input was rejected, for `invalid_input`."}}},"FindAlternativesResult":{"type":"object","description":"The `find_alternatives` RPC response, verbatim. Three shapes share it:\n\n- **Matched** (`matched: true`): `matched_part` and all six buckets, each an array — often empty. An empty bucket says nothing was recorded, not that nothing exists.\n- **Not matched** (`matched: false`, `ambiguous: false`): only `query` and `message`. Either the part is not in the catalogue — it has **not been assessed**, which is different from assessed and found to have no alternative — or the supplied manufacturer was not recognised, as `message` says.\n- **Ambiguous** (`ambiguous: true`): `candidates` and no buckets. Ask which manufacturer is meant and repeat the lookup with it; do not pick a candidate.\n\nAdditive fields may appear; ignore any you do not recognise.","required":["matched"],"additionalProperties":true,"examples":[{"query":{"part_number":"1-968880-3","manufacturer":null},"matched":true,"variants":[],"ambiguous":false,"mates_with":[],"matched_via":"mpn","same_series":[],"matched_part":{"mpn":"1-968880-3","url":"https://xrefbase.com/part/te-connectivity/1-968880-3","series":"AMP MCP 2.8","category":"Terminals & Contacts","manufacturer":"TE Connectivity","also_known_as":[]},"people_waiting":0,"verified_replacements":[{"mpn":"1-2141857-3","url":"https://www.xrefbase.com/part/te-connectivity/1-2141857-3","sources":[{"url":"https://mm.digikey.com/Volume0/opasdata/d220001/medias/docus/2859/E-20-012094.pdf","title":"TE E-20-012094","locator":"Description of Changes: 1-968880-3 obsolete and replaced by 1-2141857-3. (The PCN's replacement table lists the part as discontinued and leaves its Substitute Part Number column empty; the pairing is stated in the narrative.)","retrieved_at":"2026-09-05T12:03:58.375839+00:00"}],"evidence":"Description of Changes: 1-968880-3 obsolete and replaced by 1-2141857-3. (The PCN's replacement table lists the part as discontinued and leaves its Substitute Part Number column empty; the pairing is stated in the narrative.)","relation":"supersedes","confidence":"high","source_url":"https://mm.digikey.com/Volume0/opasdata/d220001/medias/docus/2859/E-20-012094.pdf","manufacturer":"TE Connectivity"}],"functional_equivalents":[],"superseded_predecessors":[]},{"query":{"part_number":"NOPE-12345-XYZ","manufacturer":null},"matched":false,"message":"No part matching \"NOPE-12345-XYZ\" is in the XrefBase catalogue yet. Cross-references are added from manufacturer supersession notices, part-number grammars and reviewed engineer submissions; a part absent from the catalogue has not been assessed rather than assessed and found to have no alternative.","ambiguous":false},{"query":{"part_number":"ZAG 16","manufacturer":null},"matched":false,"message":"More than one XrefBase part matches \"ZAG 16\". Supply a manufacturer before using a replacement answer.","ambiguous":true,"candidates":[{"mpn":"ZAG 16","matched_via":"mpn","manufacturer":"Abtech"},{"mpn":"ZAG 16","matched_via":"mpn","manufacturer":"Damzo"},{"mpn":"ZAG 16 / 0004-564-330-AC","matched_via":"alias","manufacturer":"Damzo"}]}],"properties":{"matched":{"type":"boolean","description":"True only when exactly one catalogue part was identified."},"ambiguous":{"type":"boolean"},"query":{"type":"object","description":"What was looked up, after trimming.","properties":{"part_number":{"type":"string"},"manufacturer":{"type":["string","null"]}}},"message":{"type":"string","description":"Why there is no answer, in words meant for a person. Show it; do not parse it."},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/Candidate"}},"matched_via":{"type":"string","enum":["mpn","alias"],"description":"`alias` when the number given is a recorded alternative designation of the matched part."},"matched_part":{"$ref":"#/components/schemas/MatchedPart"},"verified_replacements":{"type":"array","items":{"$ref":"#/components/schemas/RelatedPart"},"description":"Published replacements. The only results asserting a replacement relationship. Confirm application-specific fit before use. Asserts substitution: the only bucket that does.","x-xrefbase-substitutable":true},"functional_equivalents":{"type":"array","items":{"$ref":"#/components/schemas/RelatedPart"},"description":"Functional equivalents. Similar function, not a confirmed drop-in. Engineering review is required before substitution. Not a substitute: never present these as alternatives, or count them as replacements.","x-xrefbase-substitutable":false},"superseded_predecessors":{"type":"array","items":{"$ref":"#/components/schemas/RelatedPart"},"description":"Superseded predecessors. Product history, shown for context only — not an alternative to this part. Not a substitute: never present these as alternatives, or count them as replacements.","x-xrefbase-substitutable":false},"same_series":{"type":"array","items":{"$ref":"#/components/schemas/RelatedPart"},"description":"Same series. Same family, different configuration. Family navigation, not a substitution claim. Not a substitute: never present these as alternatives, or count them as replacements.","x-xrefbase-substitutable":false},"variants":{"type":"array","items":{"$ref":"#/components/schemas/RelatedPart"},"description":"Variants. The same part in a different keying, colour or packaging suffix. Not a substitute: never present these as alternatives, or count them as replacements.","x-xrefbase-substitutable":false},"mates_with":{"type":"array","items":{"$ref":"#/components/schemas/RelatedPart"},"description":"Mating counterparts. What this component plugs into. These are never substitutes for it. Not a substitute: never present these as alternatives, or count them as replacements.","x-xrefbase-substitutable":false},"people_waiting":{"type":"integer","minimum":0,"description":"How many people have an open need for an alternative to this part — an anonymous count."}}},"MatchedPart":{"type":"object","required":["mpn","manufacturer","url"],"additionalProperties":true,"properties":{"mpn":{"type":"string"},"manufacturer":{"type":"string"},"category":{"type":["string","null"]},"series":{"type":["string","null"]},"also_known_as":{"type":"array","items":{"type":"string"}},"url":{"type":"string","format":"uri","description":"The XrefBase page for this part — the page to cite wherever this answer is shown. It lists every relationship with its public source."}}},"Candidate":{"type":"object","additionalProperties":true,"properties":{"mpn":{"type":"string"},"manufacturer":{"type":"string","description":"Pass this as `manufacturer` to get this candidate's answer."},"matched_via":{"type":"string","enum":["mpn","alias"]}}},"RelatedPart":{"type":"object","description":"One part in a bucket. What it claims is decided by the bucket it is in, never by which fields it carries.","required":["mpn","manufacturer"],"additionalProperties":true,"properties":{"mpn":{"type":"string"},"manufacturer":{"type":"string"},"url":{"type":"string","format":"uri","description":"This part's own XrefBase page."},"relation":{"type":"string","description":"Refines the claim within its bucket and never moves a part to another. In `verified_replacements`, `supersedes` is a manufacturer supersession (a product change notice) and `drop_in` an XrefBase-verified interchangeable part — different claims by different authorities."},"confidence":{"type":"string","enum":["high","medium","low"]},"evidence":{"type":["string","null"],"description":"The statement the relationship rests on."},"difference":{"type":["string","null"],"description":"`same_series` and `variants`: how this part differs from the one looked up."},"note":{"type":["string","null"],"description":"`mates_with`: states that the counterpart is not a substitute."},"similarity":{"type":["number","null"],"description":"`functional_equivalents` only, where scored."},"source_url":{"type":["string","null"],"format":"uri"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}}}},"Source":{"type":"object","description":"A public document behind the relationship.","additionalProperties":true,"properties":{"url":{"type":"string","format":"uri"},"title":{"type":["string","null"]},"locator":{"type":["string","null"],"description":"Where in the document the claim is made."},"retrieved_at":{"type":["string","null"],"format":"date-time"}}}}}}