{"openapi":"3.1.1","info":{"title":"Gift Story Backend API","description":"Authentication endpoints plus the store, order, customer and support APIs. Order prices and totals are always computed on the server.","version":"0.1.0"},"components":{"schemas":{"User":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string"},"email":{"type":"string"},"emailVerified":{"type":"boolean","default":false,"readOnly":true},"image":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"role":{"type":"string","default":"customer","readOnly":true}},"required":["id","name","email","emailVerified","createdAt","updatedAt"]},"Session":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"expiresAt":{"type":"string","format":"date-time"},"token":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"ipAddress":{"type":"string"},"userAgent":{"type":"string"},"userId":{"type":"string"}},"required":["id","expiresAt","token","createdAt","updatedAt","userId"]},"Account":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"accountId":{"type":"string"},"providerId":{"type":"string"},"userId":{"type":"string"},"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"idToken":{"type":"string"},"accessTokenExpiresAt":{"type":"string","format":"date-time"},"refreshTokenExpiresAt":{"type":"string","format":"date-time"},"scope":{"type":"string"},"password":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","accountId","providerId","userId","createdAt","updatedAt"]},"Verification":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"identifier":{"type":"string"},"value":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","identifier","value","expiresAt","createdAt","updatedAt"]},"OrderStatus":{"type":"string","enum":["pending","confirmed","processing","shipped","delivered","cancelled","refunded"]},"HealthReport":{"type":"object","required":["status","uptimeSeconds","checks"],"properties":{"status":{"type":"string","enum":["ok","degraded"]},"uptimeSeconds":{"type":"integer"},"checks":{"type":"object","required":["database"],"properties":{"database":{"type":"object","required":["status","latencyMs"],"properties":{"status":{"type":"string","enum":["up","down"]},"latencyMs":{"type":"integer"},"error":{"type":"string","nullable":true,"description":"Present only when the database check failed."}}}}}}}},"securitySchemes":{"apiKeyCookie":{"type":"apiKey","in":"cookie","name":"apiKeyCookie","description":"API Key authentication via cookie"},"bearerAuth":{"type":"http","scheme":"bearer","description":"Bearer token authentication"}}},"security":[{"apiKeyCookie":[],"bearerAuth":[]}],"servers":[{"url":"https://api.gifthamperforall.com"},{"url":"https://giftstory-src.vercel.app"}],"tags":[{"name":"Default","description":"Default endpoints that are included with Better Auth by default. These endpoints are not part of any plugin."}],"paths":{"/api/auth/sign-in/social":{"post":{"tags":["Authentication"],"description":"Sign in with a social provider","operationId":"socialSignIn","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"callbackURL":{"type":"string","description":"Callback URL to redirect to after the user has signed in"},"newUserCallbackURL":{"type":"string"},"errorCallbackURL":{"type":"string","description":"Callback URL to redirect to if an error happens"},"provider":{"anyOf":[{"type":"string","enum":["apple","atlassian","cloudflare","cognito","discord","facebook","figma","github","microsoft","google","huggingface","slack","spotify","twitch","twitter","dropbox","kick","linear","linkedin","gitlab","tiktok","reddit","roblox","salesforce","vk","zoom","notion","kakao","naver","line","paybin","paypal","polar","railway","vercel","wechat"]},{"type":"string"}]},"disableRedirect":{"type":"boolean","description":"Disable automatic redirection to the provider. Useful for handling the redirection yourself"},"idToken":{"type":"object","properties":{"token":{"type":"string","description":"ID token from the provider"},"nonce":{"type":"string","description":"Nonce used to generate the token"},"accessToken":{"type":"string","description":"Access token from the provider"},"refreshToken":{"type":"string","description":"Refresh token from the provider"},"expiresAt":{"type":"number","description":"Expiry date of the token"},"user":{"type":"object","properties":{"name":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"}}},"email":{"type":"string"}},"description":"The user object from the provider. Only available for some providers like Apple."}},"required":["token"]},"scopes":{"type":"array","items":{"type":"string"},"description":"Array of scopes to request from the provider. This will override the default scopes passed."},"requestSignUp":{"type":"boolean","description":"Explicitly request sign-up. Useful when disableImplicitSignUp is true for this provider"},"loginHint":{"type":"string","description":"The login hint to use for the authorization code request"},"additionalParams":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Extra query parameters to append to the provider authorization URL (e.g. Cognito identity_provider, Google hd)."},"additionalData":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["provider"]}}}},"responses":{"200":{"description":"Success - Returns session details (idToken branch) or an authorize URL (redirect branch)","content":{"application/json":{"schema":{"type":"object","description":"Returns session details when idToken is provided, or an authorize URL otherwise","properties":{"token":{"type":"string"},"user":{"type":"object","$ref":"#/components/schemas/User"},"url":{"type":"string"},"redirect":{"type":"boolean"}},"required":["redirect"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/callback/{id}":{"get":{"tags":["Authentication"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}},"post":{"tags":["Authentication"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"error":{"type":"string"},"device_id":{"type":"string"},"error_description":{"type":"string"},"state":{"type":"string"},"user":{"type":"string"},"iss":{"type":"string"}}}}}},"responses":{"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/get-session":{"get":{"tags":["Auth - Core & Sessions"],"description":"Get the current session","operationId":"getSession","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":["object","null"],"properties":{"session":{"$ref":"#/components/schemas/Session"},"user":{"$ref":"#/components/schemas/User"}},"required":["session","user"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}},"post":{"tags":["Auth - Core & Sessions"],"description":"Get the current session","operationId":"getSessionPost","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":["object","null"],"properties":{"session":{"$ref":"#/components/schemas/Session"},"user":{"$ref":"#/components/schemas/User"}},"required":["session","user"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/sign-out":{"post":{"tags":["Auth - Core & Sessions"],"description":"Sign out the current user","operationId":"signOut","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"callbackURL":{"type":"string","description":"The URL to redirect to after provider logout"},"disableRedirect":{"type":"boolean","description":"Return the provider logout URL without redirecting"},"state":{"type":"string","description":"State to pass to the provider logout endpoint"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"url":{"type":"string","description":"Provider logout URL when RP-initiated logout is available"},"redirect":{"type":"boolean","description":"Whether the client should redirect to the provider logout URL"}}}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/sign-up/email":{"post":{"tags":["Auth - Registration & Onboarding"],"description":"Sign up a user using email and password","operationId":"signUpWithEmailAndPassword","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The name of the user"},"email":{"type":"string","description":"The email of the user"},"password":{"type":"string","description":"The password of the user"},"image":{"type":"string","description":"The profile image URL of the user"},"callbackURL":{"type":"string","description":"The URL to use for email verification callback"},"rememberMe":{"type":"boolean","description":"If this is false, the session will not be remembered. Default is `true`."}},"required":["name","email","password"]}}}},"responses":{"200":{"description":"Successfully created user","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","nullable":true,"description":"Authentication token for the session"},"user":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the user"},"email":{"type":"string","format":"email","description":"The email address of the user"},"name":{"type":"string","description":"The name of the user"},"image":{"type":"string","format":"uri","nullable":true,"description":"The profile image URL of the user"},"emailVerified":{"type":"boolean","description":"Whether the email has been verified"},"createdAt":{"type":"string","format":"date-time","description":"When the user was created"},"updatedAt":{"type":"string","format":"date-time","description":"When the user was last updated"}},"required":["id","email","name","emailVerified","createdAt","updatedAt"]}},"required":["user"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"422":{"description":"Unprocessable Entity. User already exists or failed to create user.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/sign-in/email":{"post":{"tags":["Auth - Core & Sessions"],"description":"Sign in with email and password","operationId":"signInEmail","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Email of the user"},"password":{"type":"string","description":"Password of the user"},"callbackURL":{"type":"string","description":"Callback URL to use as a redirect for email verification"},"rememberMe":{"type":"boolean","description":"If this is false, the session will not be remembered. Default is `true`."}},"required":["email","password"]}}}},"responses":{"200":{"description":"Success - Returns either session details or redirect URL","content":{"application/json":{"schema":{"type":"object","description":"Session response when idToken is provided","properties":{"redirect":{"type":"boolean","enum":[false]},"token":{"type":"string","description":"Session token"},"url":{"type":"string","nullable":true},"user":{"type":"object","$ref":"#/components/schemas/User"}},"required":["redirect","token","user"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/reset-password":{"post":{"tags":["Auth - Account & Credentials"],"description":"Reset the password for a user","operationId":"resetPassword","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"newPassword":{"type":"string","description":"The new password to set"},"token":{"type":"string","description":"The token to reset the password"}},"required":["newPassword"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean"}}}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/verify-password":{"post":{"tags":["Authentication"],"description":"Verify the current user's password","operationId":"verifyPassword","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string","description":"The password to verify"}},"required":["password"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean"}}}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/verify-email":{"get":{"tags":["Auth - Registration & Onboarding"],"description":"Verify the email of the user","security":[{"bearerAuth":[]}],"parameters":[{"name":"token","in":"query","description":"The token to verify the email","required":true,"schema":{"type":"string"}},{"name":"callbackURL","in":"query","description":"The URL to redirect to after email verification","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","$ref":"#/components/schemas/User"},"status":{"type":"boolean","description":"Indicates if the email was verified successfully"}},"required":["user","status"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/send-verification-email":{"post":{"tags":["Auth - Registration & Onboarding"],"description":"Send a verification email to the user","operationId":"sendVerificationEmail","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"The email to send the verification email to","example":"user@example.com"},"callbackURL":{"type":"string","description":"The URL to use for email verification callback","example":"https://example.com/callback","nullable":true}},"required":["email"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","description":"Indicates if the email was sent successfully","example":true}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error message","example":"Verification email isn't enabled"}}}}}},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/change-email":{"post":{"tags":["Authentication"],"operationId":"changeEmail","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"newEmail":{"type":"string","description":"The new email address to set must be a valid email address"},"callbackURL":{"type":"string","description":"The URL to redirect to after email verification"}},"required":["newEmail"]}}}},"responses":{"200":{"description":"Email change request processed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","$ref":"#/components/schemas/User"},"status":{"type":"boolean","description":"Indicates if the request was successful"},"message":{"type":"string","enum":["Email updated","Verification email sent"],"description":"Status message of the email change process","nullable":true}},"required":["status"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/change-password":{"post":{"tags":["Auth - Account & Credentials"],"description":"Change the password of the user","operationId":"changePassword","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"newPassword":{"type":"string","description":"The new password to set"},"currentPassword":{"type":"string","description":"The current password is required"},"revokeOtherSessions":{"type":"boolean","description":"Must be a boolean value"}},"required":["newPassword","currentPassword"]}}}},"responses":{"200":{"description":"Password successfully changed","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","nullable":true,"description":"New session token if other sessions were revoked"},"user":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the user"},"email":{"type":"string","format":"email","description":"The email address of the user"},"name":{"type":"string","description":"The name of the user"},"image":{"type":"string","format":"uri","nullable":true,"description":"The profile image URL of the user"},"emailVerified":{"type":"boolean","description":"Whether the email has been verified"},"createdAt":{"type":"string","format":"date-time","description":"When the user was created"},"updatedAt":{"type":"string","format":"date-time","description":"When the user was last updated"}},"required":["id","email","name","emailVerified","createdAt","updatedAt"]}},"required":["user"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/update-session":{"post":{"tags":["Authentication"],"description":"Update the current session","operationId":"updateSession","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","propertyNames":{"type":"string","description":"Field name must be a string"},"additionalProperties":{}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"session":{"type":"object","$ref":"#/components/schemas/Session"}}}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/update-user":{"post":{"tags":["Auth - Account & Credentials"],"description":"Update the current user","operationId":"updateUser","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The name of the user"},"image":{"type":"string","description":"The image of the user","nullable":true}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","$ref":"#/components/schemas/User"}}}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/delete-user":{"post":{"tags":["Auth - Account & Credentials"],"description":"Delete the user","operationId":"deleteUser","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"callbackURL":{"type":"string","description":"The callback URL to redirect to after the user is deleted"},"password":{"type":"string","description":"The user's password. Required if session is not fresh"},"token":{"type":"string","description":"The deletion verification token"}}}}}},"responses":{"200":{"description":"User deletion processed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the operation was successful"},"message":{"type":"string","enum":["User deleted","Verification email sent"],"description":"Status message of the deletion process"}},"required":["success","message"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/request-password-reset":{"post":{"tags":["Authentication"],"description":"Send a password reset email to the user","operationId":"requestPasswordReset","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"The email address of the user to send a password reset email to"},"redirectTo":{"type":"string","description":"The URL to redirect the user to reset their password. If the token isn't valid or expired, it'll be redirected with a query parameter `?error=INVALID_TOKEN`. If the token is valid, it'll be redirected with a query parameter `?token=VALID_TOKEN"}},"required":["email"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean"},"message":{"type":"string"}}}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/reset-password/{token}":{"get":{"tags":["Auth - Account & Credentials"],"description":"Redirects the user to the callback URL with the token","operationId":"resetPasswordCallback","security":[{"bearerAuth":[]}],"parameters":[{"name":"token","in":"path","required":true,"description":"The token to reset the password","schema":{"type":"string"}},{"name":"callbackURL","in":"query","required":true,"description":"The URL to redirect the user to reset their password","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string"}}}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/list-sessions":{"get":{"tags":["Authentication"],"description":"List all active sessions for the user","operationId":"listUserSessions","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Session"}}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/revoke-session":{"post":{"tags":["Authentication"],"description":"Revoke a single session","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"The token to revoke"}},"required":["token"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","description":"Indicates if the session was revoked successfully"}},"required":["status"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/revoke-sessions":{"post":{"tags":["Authentication"],"description":"Revoke all sessions for the user","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","description":"Indicates if all sessions were revoked successfully"}},"required":["status"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/revoke-other-sessions":{"post":{"tags":["Authentication"],"description":"Revoke all other sessions for the user except the current one","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","description":"Indicates if all other sessions were revoked successfully"}},"required":["status"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/link-social":{"post":{"tags":["Authentication"],"description":"Link a social account to the user","operationId":"linkSocialAccount","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"callbackURL":{"type":"string","description":"The URL to redirect to after the user has signed in"},"provider":{"anyOf":[{"type":"string","enum":["apple","atlassian","cloudflare","cognito","discord","facebook","figma","github","microsoft","google","huggingface","slack","spotify","twitch","twitter","dropbox","kick","linear","linkedin","gitlab","tiktok","reddit","roblox","salesforce","vk","zoom","notion","kakao","naver","line","paybin","paypal","polar","railway","vercel","wechat"]},{"type":"string"}]},"idToken":{"type":"object","properties":{"token":{"type":"string"},"nonce":{"type":"string"},"accessToken":{"type":"string"},"refreshToken":{"type":"string"}},"required":["token"]},"requestSignUp":{"type":"boolean"},"scopes":{"type":"array","items":{"type":"string"},"description":"Additional scopes to request from the provider"},"errorCallbackURL":{"type":"string","description":"The URL to redirect to if there is an error during the link process"},"disableRedirect":{"type":"boolean","description":"Disable automatic redirection to the provider. Useful for handling the redirection yourself"},"loginHint":{"type":"string","description":"The login hint to use for the authorization code request"},"additionalParams":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"Extra query parameters to append to the provider authorization URL (e.g. Cognito identity_provider, Google hd)."},"additionalData":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["provider"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"The authorization URL to redirect the user to"},"redirect":{"type":"boolean","description":"Indicates if the user should be redirected to the authorization URL"},"status":{"type":"boolean"}},"required":["redirect"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/list-accounts":{"get":{"tags":["Authentication"],"description":"List all accounts linked to the user","operationId":"listUserAccounts","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"providerId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"accountId":{"type":"string"},"userId":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}}},"required":["id","providerId","createdAt","updatedAt","accountId","userId","scopes"]}}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/delete-user/callback":{"get":{"tags":["Auth - Account & Credentials"],"description":"Callback to complete user deletion with verification token","security":[{"bearerAuth":[]}],"parameters":[{"name":"token","in":"query","schema":{"type":"string","description":"The token to verify the deletion request"}},{"name":"callbackURL","in":"query","schema":{"type":"string","description":"The URL to redirect to after deletion"}}],"responses":{"200":{"description":"User successfully deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the deletion was successful"},"message":{"type":"string","enum":["User deleted"],"description":"Confirmation message"}},"required":["success","message"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/unlink-account":{"post":{"tags":["Authentication"],"description":"Unlink an account","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"accountId":{"type":"string","description":"The Better Auth account ID to unlink"}},"required":["accountId"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean"}}}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/refresh-token":{"post":{"tags":["Authentication"],"description":"Refresh the access token using a refresh token","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"accountId":{"type":"string","description":"The Better Auth account ID"},"userId":{"type":"string","description":"The user ID associated with the account"}},"required":["accountId"]},{"type":"object","properties":{"useAccountCookie":{"enum":[true],"description":"Select the current OAuth account from its signed cookie"},"userId":{"type":"string","description":"The user ID associated with the account"}},"required":["useAccountCookie"]}]}}}},"responses":{"200":{"description":"Access token refreshed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"tokenType":{"type":"string"},"idToken":{"type":"string"},"accessToken":{"type":"string"},"refreshToken":{"type":"string"},"accessTokenExpiresAt":{"type":"string","format":"date-time"},"refreshTokenExpiresAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid refresh token or provider configuration"},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/get-access-token":{"post":{"tags":["Authentication"],"description":"Get a valid access token, doing a refresh if needed","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"accountId":{"type":"string","description":"The Better Auth account ID"},"userId":{"type":"string","description":"The user ID associated with the account"}},"required":["accountId"]},{"type":"object","properties":{"useAccountCookie":{"enum":[true],"description":"Select the current OAuth account from its signed cookie"},"userId":{"type":"string","description":"The user ID associated with the account"}},"required":["useAccountCookie"]}]}}}},"responses":{"200":{"description":"A Valid access token","content":{"application/json":{"schema":{"type":"object","properties":{"tokenType":{"type":"string"},"idToken":{"type":"string"},"accessToken":{"type":"string"},"accessTokenExpiresAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid refresh token or provider configuration"},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/account-info":{"get":{"tags":["Authentication"],"description":"Get the account info provided by the provider","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","nullable":true},"image":{"type":"string"},"emailVerified":{"type":"boolean"}},"required":["emailVerified"]},"account":{"type":"object","properties":{"id":{"type":"string"},"providerId":{"type":"string"},"accountId":{"type":"string"}},"required":["id","providerId","accountId"],"additionalProperties":false},"data":{"type":"object","properties":{},"additionalProperties":true}},"required":["user","data","account"],"additionalProperties":false}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/ok":{"get":{"tags":["Authentication"],"description":"Check if the API is working","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"API is working","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","description":"Indicates if the API is working"}},"required":["ok"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/error":{"get":{"tags":["Authentication"],"description":"Displays an error page","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"text/html":{"schema":{"type":"string","description":"The HTML content of the error page"}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/email-otp/send-verification-otp":{"post":{"tags":["Authentication"],"description":"Send a verification OTP to an email","operationId":"sendEmailVerificationOTP","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Email address to send the OTP"},"type":{"type":"string","enum":["email-verification","sign-in","forget-password","change-email"],"description":"Type of the OTP"}},"required":["email","type"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/email-otp/check-verification-otp":{"post":{"tags":["Authentication"],"description":"Verify an email with an OTP","operationId":"verifyEmailWithOTP","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Email address the OTP was sent to"},"type":{"type":"string","enum":["email-verification","sign-in","forget-password","change-email"],"description":"Type of the OTP"},"otp":{"type":"string","description":"OTP to verify"}},"required":["email","type","otp"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/email-otp/verify-email":{"post":{"tags":["Auth - Registration & Onboarding"],"description":"Verify email with OTP","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Email address to verify"},"otp":{"type":"string","description":"OTP to verify"}},"required":["email","otp"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"boolean","description":"Indicates if the verification was successful","enum":[true]},"token":{"type":"string","nullable":true,"description":"Session token if autoSignInAfterVerification is enabled, otherwise null"},"user":{"$ref":"#/components/schemas/User"}},"required":["status","token","user"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/sign-in/email-otp":{"post":{"tags":["Auth - Core & Sessions"],"description":"Sign in with email and OTP","operationId":"signInWithEmailOTP","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Email address to sign in"},"otp":{"type":"string","description":"OTP sent to the email"},"name":{"type":"string","description":"User display name. Only used if the user is registering for the first time. Eg: \"my-name\""},"image":{"type":"string","description":"User profile image URL. Only used if the user is registering for the first time."}},"required":["email","otp"],"additionalProperties":{},"propertyNames":{"type":"string"}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"Session token for the authenticated session"},"user":{"$ref":"#/components/schemas/User"}},"required":["token","user"]}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/email-otp/request-password-reset":{"post":{"tags":["Authentication"],"description":"Request password reset with email and OTP","operationId":"requestPasswordResetWithEmailOTP","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Email address to send the OTP"}},"required":["email"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the OTP was sent successfully"}}}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/forget-password/email-otp":{"post":{"tags":["Auth - Account & Credentials"],"description":"Deprecated: Use /email-otp/request-password-reset instead.","operationId":"forgetPasswordWithEmailOTP","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Email address to send the OTP"}},"required":["email"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the OTP was sent successfully"}}}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/email-otp/reset-password":{"post":{"tags":["Auth - Account & Credentials"],"description":"Reset password with email and OTP","operationId":"resetPasswordWithEmailOTP","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"Email address to reset the password"},"otp":{"type":"string","description":"OTP sent to the email"},"password":{"type":"string","description":"New password"}},"required":["email","otp","password"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/email-otp/request-email-change":{"post":{"tags":["Authentication"],"description":"Request email change with verification OTP sent to the new email","operationId":"requestEmailChangeWithEmailOTP","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"newEmail":{"type":"string","description":"New email address to send the OTP"},"otp":{"type":"string"}},"required":["newEmail"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/auth/email-otp/change-email":{"post":{"tags":["Authentication"],"description":"Verify new email with OTP and change the email if verification is successful","operationId":"changeEmailWithEmailOTP","security":[{"bearerAuth":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"newEmail":{"type":"string","description":"New email address to verify and change to"},"otp":{"type":"string","description":"OTP sent to the new email"}},"required":["newEmail","otp"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"400":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Bad Request. Usually due to missing parameters, or invalid parameters."},"401":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}},"description":"Unauthorized. Due to missing or invalid authentication."},"403":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Forbidden. You do not have permission to access this resource or to perform this action."},"404":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Not Found. The requested resource was not found."},"429":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Too Many Requests. You have exceeded the rate limit. Try again later."},"500":{"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}},"description":"Internal Server Error. This is a problem with the server that you cannot fix."}}}},"/api/products":{"get":{"tags":["Products"],"summary":"List products","description":"Returns paginated products with stock availability labels. Supports filtering by category and search.","operationId":"listProducts","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":10},"description":"Items per page"},{"name":"categoryId","in":"query","schema":{"type":"string","format":"uuid"},"description":"Filter by category"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Search by name or description"}],"responses":{"200":{"description":"Paginated list of products."}}},"post":{"tags":["Products"],"summary":"Create product","description":"Creates a new product. Admin only.","operationId":"createProduct","security":[{"apiKeyCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","name","price","stockQuantity","isActive"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"price":{"type":"string"},"stockQuantity":{"type":"integer"},"isActive":{"type":"boolean"},"availabilityOverride":{"type":"string","enum":["inherit","available","sold_out"]},"description":{"type":"string","nullable":true},"shortDescription":{"type":"string","nullable":true},"categoryId":{"type":"string","format":"uuid","nullable":true},"sku":{"type":"string","nullable":true},"isFeatured":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Product created."},"400":{"description":"Validation failed."}}}},"/api/products/bulk":{"post":{"tags":["Products"],"summary":"Bulk create products","description":"Creates up to 100 products for staff. Each row is validated independently; the response includes its input index and product or error. Product media is uploaded separately through the product media endpoints.","operationId":"bulkCreateProducts","security":[{"apiKeyCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["products"],"properties":{"products":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object"}}}}}}},"responses":{"200":{"description":"Per-row product creation results."},"400":{"description":"The request must contain between 1 and 100 products."},"401":{"description":"Staff authentication required."}}}},"/api/products/{id}":{"get":{"tags":["Products"],"summary":"Get product","description":"Returns product details and normalized availability (in_stock, low_stock, sold_out). Stock counts remain available for current cart compatibility.","operationId":"getProduct","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Product details."},"404":{"description":"Product not found."}}},"put":{"tags":["Products"],"summary":"Update product","description":"Updates an existing product. Admin only.","operationId":"updateProduct","security":[{"apiKeyCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"price":{"type":"string"},"stockQuantity":{"type":"integer"},"isActive":{"type":"boolean"},"availabilityOverride":{"type":"string","enum":["inherit","available","sold_out"]},"description":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"isFeatured":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Product updated."},"404":{"description":"Product not found."}}},"delete":{"tags":["Products"],"summary":"Delete product","description":"Deletes a product. Admin only.","operationId":"deleteProduct","security":[{"apiKeyCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Product deleted."},"404":{"description":"Product not found."}}}},"/api/categories":{"get":{"tags":["Categories"],"summary":"List categories","description":"Returns paginated categories, including their direct-product sold-out setting.","operationId":"listCategories","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":10},"description":"Items per page"}],"responses":{"200":{"description":"Paginated list of categories."}}},"post":{"tags":["Categories"],"summary":"Create category","description":"Creates a new category. Admin only.","operationId":"createCategory","security":[{"apiKeyCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","name"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"parentId":{"type":"string","format":"uuid","nullable":true},"isActive":{"type":"boolean"},"soldOut":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Category created."},"400":{"description":"Validation failed."}}}},"/api/categories/{id}":{"get":{"tags":["Categories"],"summary":"Get category","description":"Returns details of a specific category by ID.","operationId":"getCategory","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Category details."},"404":{"description":"Category not found."}}},"put":{"tags":["Categories"],"summary":"Update category","description":"Updates an existing category. Admin only.","operationId":"updateCategory","security":[{"apiKeyCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"soldOut":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Category updated."},"404":{"description":"Category not found."}}},"delete":{"tags":["Categories"],"summary":"Delete category","description":"Deletes a category. Admin only.","operationId":"deleteCategory","security":[{"apiKeyCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Category deleted."},"404":{"description":"Category not found."}}}},"/api/orders":{"post":{"tags":["Orders"],"summary":"Create order","description":"Creates an order from product and variant identifiers. Unit prices, line totals, shipping, tax and the grand total are computed on the server; the request body cannot set them.","operationId":"createOrder","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customerEmail","customerName","paymentMethod","currencyCode","items"],"properties":{"customerEmail":{"type":"string","format":"email"},"customerName":{"type":"string"},"paymentMethod":{"type":"string"},"currencyCode":{"type":"string","minLength":3,"maxLength":3,"example":"USD"},"shippingMethodCode":{"type":"string","nullable":true},"items":{"type":"array","minItems":1,"items":{"type":"object","required":["productId","quantity"],"properties":{"productId":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid","nullable":true},"quantity":{"type":"integer","minimum":1}}}}}}}}},"responses":{"201":{"description":"Order created with server-computed totals."},"400":{"description":"Validation failed, or a product is unavailable or out of stock."}}},"get":{"tags":["Orders"],"summary":"List orders","description":"Returns recent orders for staff review. Admin only.","operationId":"listOrders","security":[{"apiKeyCookie":[]}],"parameters":[{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/OrderStatus"},"description":"Filter by order status"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200},"description":"Maximum orders to return"}],"responses":{"200":{"description":"Orders with items, status history and shipment."},"401":{"description":"No valid session."},"403":{"description":"Caller is not an admin."}}}},"/api/orders/{id}":{"get":{"tags":["Orders"],"summary":"Get order","description":"Returns one order with its items, status history and shipment details.","operationId":"getOrder","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Order details."},"404":{"description":"Order not found."}}}},"/api/orders/{id}/receipt.pdf":{"get":{"tags":["Orders"],"summary":"Download paid order receipt","description":"Downloads a PDF receipt after capture. Requires order owner session, valid guest-order token, or staff session.","operationId":"downloadOrderReceipt","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"PDF receipt.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Order not found or caller is not authorized."},"409":{"description":"Order payment has not been captured."}}}},"/api/orders/{id}/receipt/resend":{"post":{"tags":["Orders"],"summary":"Resend paid receipt email","description":"Sends the paid PDF receipt to the saved order email. Admin only.","operationId":"resendOrderReceipt","security":[{"apiKeyCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Receipt queued for email."},"401":{"description":"No valid session."},"403":{"description":"Caller is not an admin."},"409":{"description":"Order payment has not been captured."}}}},"/api/orders/{id}/reservation/release":{"post":{"tags":["Orders"],"summary":"Release order stock reservation","description":"Restores a reserved order quantity exactly once and cancels an open order. Admin only.","operationId":"releaseOrderReservation","security":[{"apiKeyCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":2000}}}}}},"responses":{"200":{"description":"Reservation release result."},"401":{"description":"No valid session."},"403":{"description":"Caller is not an admin."},"404":{"description":"Order not found."}}}},"/api/orders/{id}/payment-review":{"get":{"tags":["Orders"],"summary":"Read payment review audit","description":"Returns staff-only resolution history for an order payment review.","operationId":"listOrderPaymentReviews","security":[{"apiKeyCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Payment review audit entries."},"401":{"description":"No valid session."},"403":{"description":"Caller is not an admin."},"404":{"description":"Order not found."}}},"post":{"tags":["Orders"],"summary":"Resolve payment review","description":"Staff may re-reserve and fulfil a late capture when stock permits, or record a manual Razorpay refund reference. No refund is initiated by this API. Admin only.","operationId":"resolveOrderPaymentReview","security":[{"apiKeyCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["decision","note"],"properties":{"decision":{"type":"string","enum":["fulfill","refund_recorded"]},"note":{"type":"string","minLength":1,"maxLength":2000},"refundReference":{"type":"string","maxLength":200}}}}}},"responses":{"200":{"description":"Updated order and payment review status."},"401":{"description":"No valid session."},"403":{"description":"Caller is not an admin."},"409":{"description":"Review cannot be resolved or inventory is unavailable."}}}},"/api/orders/{id}/status":{"put":{"tags":["Orders"],"summary":"Update order status","description":"Moves an order to a new status and records the transition. Admin only. Shipping requires a tracking number, and illegal transitions are rejected.","operationId":"updateOrderStatus","security":[{"apiKeyCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"$ref":"#/components/schemas/OrderStatus"},"note":{"type":"string","nullable":true},"carrier":{"type":"string","nullable":true},"trackingNumber":{"type":"string","nullable":true},"trackingUrl":{"type":"string","format":"uri","nullable":true}}}}}},"responses":{"200":{"description":"Status updated."},"400":{"description":"Illegal status transition, or shipping without a tracking number."},"401":{"description":"No valid session."},"403":{"description":"Caller is not an admin."},"404":{"description":"Order not found."}}}},"/api/payments/razorpay/order":{"post":{"tags":["Payments"],"summary":"Create Razorpay checkout attempt","description":"Creates a distinct Razorpay order for an existing unpaid Gift Story order using its server-stored amount and currency. Signed-in owners, staff, or a guest with the order-bound token may call it.","operationId":"createRazorpayOrder","parameters":[{"name":"X-Guest-Order-Token","in":"header","required":false,"schema":{"type":"string"},"description":"Required for a guest order; issued in the order creation response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderId"],"properties":{"orderId":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Razorpay order id, public key id, server-stored amount and currency."},"400":{"description":"Order is not payable or its inventory hold has expired."},"404":{"description":"Order not found or caller is not authorized."}}}},"/api/payments/razorpay/verify":{"post":{"tags":["Payments"],"summary":"Verify Razorpay payment signature","description":"Verifies the callback HMAC and checks Razorpay payment status, provider order, amount, and currency. Only captured payments are marked paid; authorization remains unpaid.","operationId":"verifyRazorpayPayment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["orderId","razorpayOrderId","razorpayPaymentId","razorpaySignature"],"properties":{"orderId":{"type":"string","format":"uuid"},"razorpayOrderId":{"type":"string"},"razorpayPaymentId":{"type":"string"},"razorpaySignature":{"type":"string"}}}}}},"responses":{"200":{"description":"Callback reconciled. Response includes success, captured, and paymentStatus."},"400":{"description":"Invalid payment signature or malformed payload."}}}},"/api/payments/razorpay/webhook":{"post":{"tags":["Payments"],"summary":"Razorpay webhook receiver","description":"Processes captured, authorized, failed, and refund webhooks idempotently using raw body HMAC verification and retryable event state.","operationId":"handleRazorpayWebhook","responses":{"200":{"description":"Webhook processed or ignored if duplicate."},"400":{"description":"Invalid webhook signature or payload."}}}},"/api/customers/me":{"get":{"tags":["Customers"],"summary":"Get customer profile","description":"Returns the customer profile attached to the signed-in session.","operationId":"getCustomerProfile","security":[{"apiKeyCookie":[]}],"responses":{"200":{"description":"Customer profile."},"401":{"description":"No valid session."},"404":{"description":"Customer profile not found."}}}},"/api/customers/addresses":{"get":{"tags":["Customers"],"summary":"List addresses","description":"Returns the saved addresses of the signed-in customer.","operationId":"listCustomerAddresses","security":[{"apiKeyCookie":[]}],"responses":{"200":{"description":"Saved addresses."},"401":{"description":"No valid session."}}},"post":{"tags":["Customers"],"summary":"Create address","description":"Saves an address for the signed-in customer. The customer is taken from the session.","operationId":"createCustomerAddress","security":[{"apiKeyCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["label","fullName","addressLine1","city","postalCode","countryCode","isDefault"],"properties":{"label":{"type":"string","enum":["shipping","billing","both"]},"fullName":{"type":"string"},"phone":{"type":"string","nullable":true},"addressLine1":{"type":"string"},"addressLine2":{"type":"string","nullable":true},"city":{"type":"string"},"state":{"type":"string","nullable":true},"postalCode":{"type":"string"},"countryCode":{"type":"string","minLength":2,"maxLength":2},"isDefault":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Address saved."},"400":{"description":"Validation failed."},"401":{"description":"No valid session."}}}},"/api/customers/addresses/{id}":{"put":{"tags":["Customers"],"summary":"Update address","description":"Updates one of the signed-in customer own addresses.","operationId":"updateCustomerAddress","security":[{"apiKeyCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Address updated."},"400":{"description":"Validation failed."},"401":{"description":"No valid session."},"404":{"description":"Address not found."}}},"delete":{"tags":["Customers"],"summary":"Delete address","description":"Deletes one of the signed-in customer own addresses.","operationId":"deleteCustomerAddress","security":[{"apiKeyCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Address deleted."},"401":{"description":"No valid session."},"404":{"description":"Address not found."}}}},"/api/support-requests":{"post":{"tags":["Support"],"summary":"Submit support request","description":"Opens a complaint, feedback or contact request. Available to signed-in customers and visitors.","operationId":"createSupportRequest","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["requestType","name","email","message"],"properties":{"requestType":{"type":"string","enum":["complaint","feedback","contact"]},"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string","nullable":true},"subject":{"type":"string","nullable":true},"message":{"type":"string"},"orderId":{"type":"string","format":"uuid","nullable":true}}}}}},"responses":{"201":{"description":"Support request created."},"400":{"description":"Validation failed."}}},"get":{"tags":["Support"],"summary":"List support requests","description":"Returns the staff support queue, newest first. Admin only.","operationId":"listSupportRequests","security":[{"apiKeyCookie":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["new","in_review","waiting_for_customer","resolved","closed"]},"description":"Filter by status"}],"responses":{"200":{"description":"Support queue."},"401":{"description":"No valid session."},"403":{"description":"Caller is not an admin."}}}},"/api/support-requests/{id}":{"get":{"tags":["Support"],"summary":"Get support request","description":"Returns one support request together with its internal notes. Admin only.","operationId":"getSupportRequest","security":[{"apiKeyCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Support request with internal notes."},"401":{"description":"No valid session."},"403":{"description":"Caller is not an admin."},"404":{"description":"Support request not found."}}}},"/api/support-requests/{id}/status":{"patch":{"tags":["Support"],"summary":"Update support request status","description":"Moves a support request through the staff workflow. Admin only.","operationId":"updateSupportRequestStatus","security":[{"apiKeyCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["new","in_review","waiting_for_customer","resolved","closed"]}}}}}},"responses":{"204":{"description":"Status updated."},"400":{"description":"Invalid status."},"401":{"description":"No valid session."},"403":{"description":"Caller is not an admin."},"404":{"description":"Support request not found."}}}},"/api/support-requests/{id}/internal-notes":{"post":{"tags":["Support"],"summary":"Add internal note","description":"Adds a staff-only note. Notes are never exposed to customers and the author comes from the session. Admin only.","operationId":"addSupportRequestInternalNote","security":[{"apiKeyCookie":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string"}}}}}},"responses":{"201":{"description":"Internal note added."},"400":{"description":"Validation failed."},"401":{"description":"No valid session."},"403":{"description":"Caller is not an admin."},"404":{"description":"Support request not found."}}}},"/api/health":{"get":{"tags":["Operations"],"summary":"Health check","description":"Reports process and database state together so one uptime monitor covers both. The response body distinguishes which part failed, which is why a liveness/readiness split is not used: a Vercel function has no supervisor that would restart it, and a monitor on process state alone would report healthy while checkout is broken. Returns 503 when a dependency is unavailable. No credentials appear in the body.","operationId":"getHealth","responses":{"200":{"description":"Process and database are healthy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthReport"}}}},"503":{"description":"A dependency is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthReport"}}}}}}},"/api/me":{"get":{"tags":["Authentication"],"summary":"Get the signed-in user","description":"Returns the current user profile for the session cookie. Returns 401 when signed out.","operationId":"getCurrentUser","security":[{"apiKeyCookie":[]}],"responses":{"200":{"description":"Current user profile."},"401":{"description":"No valid session."}}}},"/api/admin/access":{"get":{"tags":["Administration"],"summary":"Check admin access","description":"Protected example endpoint. Requires a signed-in user with the server-managed admin role.","operationId":"checkAdminAccess","security":[{"apiKeyCookie":[]}],"responses":{"200":{"description":"Caller has admin access."},"401":{"description":"No valid session."},"403":{"description":"Caller is not an admin."}}}},"/api/admin/email/test":{"post":{"tags":["Administration"],"summary":"Send a test email","description":"Sends a plain, branded delivery test through the currently configured email provider. Admin session required; exactly one recipient is accepted.","operationId":"sendAdminTestEmail","security":[{"apiKeyCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to","subject","description"],"properties":{"to":{"type":"string","format":"email","maxLength":254},"subject":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","minLength":1,"maxLength":5000}}}}}},"responses":{"200":{"description":"The provider accepted the test email."},"400":{"description":"Request validation failed."},"401":{"description":"No valid session."},"403":{"description":"Caller is not an admin."},"502":{"description":"The configured email provider rejected or could not deliver the message."}}}},"/":{"get":{"tags":["Documentation"],"summary":"API landing page","description":"HTML entry point linking to the API reference.","operationId":"getApiLandingPage","responses":{"200":{"description":"Documentation landing page."}}}},"/docs":{"get":{"tags":["Documentation"],"summary":"API documentation index","description":"Navigation page for backend documentation.","operationId":"getApiDocumentationIndex","responses":{"200":{"description":"Documentation navigation page."}}}},"/docs/swagger":{"get":{"tags":["Documentation"],"summary":"Swagger UI","description":"Interactive reference for documented backend endpoints.","operationId":"getSwaggerUi","responses":{"200":{"description":"Swagger UI page."}}}},"/docs/openapi.json":{"get":{"tags":["Documentation"],"summary":"OpenAPI specification","description":"Machine-readable API specification used by Swagger UI.","operationId":"getOpenApiDocument","responses":{"200":{"description":"OpenAPI JSON document."}}}}}}