{"openapi":"3.1.0","info":{"title":"Zenode API","version":"0.1.0"},"paths":{"/health":{"get":{"tags":["health"],"summary":"Health","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/parts/search":{"get":{"tags":["parts"],"summary":"Search Parts","description":"Search electronic parts by Manufacturer Part Number (MPN).\n\nUse this endpoint whenever you need to look up a specific electronic component\nby its exact or partial part number. It is the primary way to retrieve rich,\nstructured data about a component — including technical specifications, pricing\noffers, datasheets, images, and supply-chain information.\n\nHOW IT WORKS\n------------\n1. The MPN string is sent to the Zenode discovery service, which performs a\n   fuzzy/prefix search and returns up to 10 candidate matches ranked by\n   relevance.\n2. The resulting slugs are used to hydrate each match from the internal Neo4j\n   graph database, which holds curated data: specs, offers, documents,\n   categories, and manufacturer details.\n3. The merged result is returned as a list of fully enriched part records.\n\nWHEN TO USE THIS ENDPOINT\n-------------------------\n- The user provides a part number (e.g. \"LM358\", \"STM32F103C8T6\", \"0402B104K500CT\").\n- You need to verify whether a part exists in the catalogue before referencing it.\n- You want to find equivalent or variant parts that share a common MPN prefix.\n- You need to retrieve pricing offers, stock levels, or supplier links for BOM\n  (Bill of Materials) processing.\n- You need technical specifications (voltage, current, package type, tolerance,\n  etc.) to compare or filter components.\n\nPARAMETERS\n----------\nmpn : str\n    The Manufacturer Part Number to search for. Can be an exact match or a\n    prefix. Examples: \"LM358\", \"NE555\", \"ATMEGA328P-PU\", \"100nF 0402\".\n    Case-insensitive. Partial strings are supported and return the closest\n    matches by relevance score.\n\nRESPONSE FIELDS (PartSearchResponse)\n-------------------------------------\nhits    : Total number of results returned.\nresults : List of matched parts. Each part contains:\n  - id            : Internal numeric ID of the part.\n  - mpn           : Exact MPN string as stored in the catalogue.\n  - slug          : URL-safe unique identifier (e.g. \"lm358-ti\"). Use this\n                    to build deep links or reference a part unambiguously.\n  - description   : Short one-line description of the part.\n  - long_description : Extended description with more technical context,\n                       may be null.\n  - part_status   : Lifecycle status code (e.g. active, NRND, obsolete).\n                    Null if unknown.\n  - canonical_id  : ID of the canonical/preferred variant when this part is\n                    a duplicate or alias. Null if this part is already canonical.\n  - manufacturer  : Object with id, name, and slug of the manufacturer.\n  - series        : Series/family the part belongs to (dict), may be null.\n  - categories    : List of category dicts the part is classified under.\n  - specs         : List of technical specification dicts, each with keys such\n                    as spec_name, spec_value, spec_type. May be null.\n  - images        : List of image dicts (url, caption, etc.). May be null.\n  - documents     : List of document dicts (datasheets, application notes, etc.).\n                    May be null.\n  - offers        : List of supplier offer dicts including price breaks, stock\n                    levels, lead times, and distributor names. May be null.\n\nEXAMPLE REQUESTS\n----------------\nGET /v1/parts/search?mpn=LM358\n    -> Returns all variants of the LM358 dual op-amp (TI, ST, ON Semi, etc.)\n       with full specs and current distributor offers.\n\nGET /v1/parts/search?mpn=STM32F103C8T6\n    -> Returns the exact STM32 microcontroller variant with its datasheet,\n       pinout specs, and live pricing from distributors.\n\nGET /v1/parts/search?mpn=GRM188R71C104KA01D\n    -> Returns the Murata 100nF 0402 ceramic capacitor with full spec sheet\n       and available stock across distributors.\n\nEXAMPLE USE CASES\n-----------------\n- BOM lookup: Given a list of MPNs from a PCB design file, call this endpoint\n  for each MPN to validate existence, retrieve specs, and gather pricing.\n- Substitution analysis: Search for a part, examine its specs, then search\n  for functionally equivalent MPNs with different manufacturer prefixes.\n- Supply-chain check: Use the offers field to identify which distributors have\n  stock, at what price tiers, and what the lead time is.\n- Datasheet retrieval: Use the documents field to find the official datasheet\n  URL for a component identified by its MPN.\n- Catalogue enrichment: Retrieve the canonical_id to detect and deduplicate\n  alias MPNs that map to the same physical component.\n\nNOTES\n-----\n- Returns an empty results list (hits=0) if no match is found; does not raise\n  an error for zero results.\n- The search is backed by Zenode's discovery engine, so relevance ranking may\n  surface near-matches even when an exact MPN is not in the catalogue.\n- Up to 10 results are returned per query. If you need the single best match,\n  take results[0] when hits > 0.","operationId":"search_parts_v1_parts_search_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"mpn","in":"query","required":true,"schema":{"type":"string","title":"Mpn"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartSearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/parts/agentic-search":{"get":{"tags":["parts"],"summary":"Agentic Search Parts","description":"Search electronic parts using a free-text natural-language query.\n\nThis is the recommended endpoint for AI agents and LLM-based workflows. Unlike\nthe MPN search (which requires an exact or near-exact part number), this endpoint\naccepts natural-language descriptions and keyword queries, making it suitable for\nintent-based lookups where the precise MPN is not yet known.\n\nHOW IT WORKS\n------------\n1. The free-text query is forwarded to the Zenode agent search engine, which\n   performs semantic/keyword matching across part descriptions, MPNs, and\n   manufacturer names.\n2. The matched slugs are used to hydrate each result from the internal Neo4j\n   graph database, returning fully enriched part records (same depth as MPN\n   search: specs, offers, documents, images, categories, manufacturer).\n3. The response also includes `available_specs` — a frequency map of spec names\n   present across the result set. Use this to understand which technical\n   dimensions (e.g. \"Voltage Rating\", \"Package\") are available for further\n   filtering.\n\nWHEN TO USE THIS ENDPOINT\n-------------------------\n- The user describes a component in natural language (e.g. \"low-power op-amp\",\n  \"5V LDO regulator\", \"NPN transistor 40V\").\n- You want to explore what parts exist for a given function or application.\n- The exact MPN is unknown and you need to discover candidates before drilling\n  down with a precise MPN lookup.\n- You want to present a ranked list of options to the user and let them choose.\n- You need to enumerate available spec facets to understand the search space\n  before applying filters.\n\nPARAMETERS\n----------\nsearch_query : str\n    Free-text description or keyword query for the desired electronic part.\n    Examples: \"op-amp rail-to-rail 5V\", \"100uF electrolytic capacitor\",\n    \"STM32 microcontroller USB\", \"MOSFET N-channel 30V 10A SOT-23\".\n    The search engine understands part descriptions, function names, package\n    codes, and partial MPNs.\n\nlimit : int (default 5, range 1–50)\n    Maximum number of parts to return. Keep this low (5–10) for conversational\n    use cases to avoid overwhelming context windows. Use higher values for\n    batch lookups or when building a comparison table.\n\noffset : int (default 0)\n    Number of results to skip. Combine with `limit` to paginate through a large\n    result set. For example, offset=10&limit=5 returns results 11–15.\n\npart_status : list[str] (default [\"active\"])\n    Filter by lifecycle status. Accepted values:\n      - \"active\"           : Currently in production, preferred choice.\n      - \"engineering_sample\": Pre-production samples, not yet fully available.\n      - \"nrnd\"             : Not Recommended for New Designs — still available\n                              but manufacturer recommends against new designs.\n      - \"ltb\"              : Last Time Buy — end-of-life, limited stock remains.\n      - \"obsolete\"         : No longer manufactured or stocked.\n      - \"unknown\"          : Status not determined.\n    Pass multiple values to include several statuses, e.g.:\n      ?part_status=active&part_status=nrnd\n\nRESPONSE FIELDS (AgenticSearchResponse)\n----------------------------------------\nhits           : Total number of results returned in this response.\navailable_specs: Dict mapping spec names to their frequency count across results.\n                 Use this to understand which filterable dimensions exist.\n                 Example: {\"Voltage Rating\": 8, \"Package\": 10, \"Current\": 6}\nresults        : List of matched parts. Each part contains:\n  - id            : Internal numeric ID of the part.\n  - mpn           : Manufacturer Part Number.\n  - slug          : URL-safe unique identifier. Use for unambiguous references\n                    or to build deep links to part detail pages.\n  - description   : Short one-line description.\n  - long_description : Extended description, may be null.\n  - part_status   : Lifecycle status code. Null if unknown.\n  - canonical_id  : ID of the canonical variant if this part is an alias. Null\n                    if this part is already the canonical record.\n  - manufacturer  : Object with id, name, and slug of the manufacturer.\n  - series        : Series/family dict the part belongs to, may be null.\n  - categories    : List of category dicts.\n  - specs         : List of technical spec dicts (spec_name, spec_value,\n                    spec_type). Use these to compare and filter candidates.\n  - images        : List of image dicts. May be null.\n  - documents     : List of document dicts (datasheets, app notes). May be null.\n  - offers        : List of supplier offer dicts with price breaks, stock\n                    levels, lead times, and distributor names. May be null.\n\nEXAMPLE REQUESTS\n----------------\nGET /v1/parts/agentic-search?search_query=low+power+op-amp\n    -> Returns up to 5 active op-amps ranked by relevance, with specs and offers.\n\nGET /v1/parts/agentic-search?search_query=100nF+0402+ceramic&limit=10\n    -> Returns up to 10 0402 ceramic capacitors near 100nF.\n\nGET /v1/parts/agentic-search?search_query=LDO+3.3V&part_status=active&part_status=nrnd&limit=10\n    -> Returns active and NRND 3.3V LDO regulators.\n\nGET /v1/parts/agentic-search?search_query=MOSFET+N-channel&limit=5&offset=5\n    -> Returns results 6–10 for N-channel MOSFETs (second page).\n\nEXAMPLE AGENT WORKFLOW\n----------------------\n1. User: \"I need a low-dropout 3.3V regulator for a battery-powered design.\"\n2. Call this endpoint with search_query=\"LDO 3.3V low dropout\" and limit=5.\n3. Inspect available_specs to see which specs are populated (e.g. \"Dropout Voltage\",\n   \"Quiescent Current\", \"Output Current\").\n4. Present the top candidates with their key specs to the user.\n5. If the user selects one, call GET /v1/parts/search?mpn=<chosen_mpn> for the\n   full detail view including all distributor offers and the datasheet link.\n\nNOTES\n-----\n- Returns an empty results list (hits=0) when no parts match; does not raise\n  an error for zero results.\n- Pagination via offset/limit is useful for \"show more\" workflows.\n- For the single best match to an ambiguous query, take results[0] when hits > 0.\n- If the user already knows the exact MPN, prefer GET /v1/parts/search?mpn=...\n  for faster and more precise lookup.","operationId":"agentic_search_parts_v1_parts_agentic_search_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"search_query","in":"query","required":true,"schema":{"type":"string","title":"Search Query"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":5,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"part_status","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"default":["active"],"title":"Part Status"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenticSearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/graphql":{"get":{"summary":"Handle Http Get","operationId":"handle_http_get_graphql_get","responses":{"200":{"description":"The GraphiQL integrated development environment.","content":{"application/json":{"schema":{}}}},"404":{"description":"Not found if GraphiQL or query via GET are not enabled."}},"security":[{"HTTPBearer":[]}]},"post":{"summary":"Handle Http Post","operationId":"handle_http_post_graphql_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}}},"components":{"schemas":{"AgenticSearchResponse":{"properties":{"hits":{"type":"integer","title":"Hits"},"results":{"items":{"$ref":"#/components/schemas/PartSearchResult"},"type":"array","title":"Results"},"available_specs":{"additionalProperties":{"type":"integer"},"type":"object","title":"Available Specs","default":{}}},"type":"object","required":["hits","results"],"title":"AgenticSearchResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ManufacturerResult":{"properties":{"id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"}},"type":"object","title":"ManufacturerResult"},"PartSearchResponse":{"properties":{"hits":{"type":"integer","title":"Hits"},"results":{"items":{"$ref":"#/components/schemas/PartSearchResult"},"type":"array","title":"Results"}},"type":"object","required":["hits","results"],"title":"PartSearchResponse"},"PartSearchResult":{"properties":{"id":{"type":"integer","title":"Id"},"mpn":{"type":"string","title":"Mpn"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Slug"},"description":{"type":"string","title":"Description"},"long_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Long Description"},"part_status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Part Status"},"canonical_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Canonical Id"},"manufacturer":{"anyOf":[{"$ref":"#/components/schemas/ManufacturerResult"},{"type":"null"}]},"series":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Series"},"categories":{"anyOf":[{"items":{"type":"object"},"type":"array"},{"type":"null"}],"title":"Categories"},"specs":{"anyOf":[{"items":{"type":"object"},"type":"array"},{"type":"null"}],"title":"Specs"},"images":{"anyOf":[{"items":{"type":"object"},"type":"array"},{"type":"null"}],"title":"Images"},"documents":{"anyOf":[{"items":{"type":"object"},"type":"array"},{"type":"null"}],"title":"Documents"},"offers":{"anyOf":[{"items":{"type":"object"},"type":"array"},{"type":"null"}],"title":"Offers"}},"type":"object","required":["id","mpn","description"],"title":"PartSearchResult"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}}}