{"openapi":"3.0.0","info":{"title":"FutureSense AI Central Hub API","version":"2.0.0","description":"Unified API for AI-powered business automation across 8+ apps including:\n- AI Content Marketing (react-blog)\n- AI Appointment Booking (booker)\n- AI Invoicing & Accounting (invoicer)\n- AI Voice Agent (ai-caller)\n- And more...\n\nThis API provides centralized authentication, payments, OAuth integrations,\nand AI services (text + image generation) for all FutureSense applications.\n\n**Key Features:**\n- Multi-tenant authentication\n- Stripe subscription management\n- OAuth integrations (Google, Microsoft, QuickBooks, etc.)\n- AI text generation (4 providers with failover)\n- AI image generation (DALL-E 3)\n- CRM services (email, SMS, calls)\n- Cross-app data sharing\n\n**For AI Agents:**\nThis API is designed to be consumed by AI agents and LLM-powered applications.\nAll endpoints return structured JSON and follow RESTful conventions.\n\n## 🔐 Authentication (Swagger UI)\n1. Click the **Authorize** button at the top right\n2. Retrieve a Firebase ID token from your logged-in session\n3. Paste the token into the `bearerAuth` field\n4. Authorize to enable \"Try it out\" for protected endpoints","contact":{"name":"FutureSense AI Support","email":"support@futuresenseai.com","url":"https://futuresenseai.com"},"license":{"name":"Proprietary","url":"https://futuresenseai.com/terms"},"termsOfService":"https://futuresenseai.com/terms","x-logo":{"url":"https://futuresenseai.com/logo.png","altText":"FutureSense AI"},"x-ai-friendly":true,"x-ai-capabilities":["text-generation","image-generation","subscription-management","oauth-integrations","email-sms-calling"]},"servers":[{"url":"https://us-central1-paymentgateway-ab783.cloudfunctions.net/api","description":"Production server"},{"url":"http://localhost:5001/paymentgateway-ab783/us-central1/api","description":"Local development server"}],"x-rate-limits":{"free":{"requestsPerMinute":10,"requestsPerDay":100,"requestsPerMonth":1000,"description":"Free tier - suitable for testing and small projects"},"starter":{"requestsPerMinute":30,"requestsPerDay":1000,"requestsPerMonth":10000,"description":"Starter tier - for growing applications"},"professional":{"requestsPerMinute":60,"requestsPerDay":10000,"requestsPerMonth":100000,"description":"Professional tier - for production applications"},"business":{"requestsPerMinute":120,"requestsPerDay":50000,"requestsPerMonth":500000,"description":"Business tier - for high-volume applications"},"enterprise":{"requestsPerMinute":-1,"requestsPerDay":-1,"requestsPerMonth":-1,"description":"Enterprise tier - unlimited requests with dedicated support"}},"x-pricing":{"url":"https://futuresenseai.com/pricing","freeTier":true,"trialAvailable":false,"pricingModel":"subscription","currency":"USD","tiers":{"free":{"price":0,"billingPeriod":"monthly"},"starter":{"price":29,"billingPeriod":"monthly"},"professional":{"price":99,"billingPeriod":"monthly"},"business":{"price":299,"billingPeriod":"monthly"},"enterprise":{"price":"custom","billingPeriod":"yearly"}}},"x-workflows":[{"name":"Subscribe to a Plan","description":"Complete workflow for upgrading a user to a paid plan","steps":[{"step":1,"description":"Get available plans for an app","endpoint":"GET /payments/plans?appId={appId}","requiredAuth":false},{"step":2,"description":"Create Stripe checkout session","endpoint":"POST /subscriptions/create-checkout","requiredAuth":true,"body":{"appId":"react-blog","planId":"professional","successUrl":"...","cancelUrl":"..."}},{"step":3,"description":"Redirect user to Stripe Checkout","action":"Redirect user to response.url from step 2"},{"step":4,"description":"Verify subscription status after payment","endpoint":"GET /subscriptions/status/{appId}","requiredAuth":true}]},{"name":"Generate AI Content","description":"Workflow for generating text content using AI","steps":[{"step":1,"description":"Check user subscription and quota","endpoint":"GET /subscriptions/status/{appId}","requiredAuth":true},{"step":2,"description":"Generate text content","endpoint":"POST /ai/generate-text","requiredAuth":true,"body":{"prompt":"Write a blog post about...","maxTokens":2000,"temperature":0.7}},{"step":3,"description":"Check remaining AI credits","endpoint":"GET /ai/usage/{appId}","requiredAuth":true}]},{"name":"Connect OAuth Provider","description":"Workflow for connecting external services via OAuth","steps":[{"step":1,"description":"Initiate OAuth flow for Google","endpoint":"POST /integrations/oauth/google/initiate","requiredAuth":true,"body":{"appId":"react-blog","scopes":["email","profile","calendar"]}},{"step":2,"description":"Redirect user to OAuth provider","action":"Redirect user to response.authUrl from step 1"},{"step":3,"description":"User authorizes and returns with code","action":"OAuth provider redirects to callback URL with authorization code"},{"step":4,"description":"Verify connection status","endpoint":"GET /integrations/oauth/google/status","requiredAuth":true}]},{"name":"Send CRM Campaign","description":"Workflow for sending email/SMS campaigns","steps":[{"step":1,"description":"Check CRM quota","endpoint":"GET /crm/quotas","requiredAuth":true},{"step":2,"description":"Get contact list","endpoint":"GET /crm/contacts?limit=100","requiredAuth":true},{"step":3,"description":"Send bulk email campaign","endpoint":"POST /crm/send-bulk-email","requiredAuth":true,"body":{"recipients":["..."],"subject":"...","htmlBody":"...","templateId":"newsletter"}},{"step":4,"description":"Track campaign analytics","endpoint":"GET /crm/analytics?campaignId={id}","requiredAuth":true}]},{"name":"Create Invoice via API","description":"Workflow for creating invoices programmatically (Invoicer app)","steps":[{"step":1,"description":"Obtain API key from user dashboard","endpoint":"GET /api-keys","requiredAuth":true,"note":"Requires Integration or Business tier subscription"},{"step":2,"description":"Create external invoice","endpoint":"POST https://us-central1-invoicerfuturesenseai.cloudfunctions.net/createExternalInvoice","requiredAuth":false,"headers":{"X-API-Key":"your_api_key"},"body":{"customerName":"Acme Corp","customerEmail":"billing@acme.com","items":[{"description":"Consulting Services","quantity":10,"unitPrice":150}],"taxRate":13,"dueDate":"2025-12-31"}},{"step":3,"description":"Retrieve created invoices","endpoint":"GET https://us-central1-invoicerfuturesenseai.cloudfunctions.net/getExternalInvoices","requiredAuth":false,"headers":{"X-API-Key":"your_api_key"},"query":{"limit":50,"status":"draft"}}]}],"x-federated-apps":{"invoicer":{"appId":"invoicer","appName":"Invoice Generator Pro","description":"AI-powered invoicing and quotation system with QuickBooks integration","apiBaseUrl":"https://us-central1-invoicerfuturesenseai.cloudfunctions.net","openapiSpec":"https://us-central1-invoicerfuturesenseai.cloudfunctions.net/api/api-docs.json","capabilities":["create_invoice","generate_pdf","recurring_billing","payment_tracking","quickbooks_export","quotation_management"],"endpoints":[{"path":"/createExternalInvoice","method":"POST","description":"Create a new invoice via API","authentication":"API Key (X-API-Key header)","requiredPermissions":["write:invoices"],"requiredTier":"integration"},{"path":"/getExternalInvoices","method":"GET","description":"Retrieve invoices created via API","authentication":"API Key (X-API-Key header)","requiredPermissions":["read:invoices"]},{"path":"/createExternalQuotation","method":"POST","description":"Create a new quotation via API","authentication":"API Key (X-API-Key header)","requiredPermissions":["write:quotations"],"requiredTier":"integration"},{"path":"/getExternalQuotations","method":"GET","description":"Retrieve quotations created via API","authentication":"API Key (X-API-Key header)","requiredPermissions":["read:quotations"]}],"pricing":{"freeTier":{"invoicesPerMonth":5,"apiAccess":false},"integrationTier":{"price":29.99,"currency":"USD","billingPeriod":"monthly","features":["api_access","webhooks","1000_api_calls_per_day"]},"businessTier":{"price":49.99,"currency":"USD","billingPeriod":"monthly","features":["unlimited_api_access","webhooks","priority_support"]}},"documentation":"https://books.futuresenseai.com/docs/api"}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Firebase ID token obtained from Firebase Authentication"},"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key for external applications (obtain from /user-api-keys endpoint)"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code (e.g., MISSING_TOKEN, RATE_LIMIT_EXCEEDED)"},"details":{"type":"object","description":"Additional error details"}}},"Subscription":{"type":"object","properties":{"id":{"type":"string","description":"Subscription ID"},"appId":{"type":"string","description":"Application identifier"},"planId":{"type":"string","enum":["free","starter","professional","business","enterprise"]},"status":{"type":"string","enum":["active","canceled","past_due","trialing"]},"currentPeriodEnd":{"type":"string","format":"date-time"},"cancelAtPeriodEnd":{"type":"boolean"}}},"Plan":{"type":"object","properties":{"name":{"type":"string"},"prices":{"type":"object","additionalProperties":{"type":"object","properties":{"amount":{"type":"number"},"currency":{"type":"string"},"interval":{"type":"string","enum":["month","year"]},"stripeId":{"type":"string"}}}},"features":{"type":"array","items":{"type":"string"}}}},"Invoice":{"type":"object","description":"Invoice object for Invoicer app","properties":{"invoiceId":{"type":"string","description":"Unique invoice identifier"},"invoiceNumber":{"type":"string","description":"Human-readable invoice number (e.g., INV-001)"},"customerName":{"type":"string","description":"Customer/client name"},"customerEmail":{"type":"string","format":"email","description":"Customer email address"},"customerAddress":{"type":"string","description":"Customer billing address"},"items":{"type":"array","description":"Line items on the invoice","items":{"type":"object","properties":{"description":{"type":"string","description":"Item description"},"quantity":{"type":"number","description":"Quantity"},"unitPrice":{"type":"number","description":"Price per unit"},"total":{"type":"number","description":"Line total (quantity × unitPrice)"}},"required":["description","quantity","unitPrice"]}},"subtotal":{"type":"number","description":"Subtotal before tax"},"tax":{"type":"number","description":"Tax amount"},"taxRate":{"type":"number","description":"Tax rate as percentage (e.g., 13 for 13%)"},"total":{"type":"number","description":"Total amount due"},"currency":{"type":"string","enum":["USD","CAD","EUR","GBP"],"description":"Currency code"},"status":{"type":"string","enum":["draft","sent","paid","overdue","cancelled"],"description":"Invoice status"},"dueDate":{"type":"string","format":"date","description":"Payment due date (YYYY-MM-DD)"},"createdAt":{"type":"string","format":"date-time","description":"Creation timestamp"},"updatedAt":{"type":"string","format":"date-time","description":"Last update timestamp"}},"required":["customerName","items","total","currency","status"]},"Quotation":{"type":"object","description":"Quotation object for Invoicer app","properties":{"quotationId":{"type":"string","description":"Unique quotation identifier"},"quotationNumber":{"type":"string","description":"Human-readable quotation number (e.g., QUO-001)"},"customerName":{"type":"string","description":"Customer/client name"},"customerEmail":{"type":"string","format":"email","description":"Customer email address"},"items":{"type":"array","description":"Line items on the quotation","items":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"number"},"unitPrice":{"type":"number"},"total":{"type":"number"}}}},"total":{"type":"number","description":"Total quoted amount"},"currency":{"type":"string","enum":["USD","CAD","EUR","GBP"]},"status":{"type":"string","enum":["draft","sent","accepted","declined","expired"]},"validUntil":{"type":"string","format":"date","description":"Quote expiration date"},"createdAt":{"type":"string","format":"date-time"}}},"ApiKey":{"type":"object","description":"User API key for programmatic access","properties":{"id":{"type":"string","description":"API key ID"},"name":{"type":"string","description":"Friendly name for the key"},"keyPreview":{"type":"string","description":"Partial key for identification (e.g., fs_api_abc...)"},"status":{"type":"string","enum":["active","revoked"],"description":"Key status"},"scopes":{"type":"array","description":"Permissions granted to this key","items":{"type":"string","enum":["read:invoices","write:invoices","update:invoices","delete:invoices","read:quotations","write:quotations","update:quotations","delete:quotations","webhooks"]}},"rateLimits":{"type":"object","properties":{"requestsPerHour":{"type":"number"},"requestsPerDay":{"type":"number"},"requestsPerMonth":{"type":"number"}}},"usageStats":{"type":"object","properties":{"totalRequests":{"type":"number"},"requestsThisHour":{"type":"number"},"requestsToday":{"type":"number"},"requestsThisMonth":{"type":"number"}}},"webhookUrls":{"type":"array","description":"Webhook URLs to receive event notifications","items":{"type":"string","format":"uri"}},"createdAt":{"type":"string","format":"date-time"},"lastUsedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time","description":"Optional expiration date"}}}},"responses":{"Unauthorized":{"description":"Missing or invalid authentication token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Invalid or missing authentication token","code":"UNAUTHORIZED"}}}},"Forbidden":{"description":"Insufficient permissions or tier","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Insufficient permissions","code":"FORBIDDEN","requiredTier":"professional","currentTier":"free","upgradeUrl":"https://futuresenseai.com/pricing"}}}},"RateLimitExceeded":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Rate limit exceeded","code":"RATE_LIMIT_EXCEEDED","limit":100,"remaining":0,"resetAt":"2025-11-01T00:00:00Z"}}}}},"parameters":{"AppIdQuery":{"name":"appId","in":"query","required":true,"schema":{"type":"string"},"description":"Application identifier (e.g., react-blog, booker, invoicer)","example":"react-blog"},"AppIdPath":{"name":"appId","in":"path","required":true,"schema":{"type":"string"},"description":"Application identifier","example":"react-blog"}}},"security":[{"bearerAuth":[]}],"tags":[{"name":"Health","description":"API health and status endpoints"},{"name":"Authentication","description":"User authentication and profile management"},{"name":"Pricing","description":"Get pricing plans for apps"},{"name":"Payments","description":"Direct payment processing and webhooks"},{"name":"Subscriptions","description":"Manage user subscriptions and billing"},{"name":"AI Services","description":"AI text and image generation (centralized service)","externalDocs":{"description":"AI Service Documentation","url":"https://futuresenseai.com/docs/ai-services"}},{"name":"OAuth Integrations","description":"OAuth connections (Google, Microsoft, QuickBooks, etc.)"},{"name":"CRM","description":"Email, SMS, and call services"},{"name":"API Keys","description":"Manage API keys for external integrations"},{"name":"Admin","description":"Admin-only endpoints (requires admin role)"},{"name":"Service Accounts","description":"M2M API keys for backend services and cross-project integrations (admin only)"},{"name":"User API","description":"Programmatic access to user data via API keys. Requires X-API-Key header authentication."}],"x-tagGroups":[{"name":"Public","tags":["Health","Pricing"]},{"name":"User Services","tags":["Authentication","Payments","Subscriptions","API Keys"]},{"name":"AI & Integrations","tags":["AI Services","OAuth Integrations","CRM"]},{"name":"Administration","tags":["Admin"]}],"paths":{"/ai/generate-text":{"post":{"summary":"Generate AI text with failover","description":"Generate long-form or transactional text with automatic failover across Groq, GLM, DeepSeek, and Gemini models.\n\n**For AI agents**: Use this endpoint for content generation tasks like blog posts, customer emails, sales copy, or conversational replies.\n","tags":["AI Services"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"x-app-id","in":"header","required":true,"schema":{"type":"string"},"description":"Application identifier used for per-app rate limiting and usage tracking.","example":"react-blog"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","description":"Natural language instruction or content request.","example":"Write a 300 word blog post about AI trends in 2025."},"maxTokens":{"type":"integer","description":"Maximum tokens to generate (1-8000).","default":2000,"minimum":1,"maximum":8000},"temperature":{"type":"number","description":"Creativity level from 0 (deterministic) to 2 (creative).","default":0.7,"minimum":0,"maximum":2},"timeout":{"type":"integer","description":"Timeout in milliseconds before failover triggers.","default":30000}}}}}},"responses":{"200":{"description":"Text generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"string","description":"Generated text output."},"provider":{"type":"string","description":"Upstream AI provider that produced the response.","example":"groq"},"model":{"type":"string","example":"llama-3.3-70b-versatile"},"duration":{"type":"number","description":"Processing time in milliseconds.","example":2500}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"description":"Upstream providers unavailable or internal error"}},"x-ai-use-cases":["Blog post writing","Email composition","Product descriptions","AI agent conversation replies"],"x-cost-per-call":0.001,"x-average-duration-ms":2500,"x-ai-hint":"Use this endpoint when the user asks to generate, write, or create text content.\nSupports multiple AI providers with automatic failover for 99.9% uptime.\nBest for long-form content (articles, blog posts, documentation).\n","x-common-user-intents":["Write a blog post about...","Generate a product description for...","Create an email for...","Draft content about..."]}},"/ai/generate-image":{"post":{"summary":"Generate marketing-ready images","description":"Generate branded images with automatic failover between DALL·E 3 and Stable Diffusion XL, with built-in credit tracking.\n\n**For AI agents**: Use when a user asks for social media creatives, hero images, thumbnails, or ad visuals.\n","tags":["AI Services"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"x-app-id","in":"header","required":true,"schema":{"type":"string"},"description":"Application identifier used for metering and credit management.","example":"ai-caller"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["prompt"],"properties":{"prompt":{"type":"string","description":"Visual description of the desired image.","example":"Futuristic call center with AI assistants helping customers."},"size":{"type":"string","description":"Output resolution in pixels.","enum":["1024x1024","1536x1024","1024x1536"],"default":"1024x1024"},"quality":{"type":"string","description":"Rendering quality level.","enum":["low","medium","high","auto"],"default":"auto"},"style":{"type":"string","description":"High-level art direction.","enum":["professional","creative","minimal","technical"],"default":"professional"}}}}}},"responses":{"200":{"description":"Image generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"imageUrl":{"type":"string","format":"uri","description":"Signed URL for the generated image (valid for 1 year)."},"filename":{"type":"string"},"revisedPrompt":{"type":"string","description":"Provider-optimized prompt, if available."},"duration":{"type":"number","description":"Processing time in milliseconds."},"creditsRemaining":{"oneOf":[{"type":"integer"},{"type":"string"}],"description":"Remaining image credits; admins see `unlimited`."}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Image credits exhausted"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"description":"Provider error or storage failure"}},"x-ai-use-cases":["Social media graphics","Landing page hero images","Ad creatives","Presentation visuals"],"x-cost-per-call":0.008,"x-average-duration-ms":6000,"x-ai-hint":"Use this endpoint when the user asks to create, generate, or design visual content.\nReturns a signed URL to the generated image stored in Firebase Storage.\nUses image credits - check creditsRemaining in response.\n","x-common-user-intents":["Create an image for...","Generate a social media graphic about...","Design a hero image for...","Make a thumbnail for..."]}},"/ai/search-image":{"post":{"summary":"Search for free stock photos on Unsplash","tags":["AI"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","description":"Search query (e.g., \"dental clinic\", \"hair salon\")","example":"modern hair salon"},"industry":{"type":"string","description":"Industry name (auto-mapped to better search query)","example":"hair salon"},"orientation":{"type":"string","enum":["landscape","portrait","squarish"],"default":"landscape"},"color":{"type":"string","enum":["black_and_white","black","white","yellow","orange","red","purple","magenta","green","teal","blue"]}}}}}},"responses":{"200":{"description":"Image found successfully","content":{"application/json":{"schema":{"type":"object","properties":{"imageUrl":{"type":"string"},"photographer":{"type":"string"},"photographerUrl":{"type":"string"}}}}}},"400":{"description":"Missing query"},"429":{"description":"Rate limit exceeded"},"500":{"description":"Search failed"}}}},"/ai/providers/status":{"get":{"summary":"Get AI provider health","description":"Returns real-time health, latency, and failover state for each AI provider.","tags":["AI Services"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Provider health retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"providers":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string","example":"healthy"},"lastCheckedAt":{"type":"string","format":"date-time"}}}},"timestamp":{"type":"string","format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Unable to determine provider health"}}}},"/ai/usage/{appId}":{"get":{"summary":"Get AI usage metrics","description":"Retrieve the last 30 days of AI usage for the specified application, including token, cost, and request counts.\n\nAdmin access required.\n","tags":["AI Services"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string"},"description":"Application identifier whose AI usage should be retrieved.","example":"react-blog"}],"responses":{"200":{"description":"Usage metrics retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"appId":{"type":"string"},"totals":{"type":"object","properties":{"textRequests":{"type":"integer"},"imageRequests":{"type":"integer"},"avgDurationMs":{"type":"number"},"estimatedSpendUsd":{"type":"number"}}},"daily":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"textRequests":{"type":"integer"},"imageRequests":{"type":"integer"},"spendUsd":{"type":"number"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"description":"Failed to aggregate usage data"}}}},"/credits/balance/{appId}":{"get":{"summary":"Get credit balance","description":"Retrieve the current credit balance for a specific app","tags":["Credits"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"appId","required":true,"schema":{"type":"string"},"description":"Application identifier","example":"ai-caller"}],"responses":{"200":{"description":"Credit balance retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"balance":{"type":"number"},"totalPurchased":{"type":"number"},"totalConsumed":{"type":"number"},"lastPurchaseAt":{"type":"string","format":"date-time"},"lastConsumedAt":{"type":"string","format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/credits/consume":{"post":{"summary":"Consume credits","description":"Deduct credits from user's balance. Typically called by app backends, not frontend.","tags":["Credits"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["appId","amount","description"],"properties":{"appId":{"type":"string","example":"ai-caller"},"amount":{"type":"number","minimum":0.01,"description":"Amount of credits to consume"},"description":{"type":"string","description":"Description of what consumed the credits","example":"AI call - 5 minutes"},"metadata":{"type":"object","description":"Additional metadata (call ID, duration, etc.)"}}}}}},"responses":{"200":{"description":"Credits consumed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"balance":{"type":"number","description":"Remaining balance after consumption"}}}}}},"400":{"description":"Insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/credits/history/{appId}":{"get":{"summary":"Get credit transaction history","description":"Retrieve the credit transaction history for authenticated user","tags":["Credits"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"appId","required":true,"schema":{"type":"string"},"example":"ai-caller"},{"in":"query","name":"limit","schema":{"type":"integer","default":50,"maximum":100}},{"in":"query","name":"offset","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Transaction history retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"transactions":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/credits/packages/{appId}":{"get":{"summary":"Get available credit packages","description":"Retrieve all available credit packages for a specific app","tags":["Credits"],"parameters":[{"in":"path","name":"appId","required":true,"schema":{"type":"string"},"example":"ai-caller"}],"responses":{"200":{"description":"Credit packages retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"packages":{"type":"array","items":{"type":"object"}},"consumptionRate":{"type":"object"}}}}}},"404":{"description":"App not found or no packages available"}}}},"/credits/purchase":{"post":{"summary":"Purchase credits","description":"Create a Stripe checkout session for purchasing credits","tags":["Credits"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["appId","packageId"],"properties":{"appId":{"type":"string","example":"ai-caller"},"packageId":{"type":"string","example":"ai_caller_credits_500"},"successUrl":{"type":"string","format":"uri"},"cancelUrl":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Checkout session created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"sessionId":{"type":"string"},"url":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Package not found"}}}},"/credits/operation-cost":{"get":{"summary":"Get operation credit cost","description":"Look up the credit cost for a specific operation from central config","tags":["Credits"],"parameters":[{"in":"query","name":"appId","required":true,"schema":{"type":"string"},"description":"Application identifier","example":"personalcfo"},{"in":"query","name":"operation","required":true,"schema":{"type":"string"},"description":"Operation name","example":"list_entities"}],"responses":{"200":{"description":"Operation cost retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"cost":{"type":"number"},"enabled":{"type":"boolean"},"description":{"type":"string"}}}}}},"400":{"description":"Missing required parameters"}}}},"/credits/check-sufficient":{"post":{"summary":"Check sufficient credits","description":"Check if user has enough credits for an operation","tags":["Credits"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["appId","requiredAmount"],"properties":{"appId":{"type":"string"},"requiredAmount":{"type":"number"}}}}}},"responses":{"200":{"description":"Check result","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"sufficient":{"type":"boolean"},"currentBalance":{"type":"number"},"requiredAmount":{"type":"number"}}}}}}}}},"/marketplace/apps":{"get":{"summary":"Get public marketplace apps","description":"Public endpoint to fetch marketplace applications with release status","tags":["Marketplace"],"parameters":[{"in":"query","name":"visibility","schema":{"type":"string","enum":["all","public","coming_soon"]},"description":"Filter apps by release status (default: all)"}],"responses":{"200":{"description":"Marketplace applications returned"},"500":{"description":"Failed to fetch marketplace apps"}}}},"/payments/stripe/create-payment-intent":{"post":{"summary":"Create a Stripe Payment Intent","description":"Create a one-time Stripe Payment Intent for direct card payments with reCAPTCHA protection and pending transaction logging.\n\n**For AI agents**: Use this when users want to process a manual payment or top up credits without launching the hosted checkout.\n","tags":["Payments"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","appId","recaptchaToken"],"properties":{"amount":{"type":"number","format":"float","minimum":0.5,"description":"Charge amount in the selected currency.","example":49.99},"currency":{"type":"string","description":"Three-letter ISO currency code.","default":"USD","example":"USD"},"appId":{"type":"string","description":"Application identifier tied to the purchase.","example":"react-blog"},"description":{"type":"string","description":"Optional description that appears in Stripe and receipts.","example":"React Blog professional add-on"},"recaptchaToken":{"type":"string","description":"Google reCAPTCHA v3 token to prevent abuse."}}}}}},"responses":{"200":{"description":"Payment Intent created","content":{"application/json":{"schema":{"type":"object","properties":{"clientSecret":{"type":"string"},"paymentIntentId":{"type":"string"},"transactionId":{"type":"string"}}}}}},"400":{"description":"reCAPTCHA verification failed"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"User not found"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"description":"Failed to create payment intent"}}}},"/payments/stripe/create-checkout-session":{"post":{"summary":"Create a hosted Stripe Checkout session","description":"Create a Stripe Checkout session for a single payment. A pending transaction record is created and reconciled after webhook confirmation.\n\n**For AI agents**: Use when users need a full checkout experience with Stripe-hosted payment pages.\n","tags":["Payments"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","appId","recaptchaToken"],"properties":{"amount":{"type":"number","format":"float","minimum":0.5,"description":"Charge amount in the selected currency.","example":79},"currency":{"type":"string","description":"Three-letter ISO currency code.","default":"USD"},"appId":{"type":"string","description":"Application identifier associated with the payment.","example":"ai-caller"},"description":{"type":"string","description":"Optional line item description shown on the checkout page.","example":"AI Caller subscription upgrade"},"recaptchaToken":{"type":"string","description":"Google reCAPTCHA v3 token."}}}}}},"responses":{"200":{"description":"Checkout session created","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"url":{"type":"string","format":"uri"},"transactionId":{"type":"string"}}}}}},"400":{"description":"reCAPTCHA verification failed"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"User not found"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"description":"Failed to create checkout session"}}}},"/payments/transactions":{"get":{"summary":"List user transactions","description":"Retrieve paginated Stripe transaction history for the authenticated user across all FutureSense apps.","tags":["Payments"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Page number for pagination (default 1)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Number of transactions per page (default 10)."},{"name":"appId","in":"query","required":false,"schema":{"type":"string"},"description":"Filter results to a single application identifier.","example":"invoicer"}],"responses":{"200":{"description":"Transaction list retrieved"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to fetch transactions"}}}},"/payments/plans":{"get":{"summary":"Get pricing plans for an app","description":"Public endpoint that proxies pricing data from the central pricing service.","tags":["Pricing"],"security":[],"parameters":[{"$ref":"#/components/parameters/AppIdQuery"}],"responses":{"200":{"description":"Pricing plans retrieved"},"400":{"description":"Missing appId query parameter"},"404":{"description":"App not found"}}}},"/payments/stripe/webhook":{"post":{"summary":"Handle Stripe webhook events","description":"Validates Stripe webhook signatures, stores an audit log, and updates transaction records.","tags":["Payments"],"security":[],"responses":{"200":{"description":"Webhook processed successfully"},"400":{"description":"Invalid Stripe signature"},"500":{"description":"Error processing webhook"}}}},"/api/integrations/export-payroll":{"post":{"summary":"Export payroll data in multiple formats","tags":["Integrations"],"security":[{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["format","payrollData"],"properties":{"format":{"type":"string","enum":["csv","json","xml","excel"]},"payrollData":{"type":"object"},"options":{"type":"object"}}}}}},"responses":{"200":{"description":"Payroll data exported successfully"},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized"}}}},"/integrations/plaid/link-token":{"post":{"summary":"Create Plaid Link token","description":"Generate a Link token to initialize Plaid Link in the frontend","tags":["Plaid Banking"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["appId"],"properties":{"appId":{"type":"string","description":"The app requesting the connection"},"products":{"type":"array","items":{"type":"string"},"description":"Plaid products to enable (default transactions)"}}}}}},"responses":{"200":{"description":"Link token created"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/integrations/plaid/exchange-token":{"post":{"summary":"Exchange public token","description":"Exchange a Plaid Link public token for an access token","tags":["Plaid Banking"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["appId","publicToken","metadata"],"properties":{"appId":{"type":"string"},"publicToken":{"type":"string"},"metadata":{"type":"object","properties":{"institutionId":{"type":"string"},"institutionName":{"type":"string"},"accounts":{"type":"array"}}}}}}}},"responses":{"200":{"description":"Token exchanged, connection created"}}}},"/integrations/plaid/connections":{"get":{"summary":"Get user's bank connections","description":"List all Plaid bank connections for the user","tags":["Plaid Banking"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of bank connections"}}}},"/integrations/plaid/account-limit":{"get":{"summary":"Get the caller's per-account Plaid cap and current usage","tags":["Plaid Banking"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"{ tier, limit, usage }"}}}},"/integrations/plaid/accounts/{connectionId}":{"get":{"summary":"Get accounts for a connection","tags":["Plaid Banking"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of accounts"}}}},"/integrations/plaid/balances/{connectionId}":{"get":{"summary":"Get account balances","tags":["Plaid Banking"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Account balances"}}}},"/integrations/plaid/sync/{connectionId}":{"post":{"summary":"Sync transactions","description":"Sync transactions from a bank connection (rate limited to once per 6 hours)","tags":["Plaid Banking"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["appId"],"properties":{"appId":{"type":"string","description":"Application ID (required for subscription validation)","example":"personalcfo"},"forceSync":{"type":"boolean","description":"Override rate limiting (admin only)"},"daysBack":{"type":"number","description":"Days of transactions to fetch (default 7)"}}}}}},"responses":{"200":{"description":"Sync results"},"429":{"description":"Rate limited"}}}},"/integrations/plaid/transactions":{"get":{"summary":"Get transactions","tags":["Plaid Banking"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"connectionId","in":"query","schema":{"type":"string"}},{"name":"accountId","in":"query","schema":{"type":"string"}},{"name":"startDate","in":"query","schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"List of transactions"}}}},"/integrations/plaid/toggle-app":{"put":{"summary":"Toggle app access for a connection","tags":["Plaid Banking"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["connectionId","appId","enabled"],"properties":{"connectionId":{"type":"string"},"appId":{"type":"string"},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"App access toggled"}}}},"/integrations/plaid/disconnect/{connectionId}":{"delete":{"summary":"Disconnect a bank connection","tags":["Plaid Banking"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"connectionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Connection disconnected"}}}},"/integrations/plaid/webhook":{"post":{"summary":"Handle Plaid webhooks","description":"Receives webhook events from Plaid","tags":["Plaid Banking"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Webhook processed"}}}},"/integrations/plaid/institutions":{"get":{"summary":"Search financial institutions","tags":["Plaid Banking"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string"},"description":"Search term (e.g., \"Chase\", \"Bank of America\")"},{"name":"limit","in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"List of matching institutions"}}}},"/integrations/plaid/institutions/{institutionId}":{"get":{"summary":"Get institution details","tags":["Plaid Banking"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"institutionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Institution details"}}}},"/admin/service-accounts":{"get":{"summary":"List all service accounts","description":"Retrieve all M2M service accounts (admin only)","tags":["Service Accounts"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Service accounts retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"serviceAccounts":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Admin access required"}}},"post":{"summary":"Create service account API key","description":"Generate a new M2M API key for backend services (admin only)","tags":["Service Accounts"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","environment","scopes"],"properties":{"name":{"type":"string","description":"Service account name"},"description":{"type":"string","description":"Purpose of this service account"},"environment":{"type":"string","enum":["development","production","enterprise"]},"projectId":{"type":"string","description":"Firebase project ID this service belongs to"},"scopes":{"type":"array","items":{"type":"string"},"description":"Permissions (e.g., [\"read:users\", \"write:subscriptions\"])"},"expiresInDays":{"type":"integer","description":"Optional expiration window in days"}}}}}},"responses":{"201":{"description":"Service account created"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Admin access required"}}}},"/admin/service-accounts/{id}":{"delete":{"summary":"Revoke service account","description":"Revoke a service account API key (admin only)","tags":["Service Accounts"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Service account revoked"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Admin access required"},"404":{"description":"Service account not found"}}}},"/subscriptions/portal":{"post":{"summary":"Create customer portal session (legacy alias)","description":"Legacy alias for `/subscriptions/create-portal`. Generates a Stripe billing portal URL for the authenticated user.","tags":["Subscriptions"],"security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"returnUrl":{"type":"string","format":"uri","description":"Optional URL to redirect back after managing billing."}}}}}},"responses":{"200":{"description":"Portal session created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"url":{"type":"string","format":"uri"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to create portal session"}}}},"/subscriptions/create-portal":{"post":{"summary":"Create Stripe billing portal session","description":"Provide users with a self-service billing portal to manage payment methods and invoices.","tags":["Subscriptions"],"security":[{"bearerAuth":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"returnUrl":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"Portal session created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"url":{"type":"string","format":"uri"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to create portal session"}}}},"/subscriptions/payment-methods":{"get":{"summary":"List saved payment methods","description":"Fetch the customer's saved payment methods from Stripe.","tags":["Subscriptions"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Payment methods retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"paymentMethods":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"card":{"type":"object","nullable":true,"properties":{"brand":{"type":"string"},"last4":{"type":"string"},"expMonth":{"type":"integer"},"expYear":{"type":"integer"}}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to fetch payment methods"}}}},"/subscriptions/payment-methods/set-default":{"post":{"summary":"Set default payment method","description":"Set the specified payment method as the default for future invoices.","tags":["Subscriptions"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["paymentMethodId"],"properties":{"paymentMethodId":{"type":"string","description":"Stripe payment method identifier."}}}}}},"responses":{"200":{"description":"Default payment method set"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to update payment method"}}}},"/subscriptions/payment-methods/{paymentMethodId}":{"delete":{"summary":"Remove payment method","description":"Detach a saved payment method from the customer.","tags":["Subscriptions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"paymentMethodId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Payment method removed"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to remove payment method"}}}},"/subscriptions/invoices":{"get":{"summary":"List invoices","description":"Retrieve Stripe invoices for the authenticated customer.","tags":["Subscriptions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100},"description":"Maximum number of invoices to return (default 10)."}],"responses":{"200":{"description":"Invoices retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"invoices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"},"status":{"type":"string"},"created":{"type":"string","format":"date-time"},"hostedInvoiceUrl":{"type":"string","format":"uri"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to fetch invoices"}}}},"/subscriptions/upcoming-invoice/{appId}":{"get":{"summary":"Get upcoming invoice","description":"Retrieve the next scheduled invoice for the specified app subscription.","tags":["Subscriptions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Upcoming invoice retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"invoice":{"type":"object","nullable":true,"properties":{"amount":{"type":"number"},"currency":{"type":"string"},"periodStart":{"type":"string","format":"date-time"},"periodEnd":{"type":"string","format":"date-time"},"nextPaymentAttempt":{"type":"string","format":"date-time"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to fetch upcoming invoice"}}}},"/subscriptions/invoices/{invoiceId}/retry":{"post":{"summary":"Retry invoice payment","description":"Attempt to pay a failed invoice again using the default payment method.","tags":["Subscriptions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"invoiceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Retry initiated"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to retry invoice"}}}},"/subscriptions/create-checkout":{"post":{"summary":"Start subscription checkout","description":"Create a Stripe Checkout session for upgrading a user to a paid plan.","tags":["Subscriptions"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["appId","planId"],"properties":{"appId":{"type":"string","description":"Application identifier the subscription applies to.","example":"react-blog"},"planId":{"type":"string","description":"Plan tier key (free, starter, professional, business, enterprise).","example":"professional"},"priceId":{"type":"string","description":"Stripe price ID. Optional — resolved from appId + planId + interval if omitted.","example":"price_1Q9xyZA10"},"interval":{"type":"string","enum":["monthly","yearly"],"description":"Billing interval. Used when priceId is omitted. Defaults to monthly."},"successUrl":{"type":"string","format":"uri"},"cancelUrl":{"type":"string","format":"uri"},"metadata":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"Checkout session created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"sessionId":{"type":"string"},"url":{"type":"string","format":"uri"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to create checkout session"}},"x-ai-hint":"Use when user wants to \"subscribe\", \"upgrade\", or \"start a paid plan\".\nReturns a Stripe Checkout URL - redirect the user to complete payment.\nAfter payment, Stripe webhook automatically activates the subscription.\n","x-common-user-intents":["I want to upgrade to Pro","Subscribe to the Business plan","Start a paid subscription","Switch to the Professional tier"]}},"/subscriptions/buy-credits":{"post":{"summary":"Purchase usage credits","description":"Create a Stripe Checkout session for purchasing additional AI credits or metered add-ons.\n","tags":["Subscriptions"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["appId","packageId","credits"],"properties":{"appId":{"type":"string","example":"ai-caller"},"packageId":{"type":"string","description":"Identifier of the credit package (e.g., ai-caller-500)."},"priceId":{"type":"string","description":"Stripe price ID. Optional — resolved from appId + packageId + currency if omitted."},"credits":{"type":"integer","minimum":1},"currency":{"type":"string","description":"Currency code for price resolution. Defaults to usd.","example":"usd"},"successUrl":{"type":"string","format":"uri"},"cancelUrl":{"type":"string","format":"uri"},"metadata":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"Checkout session created","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"sessionId":{"type":"string"},"url":{"type":"string","format":"uri"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to create credit checkout session"}}}},"/subscriptions/status":{"get":{"summary":"Get subscription status","description":"Returns the active subscription for the authenticated user. Provide `x-app-id` header or `appId` query to target a specific app.","tags":["Subscriptions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"x-app-id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional application identifier header override."},{"name":"appId","in":"query","required":false,"schema":{"type":"string"},"description":"Optional application identifier to check."}],"responses":{"200":{"description":"Subscription status retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"string"},"subscription":{"$ref":"#/components/schemas/Subscription"},"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to retrieve subscription status"}}}},"/subscriptions/status/{appId}":{"get":{"summary":"Get subscription status for an app","description":"Check whether the authenticated user has an active subscription for the specified application.","tags":["Subscriptions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string"},"description":"Application identifier to check."}],"responses":{"200":{"description":"Subscription status retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"subscription":{"$ref":"#/components/schemas/Subscription"},"status":{"type":"string","example":"active"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to retrieve subscription status"}}}},"/subscriptions/all":{"get":{"summary":"List all subscriptions","description":"Retrieve every subscription attached to the authenticated user across all FutureSense apps.","tags":["Subscriptions"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Subscriptions retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to fetch subscriptions"}}}},"/subscriptions/cancel/{appId}":{"post":{"summary":"Cancel subscription","description":"Cancel or schedule cancellation for the specified app subscription.","tags":["Subscriptions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"cancelAtPeriodEnd":{"type":"boolean","description":"Whether to cancel at the end of the current billing period.","default":true}}}}}},"responses":{"200":{"description":"Cancellation scheduled or completed"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to cancel subscription"}}}},"/subscriptions/reactivate/{appId}":{"post":{"summary":"Reactivate subscription","description":"Remove cancellation flags and reactivate the subscription if still within the billing period.","tags":["Subscriptions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Subscription reactivated"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to reactivate subscription"}}}},"/subscriptions/pause/{appId}":{"post":{"summary":"Pause subscription","description":"Temporarily pause billing for the specified subscription with an optional resume date.","tags":["Subscriptions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"resumeAt":{"type":"string","format":"date-time","description":"Optional ISO date when the subscription should resume automatically."}}}}}},"responses":{"200":{"description":"Subscription paused"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to pause subscription"}}}},"/subscriptions/resume/{appId}":{"post":{"summary":"Resume subscription","description":"Resume a previously paused subscription immediately.","tags":["Subscriptions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Subscription resumed"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to resume subscription"}}}},"/subscriptions/update/{appId}":{"post":{"summary":"Change subscription plan","description":"Upgrade or downgrade the subscription for the specified app.","tags":["Subscriptions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"appId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["newPriceId"],"properties":{"newPriceId":{"type":"string","description":"Target Stripe price identifier."},"prorationBehavior":{"type":"string","enum":["create_prorations","none","always_invoice"],"default":"create_prorations"}}}}}},"responses":{"200":{"description":"Subscription updated"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to update subscription"}}}},"/integrations/taxbandits/health":{"get":{"summary":"Tax Bandits integration health check","description":"Verifies Tax Bandits credentials and connectivity","tags":["Tax Bandits"],"responses":{"200":{"description":"Health status"}}}},"/integrations/taxbandits/businesses":{"get":{"summary":"Get user's business profiles","description":"List all business profiles for tax form filing","tags":["Tax Bandits"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of business profiles"}}},"post":{"summary":"Create or update business profile","description":"Save business information for tax form filing","tags":["Tax Bandits"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["businessName","ein","address","contactName","contactPhone","contactEmail"],"properties":{"businessId":{"type":"string","description":"Optional - for updating existing business"},"businessName":{"type":"string"},"ein":{"type":"string"},"address":{"type":"object"},"contactName":{"type":"string"},"contactPhone":{"type":"string"},"contactEmail":{"type":"string"}}}}}},"responses":{"200":{"description":"Business saved"}}}},"/integrations/taxbandits/forms/1099-nec":{"post":{"summary":"Submit 1099-NEC form","description":"File 1099-NEC for non-employee compensation","tags":["Tax Bandits"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["businessId","taxYear","recipient","nonEmployeeCompensation","appId"],"properties":{"businessId":{"type":"string"},"taxYear":{"type":"number"},"recipient":{"type":"object"},"nonEmployeeCompensation":{"type":"number"},"appId":{"type":"string"}}}}}},"responses":{"200":{"description":"Form submitted"}}}},"/integrations/taxbandits/forms/w2":{"post":{"summary":"Submit W-2 form","description":"File W-2 for employee wages","tags":["Tax Bandits"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["businessId","taxYear","employee","wages","federalIncomeTaxWithheld","socialSecurityWages","socialSecurityTaxWithheld","medicareWages","medicareTaxWithheld","appId"]}}}},"responses":{"200":{"description":"Form submitted"}}}},"/integrations/taxbandits/submissions":{"get":{"summary":"Get user's tax form submissions","description":"List all submitted tax forms","tags":["Tax Bandits"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"formType","in":"query","schema":{"type":"string"}},{"name":"taxYear","in":"query","schema":{"type":"number"}},{"name":"limit","in":"query","schema":{"type":"number"}}],"responses":{"200":{"description":"List of submissions"}}}},"/integrations/taxbandits/submissions/{submissionId}":{"get":{"summary":"Get submission status","description":"Check status of a submitted tax form","tags":["Tax Bandits"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"submissionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Submission status"}}},"delete":{"summary":"Delete pending submission","description":"Delete a tax form submission that hasn't been filed yet","tags":["Tax Bandits"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"submissionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Submission deleted"}}}},"/integrations/taxbandits/submissions/{submissionId}/pdf":{"get":{"summary":"Get PDF for submission","description":"Download PDF copy of submitted tax form","tags":["Tax Bandits"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"submissionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"PDF URL"}}}},"/api/user-api/me":{"get":{"summary":"Get authenticated user profile","description":"Retrieve the profile information for the user associated with the API key.","tags":["User API"],"security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"User profile retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"emailVerified":{"type":"boolean"},"displayName":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"createdAt":{"type":"string"},"lastLoginAt":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Missing required scope"}},"x-ai-hint":"Use this to get basic user information when an AI agent needs to identify or personalize responses for the authenticated user.","x-common-user-intents":["Show me my profile","What's my account information?","Get my user details"]}},"/api/user-api/subscriptions":{"get":{"summary":"List user subscriptions","description":"Retrieve all subscriptions for the authenticated user across all apps.","tags":["User API"],"security":[{"apiKeyAuth":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["active","canceled","past_due","trialing"]},"description":"Filter by subscription status"}],"responses":{"200":{"description":"Subscriptions retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}},"total":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"x-ai-hint":"Query user subscriptions to check which apps they have access to and their subscription tiers.","x-common-user-intents":["What apps am I subscribed to?","Show my active subscriptions","List all my plans"]}},"/api/user-api/transactions":{"get":{"summary":"List user transactions","description":"Retrieve transaction history for the authenticated user with pagination and filtering.","tags":["User API"],"security":[{"apiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100},"description":"Number of transactions to return"},{"name":"offset","in":"query","schema":{"type":"integer","default":0},"description":"Pagination offset"},{"name":"appId","in":"query","schema":{"type":"string"},"description":"Filter by application ID"},{"name":"status","in":"query","schema":{"type":"string","enum":["completed","pending","failed"]},"description":"Filter by transaction status"}],"responses":{"200":{"description":"Transactions retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"transactions":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"x-ai-hint":"Use this to retrieve payment history and transaction details for billing inquiries.","x-common-user-intents":["Show my recent payments","What did I pay last month?","List my transaction history"]}},"/api/user-api/rate-limits":{"get":{"summary":"Get current rate limit status","description":"Check remaining rate limit quota for the authenticated API key (hourly and daily).","tags":["User API"],"security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"Rate limit status retrieved","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"tier":{"type":"string"},"rateLimits":{"type":"object","properties":{"hourly":{"type":"object","properties":{"limit":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"},"resetAt":{"type":"string","format":"date-time"}}},"daily":{"type":"object","properties":{"limit":{"type":"integer"},"used":{"type":"integer"},"remaining":{"type":"integer"},"resetAt":{"type":"string","format":"date-time"}}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}},"x-ai-hint":"Check this before making batch requests to avoid hitting rate limits.","x-common-user-intents":["How many API calls do I have left?","Check my rate limit status","Am I close to my API quota?"]}},"/api-keys":{"get":{"summary":"List API keys (legacy)","description":"Returns the user's API keys along with tier information. This legacy endpoint is maintained for backward compatibility.","tags":["API Keys"],"deprecated":true,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"API keys retrieved"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to fetch API keys"}}},"post":{"summary":"Create API key","description":"Generate a new API key for the authenticated user with tier-aware limits and scope validation.","tags":["API Keys"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"expiresInDays":{"type":"integer","description":"Optional expiration window in days."}}}}}},"responses":{"201":{"description":"API key created"},"400":{"description":"Validation error"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Tier limit reached"},"500":{"description":"Failed to create API key"}}}},"/api/user-api-keys":{"get":{"summary":"List API keys","description":"Retrieve all API keys for the authenticated user, including usage stats, rate limits, and tier metadata.","tags":["API Keys"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"API keys retrieved"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to fetch API keys"}}}},"/api-keys/{id}":{"get":{"summary":"Get API key metadata","description":"Retrieve metadata for a single API key (never returns the full secret).","tags":["API Keys"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key metadata returned"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"API key not found"},"500":{"description":"Failed to fetch API key"}}},"put":{"summary":"Update API key metadata","description":"Update mutable fields (such as the display name) for an API key.","tags":["API Keys"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}},"responses":{"200":{"description":"API key updated"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"API key not found"},"500":{"description":"Failed to update API key"}}},"delete":{"summary":"Revoke API key","description":"Revoke (soft-delete) an API key so it can no longer be used.","tags":["API Keys"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key revoked"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"API key not found"},"500":{"description":"Failed to revoke API key"}}}},"/api-keys/{id}/usage":{"get":{"summary":"Get API key usage","description":"Retrieve rate limit consumption and usage statistics for an API key.","tags":["API Keys"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Usage statistics returned"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"API key not found"},"500":{"description":"Failed to retrieve usage stats"}}}},"/api/tier-info":{"get":{"summary":"Get API tier information","description":"Retrieve the authenticated user's API plan tier and applicable limits.","tags":["API Keys"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Tier information returned"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"description":"Failed to fetch tier information"}}}}}}