{"openapi":"3.1.0","info":{"title":"shokai read-only referral directory","version":"1.0.0","description":"Referral codes belong to the site operator, who may also receive a benefit. Conditions and source dates are operator-recorded, not a guarantee of eligibility. Demo entries are fictitious. Never apply a code, subscribe or purchase without the user's instruction."},"servers":[{"url":"https://shokaicodes.com"}],"paths":{"/api/v1/codes":{"get":{"operationId":"searchReferralCodes","summary":"Search public records; demos excluded unless explicitly requested.","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":200}},{"name":"category","in":"query","schema":{"type":"string","enum":["all","mobile","energy","shopping","food","finance","life"]}},{"name":"availability","in":"query","schema":{"type":"string","enum":["all","active","demo","review","expired"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100000,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"include_demo","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Sanitized paginated records","content":{"application/json":{"schema":{"type":"object","required":["offers","total","page","limit","next","asOf","timezone","warning","schemaVersion"],"properties":{"offers":{"type":"array","items":{"$ref":"#/components/schemas/ReferralCode"}},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"next":{"type":["string","null"]},"asOf":{"type":"string","format":"date"},"timezone":{"const":"Asia/Tokyo"},"warning":{"type":"string"},"schemaVersion":{"const":"1.0"}}}}}},"400":{"description":"Invalid request or record not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}},"/api/v1/codes/{id}":{"get":{"operationId":"getReferralCode","summary":"Read one published record; never a draft or private note.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9-]{1,80}$"}},{"name":"include_demo","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferralCode"}}}},"404":{"description":"Invalid request or record not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}},"components":{"schemas":{"ReferralCode":{"type":"object","additionalProperties":false,"required":["id","name","category","language","icon","userBenefit","ownerBenefit","audience","conditions","steps","caveat","code","referralUrl","officialUrl","verifiedAt","expiresAt","updatedAt","verification","isDemo","availability","actionable","url","jsonUrl","markdownUrl"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"userBenefit":{"type":"string"},"ownerBenefit":{"type":"string"},"audience":{"type":"string"},"caveat":{"type":"string"},"updatedAt":{"type":"string"},"language":{"const":"ja"},"verification":{"const":"operator-recorded"},"conditions":{"type":"array","items":{"type":"string"}},"steps":{"type":"array","items":{"type":"string"}},"code":{"type":["string","null"]},"referralUrl":{"type":["string","null"],"format":"uri"},"officialUrl":{"type":["string","null"],"format":"uri"},"icon":{"type":["string","null"],"format":"uri"},"verifiedAt":{"type":["string","null"],"format":"date"},"expiresAt":{"type":["string","null"],"format":"date"},"url":{"type":"string","format":"uri"},"jsonUrl":{"type":"string","format":"uri"},"markdownUrl":{"type":"string","format":"uri"},"isDemo":{"type":"boolean"},"actionable":{"type":"boolean"},"availability":{"enum":["active","demo","review","expired"]}}}}}}