{"openapi":"3.1.0","jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","info":{"title":"Toolshelf.space Public Catalog API","version":"1.0.0","x-toolshelf-stability":"public-beta","x-toolshelf-versioning-policy":"Backward-compatible fields may be added within version 1. Breaking changes use a new major contract, and scheduled retirements are documented before standard Deprecation and Sunset headers are sent.","summary":"Read-only access to the Toolshelf digital tools catalog.","description":"Toolshelf.space is an independent catalog for choosing digital tools through source-backed public trails, people, company details, and product evidence. These public endpoints require no authentication. Results are bounded and cached to protect shared infrastructure."},"servers":[{"url":"https://www.toolshelf.space"}],"tags":[{"name":"Catalog","description":"Read-only catalog discovery."}],"paths":{"/api/tools":{"get":{"operationId":"searchTools","summary":"Search and browse tools","tags":["Catalog"],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":120}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"source","in":"query","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["top","discussed","newest"],"default":"top"}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"A bounded catalog page and the matching total.","content":{"application/json":{"schema":{"type":"object","required":["tools","totalCount"],"properties":{"tools":{"type":"array","items":{"type":"object","required":["id","slug","name","url","summary","categories","jobs","sources","firstSeenAt","scorePeak","commentsPeak"],"properties":{"id":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"summary":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"jobs":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"logoUrl":{"type":["string","null"]},"previewImageUrl":{"type":["string","null"]},"brandColor":{"type":["string","null"]},"urlStatus":{"type":"string"},"firstSeenAt":{"type":"string","format":"date-time"},"scorePeak":{"type":"integer"},"commentsPeak":{"type":"integer"}}}},"totalCount":{"type":"integer"}}}}}},"default":{"description":"A machine-readable RFC 9457 problem response.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail","code","resolution"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"code":{"type":"string"},"resolution":{"type":"string"}}}}}}}}},"/api/tools/by-slugs":{"get":{"operationId":"getToolsBySlugs","summary":"Get up to 100 tools by slug","tags":["Catalog"],"parameters":[{"name":"slugs","in":"query","required":true,"description":"Comma-separated Toolshelf slugs.","schema":{"type":"string"}}],"responses":{"200":{"description":"Matching published tools.","content":{"application/json":{"schema":{"type":"object","required":["tools"],"properties":{"tools":{"type":"array","items":{"type":"object","required":["id","slug","name","url","summary","categories","jobs","sources","firstSeenAt","scorePeak","commentsPeak"],"properties":{"id":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"summary":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"jobs":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"type":"string"}},"logoUrl":{"type":["string","null"]},"previewImageUrl":{"type":["string","null"]},"brandColor":{"type":["string","null"]},"urlStatus":{"type":"string"},"firstSeenAt":{"type":"string","format":"date-time"},"scorePeak":{"type":"integer"},"commentsPeak":{"type":"integer"}}}}}}}}},"503":{"description":"Catalog lookup is temporarily unavailable.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail","code","resolution"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"code":{"type":"string"},"resolution":{"type":"string"}}}}}},"default":{"description":"A machine-readable RFC 9457 problem response.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail","code","resolution"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"code":{"type":"string"},"resolution":{"type":"string"}}}}}}}}},"/api/command-index":{"get":{"operationId":"searchCommandIndex","summary":"Search the compact command index","tags":["Catalog"],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":120}}],"responses":{"200":{"description":"Compact tool matches, active source counts, and catalog total.","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"A machine-readable RFC 9457 problem response.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail","code","resolution"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"code":{"type":"string"},"resolution":{"type":"string"}}}}}}}}},"/api/tools/stack-recommendations":{"get":{"operationId":"getStackRecommendations","summary":"Get source-backed related tools","tags":["Catalog"],"parameters":[{"name":"slugs","in":"query","required":true,"description":"Up to 20 comma-separated seed slugs.","schema":{"type":"string"}}],"responses":{"200":{"description":"Up to six verified recommendations.","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"A machine-readable RFC 9457 problem response.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail","code","resolution"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"code":{"type":"string"},"resolution":{"type":"string"}}}}}},"default":{"description":"A machine-readable RFC 9457 problem response.","content":{"application/problem+json":{"schema":{"type":"object","required":["type","title","status","detail","code","resolution"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"code":{"type":"string"},"resolution":{"type":"string"}}}}}}}}}},"components":{"schemas":{"Problem":{"type":"object","required":["type","title","status","detail","code","resolution"],"properties":{"type":{"type":"string","format":"uri-reference"},"title":{"type":"string"},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"code":{"type":"string"},"resolution":{"type":"string"}}}}}}