{"openapi":"3.1.0","info":{"title":"Humanoid Hub Product Catalog API","description":"Public read-only catalog endpoints for discovering, searching, and retrieving published humanoid robot records. Production data access, exports, and partner API usage are reviewed by request.","version":"1.0.0","contact":{"name":"Humanoid Hub","url":"https://www.humanoidhub.ai"}},"servers":[{"url":"https://www.humanoidhub.ai","description":"Production"}],"paths":{"/api/products":{"get":{"operationId":"listProducts","summary":"List and search humanoid robot products","description":"Returns a paginated list of active robot products. Supports filtering by category, manufacturer, price range, tags, availability, and full-text search.","parameters":[{"name":"search","in":"query","schema":{"type":"string"},"description":"Full-text search across product name and description"},{"name":"category","in":"query","schema":{"type":"string","enum":["humanoid","quadruped","industrial","educational","research","companion"]},"description":"Filter by product category"},{"name":"manufacturer","in":"query","schema":{"type":"string"},"description":"Filter by manufacturer name"},{"name":"tags","in":"query","schema":{"type":"string"},"description":"Comma-separated tags to filter by"},{"name":"minPrice","in":"query","schema":{"type":"integer"},"description":"Minimum price in cents"},{"name":"maxPrice","in":"query","schema":{"type":"integer"},"description":"Maximum price in cents"},{"name":"inStock","in":"query","schema":{"type":"boolean"},"description":"Filter to only in-stock products"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100},"description":"Number of results per page (max 100)"},{"name":"offset","in":"query","schema":{"type":"integer","default":0},"description":"Pagination offset"},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["price","name","created_at"]},"description":"Sort field"},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"]},"description":"Sort direction"}],"responses":{"200":{"description":"Successful product listing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductSummary"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}}}}},"/api/products/{slug}":{"get":{"operationId":"getProductBySlug","summary":"Get detailed product information","description":"Returns full product details including specifications, images, manufacturer info, videos, and documents.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"Product slug identifier"}],"responses":{"200":{"description":"Full product details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/Product"}}}}}},"404":{"description":"Product not found"}}}},"/api/products/videos":{"get":{"operationId":"getProductVideos","summary":"Get source-backed videos for a product","description":"Returns public product video rows for a specific humanoid robot product. Useful for agent experiences that want to surface demos, showcase clips, and PDP-linked video evidence.","parameters":[{"name":"productId","in":"query","required":true,"schema":{"type":"string","format":"uuid"},"description":"Product UUID identifier"}],"responses":{"200":{"description":"Successful product video response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"videos":{"type":"array","items":{"$ref":"#/components/schemas/ProductVideo"}}}}}}}}},"400":{"description":"Missing productId parameter"}}}},"/api/products/search":{"get":{"operationId":"searchProducts","summary":"Search products by keyword","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/ProductSummary"}}}}}}}}}}}},"/api/news":{"get":{"operationId":"listNewsArticles","summary":"List humanoid robotics news articles","description":"Returns a latest-first feed of source-backed humanoid robotics news articles. Supports category, source, topic, language, and keyword filters.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":60},"description":"Number of articles per page"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from the previous response"},{"name":"category","in":"query","schema":{"type":"string"},"description":"Filter by editorial category"},{"name":"topic","in":"query","schema":{"type":"string"},"description":"Filter by topic tag"},{"name":"source","in":"query","schema":{"type":"string"},"description":"Filter by source name"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Keyword search across title and summary"},{"name":"is_latest","in":"query","schema":{"type":"boolean","default":true},"description":"Filter to current latest versions"}],"responses":{"200":{"description":"Successful news feed response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NewsArticle"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}}},"/api/news/search":{"get":{"operationId":"searchNewsArticles","summary":"Search humanoid robotics news","description":"Search the humanoid robotics news corpus with full-text, semantic, or hybrid retrieval.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query"},{"name":"type","in":"query","schema":{"type":"string","enum":["fulltext","semantic","hybrid"],"default":"hybrid"},"description":"Search mode"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"responses":{"200":{"description":"Successful news search response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/NewsArticle"}}}}}}}}}},"/api/learn/{guideId}/related":{"get":{"operationId":"getRelatedLearningResources","summary":"Get related learning resources and catalog links","description":"Returns neighboring learning resources plus canonical product, use-case, buyer-guide, and learning links derived from the catalog relationship graph.","parameters":[{"name":"guideId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Learning resource UUID"}],"responses":{"200":{"description":"Related learning resources and canonical catalog links","content":{"application/json":{"schema":{"type":"object","properties":{"related":{"type":"array","items":{"$ref":"#/components/schemas/LearningResource"}},"catalog_links":{"type":"array","items":{"$ref":"#/components/schemas/CatalogLink"}}}}}}}}}}},"components":{"schemas":{"ProductSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"summary":{"type":"string"},"price_cents":{"type":"integer","description":"Price in cents (USD)"},"category":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"images":{"type":"array","items":{"type":"string","format":"uri"}},"status":{"type":"string"},"manufacturer":{"$ref":"#/components/schemas/Manufacturer"}}},"Product":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"summary":{"type":"string"},"description":{"type":"string"},"price_cents":{"type":"integer"},"category":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"images":{"type":"array","items":{"type":"string","format":"uri"}},"specs":{"type":"object","description":"Technical specifications (height, weight, DOF, payload, battery, sensors, etc.)","additionalProperties":true},"status":{"type":"string"},"buyable":{"type":"boolean"},"manufacturer":{"$ref":"#/components/schemas/Manufacturer"},"videos":{"type":"array","items":{"type":"object"}},"documents":{"type":"array","items":{"type":"object"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ProductVideo":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"product_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string"},"video_url":{"type":"string","format":"uri"},"thumbnail_url":{"type":"string","format":"uri"},"video_type":{"type":"string"},"duration_seconds":{"type":"integer"},"order_index":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"Manufacturer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"website":{"type":"string","format":"uri"},"logo_url":{"type":"string","format":"uri"}}},"NewsArticle":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"title":{"type":"string"},"canonical_title":{"type":"string"},"summary":{"type":"string"},"source_name":{"type":"string"},"source_url":{"type":"string","format":"uri"},"source_urls":{"type":"array","items":{"type":"string","format":"uri"}},"category":{"type":"string"},"topics":{"type":"array","items":{"type":"string"}},"curated_at":{"type":"string","format":"date-time"},"published_at":{"type":"string","format":"date-time"},"image_url":{"type":"string","format":"uri"},"thumbnail_url":{"type":"string","format":"uri"},"language":{"type":"string"},"is_latest":{"type":"boolean"}}},"LearningResource":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"title":{"type":"string"},"summary":{"type":"string"},"level":{"type":"string"},"cost":{"type":"string"},"contentType":{"type":"string"},"provider":{"type":"string"},"institution":{"type":"string"},"coverImage":{"type":"string","format":"uri"},"durationMinutes":{"type":"integer"},"canonical_url":{"type":"string","format":"uri"},"score":{"type":"number"},"reason":{"type":"string"}}},"CatalogLink":{"type":"object","properties":{"type":{"type":"string","enum":["product","manufacturer","solution","filter_page","best_guide","learning_resource"]},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"score":{"type":"number"},"reason":{"type":"string"},"related_product_names":{"type":"array","items":{"type":"string"}}}},"Pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}}