{"openapi":"3.1.0","info":{"title":"Console public review API","version":"1.0.0","description":"Read-only retrieval of published, dated editorial evidence, plus optional newsletter signup. Historical reviews do not establish current capabilities."},"servers":[{"url":"https://console.dev"}],"paths":{"/subscribe":{"post":{"operationId":"subscribeNewsletter","summary":"Request optional newsletter signup with the person's consent","description":"Subscribe with the person's permission, then follow the verification email instructions. No API key required. Do not retry 200 or 409; check the inbox if the response is lost.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["email"],"properties":{"email":{"type":"string","format":"email","maxLength":254}}}}}},"responses":{"200":{"description":"Accepted; the person must follow the verification email instructions","content":{"application/json":{"schema":{"type":"object","required":["status","message"],"properties":{"status":{"const":"accepted"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid, blocked, already subscribed, rate limited, or temporarily unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"Invalid, blocked, already subscribed, rate limited, or temporarily unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"Invalid, blocked, already subscribed, rate limited, or temporarily unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"413":{"description":"Invalid, blocked, already subscribed, rate limited, or temporarily unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Invalid, blocked, already subscribed, rate limited, or temporarily unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"502":{"description":"Invalid, blocked, already subscribed, rate limited, or temporarily unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"Invalid, blocked, already subscribed, rate limited, or temporarily unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}},"/api/v1/tools":{"get":{"operationId":"searchTools","summary":"Find reviewed developer tools","parameters":[{"name":"q","in":"query","description":"Up to 12 keywords, combined with AND; no FTS operators.","schema":{"type":"string","maxLength":200}},{"name":"category","in":"query","description":"Exact category name from tool responses.","schema":{"type":"string","maxLength":200}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}},{"name":"cursor","in":"query","description":"Opaque continuation value returned as nextCursor. Pagination reflects the current catalog; restart after publication changes.","schema":{"type":"string","pattern":"^[0-9]{1,4}$"}}],"responses":{"200":{"description":"Published editorial evidence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Search"}}}},"400":{"description":"Invalid request, missing record, request limit, or temporary failure","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"Invalid request, missing record, request limit, or temporary failure","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"405":{"description":"Invalid request, missing record, request limit, or temporary failure","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Invalid request, missing record, request limit, or temporary failure","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"Invalid request, missing record, request limit, or temporary failure","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}},"/api/v1/tools/{id}":{"get":{"operationId":"getTool","summary":"Retrieve a tool and its dated reviews","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}},{"name":"cursor","in":"query","description":"Opaque continuation value returned as nextCursor. Pagination reflects the current catalog; restart after publication changes.","schema":{"type":"string","pattern":"^[0-9]{1,4}$"}}],"responses":{"200":{"description":"Published editorial evidence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Detail"}}}},"400":{"description":"Invalid request, missing record, request limit, or temporary failure","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"404":{"description":"Invalid request, missing record, request limit, or temporary failure","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"405":{"description":"Invalid request, missing record, request limit, or temporary failure","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Invalid request, missing record, request limit, or temporary failure","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"503":{"description":"Invalid request, missing record, request limit, or temporary failure","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}}}}},"components":{"schemas":{"Rights":{"type":"object","required":["copyrightHolder","copyrightYear","statement","usageTerms","contact","usageInfo"],"properties":{"copyrightHolder":{"type":"string"},"copyrightYear":{"type":"integer"},"statement":{"type":"string"},"usageTerms":{"type":"string"},"contact":{"type":"string"},"usageInfo":{"type":"string"}}},"Tool":{"type":"object","required":["id","name","description","website","category","url","markdownUrl"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"website":{"type":"string"},"category":{"type":["string","null"]},"url":{"type":"string"},"markdownUrl":{"type":"string"}}},"Review":{"type":"object","required":["id","revisionId","url","reviewedOn","updatedAt","author","likes","dislikes"],"properties":{"id":{"type":"string"},"revisionId":{"type":"string"},"url":{"type":"string"},"reviewedOn":{"type":"string","format":"date"},"updatedAt":{"type":"string","format":"date-time"},"author":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}}},"likes":{"type":"string"},"dislikes":{"type":"string"}}},"Search":{"type":"object","required":["schemaVersion","items","nextCursor","historicalNotice","rights"],"properties":{"schemaVersion":{"const":1},"items":{"type":"array","items":{"allOf":[{"type":"object","required":["id","name","description","website","category","url","markdownUrl"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"website":{"type":"string"},"category":{"type":["string","null"]},"url":{"type":"string"},"markdownUrl":{"type":"string"}}},{"type":"object","properties":{"excerpt":{"type":"string"},"excerptSource":{"type":"string","enum":["likes","dislikes","tool"],"description":"tool excerpts are current profile metadata; likes/dislikes belong to the cited historical review."},"review":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"reviewedOn":{"type":"string","format":"date"}}}}}]}},"nextCursor":{"type":["string","null"]},"historicalNotice":{"type":"string"},"rights":{"$ref":"#/components/schemas/Rights"}}},"Detail":{"type":"object","required":["schemaVersion","tool","reviews","nextCursor","stacks","historicalNotice","rights"],"properties":{"schemaVersion":{"const":1},"tool":{"$ref":"#/components/schemas/Tool"},"reviews":{"type":"array","items":{"$ref":"#/components/schemas/Review"}},"nextCursor":{"type":["string","null"]},"stacks":{"type":["object","null"],"required":["observed_on","status","source_url","evidence","tags"],"properties":{"observed_on":{"type":"string","format":"date"},"status":{"type":"string","enum":["verified","unresolved"]},"source_url":{"type":"string"},"evidence":{"type":"string"},"tags":{"type":"array","items":{"type":"object","required":["key","label","dimension","relationship"],"properties":{"key":{"type":"string"},"label":{"type":"string"},"dimension":{"type":"string","enum":["language","runtime","framework","os","integration"]},"relationship":{"type":"string","enum":["runs_on","sdk","integration","implementation"]}}}}},"description":"Separately dated research: observed_on, status, source_url, evidence, and relationship-qualified tags. Null means unresearched."},"historicalNotice":{"type":"string"},"rights":{"$ref":"#/components/schemas/Rights"}}}}}}