{"openapi":"3.1.0","info":{"title":"Shorterest reader API","version":"1.0.0","description":"Use the same reader token for all requests. Each account receives one stable editorial edition. Never expose account data or tokens. Confirm account creation and each profile/opinion write with the user."},"servers":[{"url":"https://shorterest.com"}],"components":{"securitySchemes":{"readerToken":{"type":"http","scheme":"bearer"}}},"paths":{"/api/account/register":{"post":{"operationId":"registerReader","summary":"Create an adult reader account only after explicit user confirmation; research consent is optional","security":[{"readerToken":[]},{}],"responses":{"200":{"description":"Success"},"201":{"description":"Created"},"400":{"description":"Invalid or unconfirmed input"},"401":{"description":"Sign in required"},"403":{"description":"Consent or permission required"},"404":{"description":"Unavailable in this reader edition"},"409":{"description":"Email already registered"},"429":{"description":"Retry later"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"},"password":{"type":"string","minLength":12,"maxLength":256},"account_create_confirmed":{"const":true},"age_confirmed":{"const":true},"research_consent":{"type":"boolean"}},"required":["email","name","password","account_create_confirmed","age_confirmed"],"additionalProperties":false}}}}}},"/api/account/login":{"post":{"operationId":"loginReader","summary":"Sign in; keep returned bearer token private","security":[{"readerToken":[]},{}],"responses":{"200":{"description":"Success"},"201":{"description":"Created"},"400":{"description":"Invalid or unconfirmed input"},"401":{"description":"Sign in required"},"403":{"description":"Consent or permission required"},"404":{"description":"Unavailable in this reader edition"},"409":{"description":"Email already registered"},"429":{"description":"Retry later"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"],"additionalProperties":false}}}}}},"/api/account/logout":{"post":{"operationId":"logoutReader","summary":"End this session","security":[{"readerToken":[]}],"responses":{"200":{"description":"Success"},"201":{"description":"Created"},"400":{"description":"Invalid or unconfirmed input"},"401":{"description":"Sign in required"},"403":{"description":"Consent or permission required"},"404":{"description":"Unavailable in this reader edition"},"409":{"description":"Email already registered"},"429":{"description":"Retry later"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[],"additionalProperties":false}}}}}},"/api/account/me":{"get":{"operationId":"getOwnProfile","summary":"Read only the authenticated reader profile and valid profile choices","security":[{"readerToken":[]}],"responses":{"200":{"description":"Success"},"201":{"description":"Created"},"400":{"description":"Invalid or unconfirmed input"},"401":{"description":"Sign in required"},"403":{"description":"Consent or permission required"},"404":{"description":"Unavailable in this reader edition"},"409":{"description":"Email already registered"},"429":{"description":"Retry later"}}}},"/api/account/profile":{"post":{"operationId":"saveOwnProfile","summary":"Save explicitly confirmed optional preferences and consent; withdrawing removes stored research responses","security":[{"readerToken":[]}],"responses":{"200":{"description":"Success"},"201":{"description":"Created"},"400":{"description":"Invalid or unconfirmed input"},"401":{"description":"Sign in required"},"403":{"description":"Consent or permission required"},"404":{"description":"Unavailable in this reader edition"},"409":{"description":"Email already registered"},"429":{"description":"Retry later"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"save_confirmed":{"const":true},"research_consent":{"type":"boolean"},"preferences":{"type":"array","items":{"type":"string"}},"demographics":{"type":"object","properties":{"age_range":{"type":"string"},"region":{"type":"string"},"gender":{"type":"string"}},"additionalProperties":false}},"required":["save_confirmed","research_consent"],"additionalProperties":false}}}}}},"/api/reader/articles":{"get":{"operationId":"listArticles","summary":"List this reader edition; anonymous preview is available","security":[{"readerToken":[]},{}],"responses":{"200":{"description":"Success"},"201":{"description":"Created"},"400":{"description":"Invalid or unconfirmed input"},"401":{"description":"Sign in required"},"403":{"description":"Consent or permission required"},"404":{"description":"Unavailable in this reader edition"},"409":{"description":"Email already registered"},"429":{"description":"Retry later"}},"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Search article text in this reader edition"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}]}},"/api/reader/articles/{id}":{"get":{"operationId":"readArticle","summary":"Read one article available in this reader edition","security":[{"readerToken":[]},{}],"responses":{"200":{"description":"Success"},"201":{"description":"Created"},"400":{"description":"Invalid or unconfirmed input"},"401":{"description":"Sign in required"},"403":{"description":"Consent or permission required"},"404":{"description":"Unavailable in this reader edition"},"409":{"description":"Email already registered"},"429":{"description":"Retry later"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}]}},"/api/reader/articles/{id}/response":{"post":{"operationId":"saveArticleOpinion","summary":"Save or update an explicitly confirmed personal opinion with research consent","security":[{"readerToken":[]}],"responses":{"200":{"description":"Success"},"201":{"description":"Created"},"400":{"description":"Invalid or unconfirmed input"},"401":{"description":"Sign in required"},"403":{"description":"Consent or permission required"},"404":{"description":"Unavailable in this reader edition"},"409":{"description":"Email already registered"},"429":{"description":"Retry later"}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"save_confirmed":{"const":true},"agreement":{"enum":["agree","mixed","disagree"]},"rating":{"type":"integer","minimum":1,"maximum":5}},"required":["save_confirmed","agreement","rating"],"additionalProperties":false}}}}}}}}