{"openapi":"3.1.0","info":{"title":"Aha Translator API","version":"1.0.0","description":"Public metadata and authenticated English-learning operations used by the Aha Translator browser extension. OAuth activation and client registration are managed by Aha Translator; contact support before building a production integration. Errors return JSON `{ code, message, hint }` — clients should branch on `code`, not `message`.","contact":{"name":"Aha Translator developer support","email":"support@ahatranslator.com"}},"externalDocs":{"description":"Aha Translator developer resources","url":"https://www.ahatranslator.com/en/developers"},"servers":[{"url":"https://www.ahatranslator.com","description":"Production"}],"tags":[{"name":"Public","description":"Operations that require no authentication."},{"name":"Account","description":"Operations scoped to the authenticated user."},{"name":"Learning","description":"English-learning operations."}],"paths":{"/api/extension/version":{"get":{"operationId":"getExtensionVersionPolicy","summary":"Get the public extension version policy","tags":["Public"],"security":[],"parameters":[{"name":"currentVersion","in":"query","required":false,"schema":{"type":"string"},"description":"Installed semantic version, when known."}],"responses":{"200":{"description":"Current update policy and download URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionPolicy"}}}}}}},"/api/billing/plan":{"get":{"operationId":"getPublicBillingPlan","summary":"Get public plan and pricing display data","tags":["Public"],"security":[],"responses":{"200":{"description":"Public pricing data. Checkout remains server-authoritative.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicBillingPlan"}}}}}}},"/api/auth/verify":{"get":{"operationId":"verifyAccessToken","summary":"Verify the current bearer token","tags":["Account"],"security":[{"oauth2":["openid","email"]}],"responses":{"200":{"description":"The access token is valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifiedUser"}}}},"401":{"description":"The access token is missing, expired, or invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/words":{"get":{"operationId":"listSavedWords","summary":"List words saved by the authenticated user","tags":["Learning"],"security":[{"oauth2":["openid"]}],"responses":{"200":{"description":"Saved words in reverse chronological order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedWordList"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/translate":{"post":{"operationId":"translateLearningText","summary":"Translate and segment text for the learning experience","description":"Quota-metered product operation for the Aha learning UI. Not an unrestricted general translation API. Production integrations should contact support first.","tags":["Learning"],"security":[{"oauth2":["openid"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslateRequest"}}}},"responses":{"200":{"description":"Segmented source text and translations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslateResult"}}}},"400":{"description":"The request body is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"The signed-in plan has no remaining quota for this feature.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"An upstream rate limit was hit. Retry later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Aha Translator user access token issued by Supabase Auth."},"oauth2":{"type":"oauth2","description":"OAuth 2.1 authorization-code flow with mandatory PKCE.","flows":{"authorizationCode":{"authorizationUrl":"https://opwsdawsufthowmtmhbw.supabase.co/auth/v1/oauth/authorize","tokenUrl":"https://opwsdawsufthowmtmhbw.supabase.co/auth/v1/oauth/token","scopes":{"openid":"Identify the signed-in user.","email":"Read the signed-in user email address.","profile":"Read basic profile claims."}}}}},"schemas":{"ApiError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable code. Map this to UI copy; do not display `message` to end users.","examples":["UNAUTHORIZED","INVALID_REQUEST","FEATURE_LIMIT_REACHED"]},"message":{"type":"string","description":"Fallback English string for older clients."},"hint":{"type":"string","description":"How an agent or developer can recover from this error."}},"additionalProperties":true},"VersionPolicy":{"type":"object","required":["status","downloadUrl"],"properties":{"status":{"type":"string","enum":["current","optional","required"]},"currentVersion":{"type":["string","null"]},"latestVersion":{"type":["string","null"]},"downloadUrl":{"type":"string"}},"additionalProperties":true},"PublicBillingPlan":{"type":"object","required":["market","priceLabel","intervalLabel","yearly"],"properties":{"market":{"type":"string"},"priceLabel":{"type":"string"},"intervalLabel":{"type":"string"},"yearly":{"type":"object","required":["amount","priceLabel","intervalLabel"],"properties":{"amount":{"type":"string"},"priceLabel":{"type":"string"},"originalLabel":{"type":"string"},"discountPercent":{"type":"number"},"discountLabel":{"type":"string"},"intervalLabel":{"type":"string"}}}}},"VerifiedUser":{"type":"object","required":["valid","user"],"properties":{"valid":{"const":true},"user":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":["string","null"],"format":"email"}}}}},"SavedWord":{"type":"object","required":["_id"],"properties":{"_id":{"type":"string"},"word":{"type":"string"},"definition":{"type":"string"},"context":{"type":["string","null"]},"language":{"type":"string"},"timestamp":{"type":["string","number","null"]}},"additionalProperties":true},"SavedWordList":{"type":"object","required":["words"],"properties":{"words":{"type":"array","items":{"$ref":"#/components/schemas/SavedWord"}}}},"TranslateRequest":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1},"source":{"type":"string","description":"Source language code."},"target":{"type":"string","description":"Target language code."},"pageUrl":{"type":"string","format":"uri"}}},"TranslateSentence":{"type":"object","required":["original","translation","id"],"properties":{"original":{"type":"string"},"translation":{"type":"string"},"id":{"type":"integer"}}},"TranslateResult":{"type":"object","required":["sentences"],"properties":{"sentences":{"type":"array","items":{"$ref":"#/components/schemas/TranslateSentence"}},"cacheVersion":{"type":"string"},"quota":{"type":"object","additionalProperties":true}},"additionalProperties":true}}}}