{ "openapi": "3.1.0", "info": { "title": "XAiPro API", "version": "0.1.0", "description": "Public API for the XAiPro Google AI Pro (Gemini Pro) subscription: pricing, OTP authentication, checkout, order status and health. Authenticated endpoints accept a bearer access token (see /auth.md).", "license": { "name": "Proprietary", "url": "https://xaipro.ir/terms" } }, "servers": [ { "url": "https://xaipro.ir" } ], "tags": [ { "name": "meta", "description": "Service metadata" }, { "name": "auth", "description": "OTP authentication" }, { "name": "commerce", "description": "Pricing, checkout and payments" }, { "name": "agent", "description": "Agent-only endpoints" } ], "x-service-info": { "categories": [ "ai-subscription", "e-commerce", "agent-tools" ], "support": { "url": "https://t.me/xaipro_ir", "type": "telegram" }, "documentation": "https://xaipro.ir/faq", "terms": "https://xaipro.ir/terms" }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "access_token from POST /api/auth/verify-otp" }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "xaipro_session" } }, "schemas": { "Error": { "type": "object", "required": [ "success", "message" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "Plans": { "type": "object", "required": [ "currency", "discountedPrice", "durationMonths" ], "properties": { "currency": { "type": "string", "example": "TOMAN" }, "originalPrice": { "type": "integer" }, "discountedPrice": { "type": "integer" }, "durationMonths": { "type": "integer", "example": 18 }, "features": { "type": "array", "items": { "type": "string" } }, "purchaseUrl": { "type": "string", "format": "uri" } } }, "SubscriptionStatus": { "type": "object", "properties": { "loggedIn": { "type": "boolean" }, "hasActiveSubscription": { "type": "boolean" }, "user": { "type": "object", "nullable": true, "properties": { "name": { "type": "string", "nullable": true } } } } }, "PaymentRequirements": { "type": "object", "description": "x402 payment requirements returned with HTTP 402 (in the payment-required header and mirrored in the body)", "properties": { "x402Version": { "type": "integer", "example": 2 }, "error": { "type": "string", "example": "Payment required" }, "resource": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "mimeType": { "type": "string" } } }, "accepts": { "type": "array", "items": { "type": "object" } } } } } }, "paths": { "/api/health": { "get": { "tags": [ "meta" ], "operationId": "getHealth", "summary": "Service health status", "security": [], "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "service": { "type": "string", "example": "xaipro" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/plans": { "get": { "tags": [ "commerce" ], "operationId": "getPlans", "summary": "Current plan pricing and included features", "security": [], "responses": { "200": { "description": "Current pricing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plans" } } } } } } }, "/api/auth/send-otp": { "post": { "tags": [ "auth" ], "operationId": "sendOtp", "summary": "Request a one-time login code (agent registration step 1)", "description": "Registration method for agents: restricted to customers with a successful purchase.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone" ], "properties": { "phone": { "type": "string" } } } } } }, "responses": { "200": { "description": "OTP dispatched" }, "403": { "description": "No successful purchase for this phone number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/auth/verify-otp": { "post": { "tags": [ "auth" ], "operationId": "verifyOtp", "summary": "Exchange OTP for a bearer access token (OTP grant)", "description": "Grant type urn:ietf:params:oauth:grant-type:otp. Returns access_token / token_type=bearer / expires_in.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "phone", "code" ], "properties": { "phone": { "type": "string" }, "code": { "type": "string", "minLength": 6, "maxLength": 6 } } } } } }, "responses": { "200": { "description": "Credential issued", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "access_token": { "type": "string" }, "token_type": { "type": "string", "example": "bearer" }, "expires_in": { "type": "integer", "example": 2592000 } } } } } }, "400": { "description": "Invalid phone number or code" } } } }, "/api/auth/logout": { "post": { "tags": [ "auth" ], "operationId": "logout", "summary": "Revoke the current session credential", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Session revoked" } } } }, "/api/user/status": { "get": { "tags": [ "commerce" ], "operationId": "getSubscriptionStatus", "summary": "Whether the authenticated customer has an active subscription", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Status (loggedIn=false when unauthenticated)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionStatus" } } } } } } }, "/api/payment/create": { "post": { "tags": [ "commerce" ], "operationId": "createCheckout", "summary": "Create an order and start the hosted card checkout", "security": [], "x-payment-info": { "intent": "charge", "method": "card", "amount": 19900000, "currency": "IRR", "description": "18-month Google AI Pro subscription; the amount reaches the payment gateway in Rial (site prices are Toman). A ready-account order (productOption=READY_ACCOUNT) is charged at readyAccountPrice instead." }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "phone", "quantity" ], "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1 }, "returnTo": { "type": "string", "format": "uri" }, "productOption": { "type": "string", "enum": [ "ACTIVATION_LINK", "READY_ACCOUNT" ], "default": "ACTIVATION_LINK", "description": "ACTIVATION_LINK: an activation link for the buyer's own account. READY_ACCOUNT: a ready Gmail + password (US/EU region) from a separate pool, priced at readyAccountPrice." } } } } } }, "responses": { "200": { "description": "Hosted payment URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "paymentUrl": { "type": "string", "format": "uri" }, "orderId": { "type": "string" }, "needsVpnWarning": { "type": "boolean", "description": "True when the visitor's IP country (CF-IPCountry) is not IR: the shop UI shows a 2-second 'turn off your VPN' notice (pay button keeps spinning) before redirecting to the gateway." } } } } } }, "400": { "description": "Validation error" } } } }, "/api/payment/verify": { "get": { "tags": [ "commerce" ], "operationId": "verifyPaymentLegacy", "summary": "Deprecated legacy verification (redirects to the result page)", "deprecated": true, "security": [], "responses": { "302": { "description": "Redirect to /payment/result" } } } }, "/api/premium/brief": { "get": { "tags": [ "agent" ], "operationId": "getPremiumBrief", "summary": "Paid product brief for agents (x402 micropayment)", "description": "Returns HTTP 402 with x402 payment requirements unless the request carries a settled X-PAYMENT header.", "security": [], "x-payment-info": { "intent": "charge", "method": "tempo", "amount": 0.01, "currency": "USD", "description": "Micropayment settled via x402 (exact scheme, USDC on Base Sepolia by default)." }, "responses": { "200": { "description": "The paid brief", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "402": { "description": "x402 payment required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequirements" } }, "application/json;schema=payment-required": { "schema": { "$ref": "#/components/schemas/PaymentRequirements" } } } } } } }, "/mcp": { "post": { "tags": [ "agent" ], "operationId": "mcp", "summary": "Model Context Protocol endpoint (Streamable HTTP, JSON-RPC 2.0)", "security": [], "responses": { "200": { "description": "JSON-RPC response" }, "202": { "description": "Notification accepted" } } } } } }