# FutureSense AI - Complete API Reference for LLMs
# https://llmstxt.org/
# This is the extended version. See llms.txt for the summary.

> FutureSense AI is an API-first business automation platform. 439 operations across 33 apps — accessible via REST API with universal credits. AI agents can authenticate, purchase credits, and call any operation programmatically.

## Quick Start for AI Agents

### Base URL
```
https://us-central1-paymentgateway-ab783.cloudfunctions.net/api
```

### Authentication
Every request (except public endpoints) requires:
```
Authorization: Bearer <firebase_id_token>
x-app-id: <target-app-id>
Content-Type: application/json
```

Alternative: Use API keys for M2M access:
```
x-api-key: <your_api_key>
x-app-id: <target-app-id>
```

### Machine-Readable Specs
- OpenAPI 3.0: https://futuresenseai.com/openapi.json
- Swagger UI: https://us-central1-paymentgateway-ab783.cloudfunctions.net/api/api-docs
- OpenAPI JSON: https://us-central1-paymentgateway-ab783.cloudfunctions.net/api/api-docs.json
- AI Plugin: https://futuresenseai.com/.well-known/ai-plugin.json

---

## Complete Endpoint Reference

### Health & Status (Public, No Auth)

#### GET /health
Platform health check.
```json
Response: { "status": "OK", "timestamp": "...", "version": "4.0.0-modular" }
```

#### GET /analytics/public
Aggregate platform metrics.
```json
Response: { "metrics": { "activeUsers": 150, "totalTransactions": 5000, "businessesTransformed": 120 } }
```

---

### Authentication

#### POST /auth/exchange-token
Exchange Firebase ID token for cross-app SSO session.
```json
Request: { "idToken": "firebase_id_token", "appId": "invoicer" }
Response: { "customToken": "...", "uid": "..." }
```

---

### Universal Credits System

Every API operation costs credits. Buy credits via Stripe, then call any operation across any app.

#### GET /credits/balance
Check credit balance.
```json
Headers: Authorization: Bearer <token>, x-app-id: <appId>
Response: { "balance": 5000, "userId": "abc123" }
```

#### POST /credits/check
Pre-check if user can afford an operation.
```json
Request: { "operationId": "createInvoice", "appId": "invoicer" }
Response: { "canAfford": true, "cost": 5, "balance": 5000 }
```

#### POST /credits/deduct
Deduct credits for an operation.
```json
Request: { "operationId": "createInvoice", "appId": "invoicer", "amount": 5 }
Response: { "success": true, "newBalance": 4995 }
```

### Credit Pricing Tiers
| Tier | Credits | Example Operations |
|------|---------|-------------------|
| Read | 3 | List records, get details, check status |
| Write | 5-8 | Create/update records, send emails |
| Report | 10-15 | Generate reports, PDF export, analytics |
| AI | 20-30 | AI analysis, predictions, recommendations |
| Premium | 35-100 | Payroll processing, bulk campaigns, tax filing, AI content generation |

---

### Subscriptions & Billing

#### GET /pricing/app/{appId}
Get pricing plans for an app (public, no auth).
```json
Response: { "appId": "invoicer", "plans": { "free": {...}, "starter": {...}, "professional": {...} } }
```

#### GET /subscriptions/status/{appId}
Check subscription status.
```json
Response: { "appId": "invoicer", "planId": "professional", "status": "active", "currentPeriodEnd": "2026-03-15T00:00:00Z" }
```

#### POST /subscriptions/checkout
Create Stripe checkout session for subscription or credit purchase.
```json
Request: { "appId": "invoicer", "planId": "professional", "successUrl": "https://...", "cancelUrl": "https://..." }
Response: { "url": "https://checkout.stripe.com/...", "sessionId": "cs_..." }
```

---

### AI Services

#### POST /ai/generate-text
Generate text with multi-provider failover (Groq, GLM, DeepSeek, Gemini).
```json
Request: {
  "prompt": "Write a 300 word blog post about AI trends in 2026.",
  "maxTokens": 2000,
  "temperature": 0.7,
  "timeout": 30000
}
Response: {
  "content": "...",
  "provider": "groq",
  "model": "llama-3.3-70b-versatile",
  "duration": 2500
}
```
Cost: ~20-30 credits | Rate limit: 20-100 req/min per app

#### POST /ai/generate-image
Generate images (DALL-E 3 / Stable Diffusion failover).
```json
Request: {
  "prompt": "Futuristic call center with AI assistants",
  "size": "1024x1024",
  "quality": "standard",
  "style": "professional"
}
Response: {
  "imageUrl": "https://storage.googleapis.com/...",
  "filename": "ai-images/...",
  "revisedPrompt": "...",
  "duration": 6000,
  "creditsRemaining": 45
}
```
Cost: ~35-50 credits | Sizes: 1024x1024, 1792x1024, 1024x1792

#### POST /ai/search-image
Search free Unsplash stock photos (no credit cost).
```json
Request: { "query": "modern hair salon", "orientation": "landscape" }
Response: { "imageUrl": "...", "photographer": "...", "photographerUrl": "..." }
```

#### GET /ai/providers/status
Get real-time AI provider health and latency.

---

### CRM & Communications

#### GET /crm/contacts
List CRM contacts. Supports pagination with `limit` and `offset` query params.

#### POST /crm/contacts
Create a contact.
```json
Request: { "email": "john@acme.com", "firstName": "John", "lastName": "Doe", "company": "Acme", "tags": ["lead"] }
```

#### POST /crm/email/send
Send email via connected provider (Gmail, Outlook, SES).
```json
Request: { "to": "customer@example.com", "subject": "Invoice Ready", "body": "<h1>Your invoice is ready</h1>..." }
```

#### POST /crm/campaigns
Create email campaign.
```json
Request: { "name": "Newsletter Q1", "subject": "...", "htmlBody": "...", "recipients": ["tag:customers"], "scheduledAt": "2026-03-01T10:00:00Z" }
```

#### POST /communications/email/send
Send transactional email (receipts, notifications, confirmations).

#### POST /communications/email/bulk
Send bulk email campaigns.

---

### OAuth Integrations

Supported providers: Google, Microsoft, QuickBooks, Xero, LinkedIn, WordPress, Facebook

#### GET /integrations/connections
List all connected OAuth providers for the user.

#### POST /integrations/oauth/{provider}/initiate
Start OAuth flow. Returns `authUrl` to redirect user.
```json
Request: { "appId": "invoicer", "scopes": ["email", "profile", "calendar"] }
Response: { "authUrl": "https://accounts.google.com/o/oauth2/..." }
```

#### GET /integrations/oauth/{provider}/status
Check connection status for a provider.

---

### API Keys (Programmatic Access)

#### GET /user-api-keys
List your API keys.

#### POST /user-api-keys
Create a new API key.
```json
Request: { "name": "Production Key", "scopes": ["read:invoices", "write:invoices"] }
Response: { "id": "key_...", "key": "fs_api_...", "name": "Production Key" }
```

#### DELETE /user-api-keys/{id}
Revoke an API key.

---

### Marketplace (Public)

#### GET /marketplace/apps
List all marketplace apps with pricing and release status.
```json
Query: ?visibility=public (or all, coming_soon)
Response: { "apps": { "invoicer": { "appName": "Invoice Creator Pro", "plans": {...}, "url": "https://ledger.futuresenseai.com", "releaseStatus": "released" } }, "count": 33 }
```

---

### Accounting (Requires x-app-id: invoicer or accounting)

Full double-entry bookkeeping API:
- `GET /accounting/chart-of-accounts` — List accounts
- `POST /accounting/journal-entries` — Create journal entry
- `GET /accounting/general-ledger` — General ledger report
- `GET /accounting/trial-balance` — Trial balance
- `GET /accounting/reports/profit-loss` — P&L report
- `GET /accounting/reports/balance-sheet` — Balance sheet
- `GET /accounting/reports/cash-flow` — Cash flow statement
- `POST /accounting/bills` — Create bill / A/P
- `POST /accounting/invoices` — Create A/R invoice
- `POST /accounting/bank-reconciliation` — Reconcile bank transactions
- `GET /accounting/vendors` — List vendors
- `POST /accounting/period-close` — Close accounting period

---

### Micro-SaaS AI Tools (20+ endpoints)

Each tool is a single-purpose AI endpoint. All require auth + x-app-id.

| Endpoint | Method | Description | Credits |
|----------|--------|-------------|---------|
| `/invoice-explainer/analyze` | POST | Explain invoice in plain English | 10 |
| `/receipt-scanner/scan` | POST | OCR + categorize receipt | 15 |
| `/contract-analyzer/analyze` | POST | Analyze legal contract | 20 |
| `/quote-converter/convert` | POST | Convert quote to invoice | 8 |
| `/outreach-writer/generate` | POST | Write sales outreach email | 15 |
| `/seo-generator/generate` | POST | Generate SEO meta tags | 10 |
| `/welcome-email/generate` | POST | Generate onboarding email | 10 |
| `/lead-enricher/enrich` | POST | Enrich lead data | 12 |
| `/pricing-ideas/generate` | POST | AI pricing suggestions | 15 |
| `/save-offer/generate` | POST | Generate save offer for churning customer | 12 |
| `/churn-detector/analyze` | POST | Predict churn risk | 15 |
| `/social-snippet/generate` | POST | Generate social media post | 10 |
| `/testimonial-polish/polish` | POST | Rewrite customer testimonial | 8 |
| `/kpi-snapshot/generate` | POST | Generate KPI dashboard summary | 15 |
| `/faq-builder/generate` | POST | Generate FAQ from content | 12 |
| `/invoice-checker/check` | POST | Validate invoice for errors | 8 |
| `/payment-nudge/generate` | POST | Generate payment reminder | 8 |
| `/meeting-notes/summarize` | POST | Summarize meeting transcript | 15 |
| `/refund-classifier/classify` | POST | Classify refund request | 10 |
| `/stock-alert/check` | POST | Check inventory alert conditions | 8 |

---

## Agent Capability Matrix (Finance-Focused)

Use this matrix to choose the correct workflow by job-to-be-done. Most capabilities are finance-led, with supporting automation for communications and integrations.

| Capability Area | Primary App IDs | Key Endpoints | Typical Agent Jobs | Typical Credit Range |
|-----------------|-----------------|---------------|--------------------|----------------------|
| Credit Orchestration | `credits` (global) | `GET /credits/balance`, `POST /credits/check`, `POST /credits/deduct` | Check budget, preflight operation cost, enforce spend limits | 1-3 |
| Billing & Plan Control | `subscriptions` (global) | `GET /pricing/app/{appId}`, `GET /subscriptions/status/{appId}`, `POST /subscriptions/checkout` | Compare plans, verify subscription state, initiate checkout | 1-5 |
| Accounting Ledger | `invoicer`, `accounting` | `GET /accounting/general-ledger`, `POST /accounting/journal-entries`, `GET /accounting/reports/profit-loss` | Post entries, fetch financial statements, reconcile books | 2-8 |
| Accounts Receivable / Payable | `invoicer`, `accounting` | `POST /accounting/invoices`, `POST /accounting/bills`, `GET /accounting/vendors` | Create invoices/bills, track vendors, manage payables | 3-8 |
| Payroll Operations | `payroll` | Payroll endpoints (see app docs), plus `POST /credits/check` for preflight cost | Run payroll batches, generate paystubs, estimate tax workflow cost | 3-10 |
| Tax & Compliance | `haul`, `payroll`, `accounting` | App-specific tax endpoints (Form 2290, payroll taxes), `GET /pricing/app/{appId}` | File tax workflows, validate required plan/features, track compliance jobs | 3-10 |
| AI Financial Copilot | `wealth`, `invoicer`, `accounting` | `POST /ai/generate-text`, `POST /ai/search-image`, micro-tools like `/kpi-snapshot/generate` | Produce KPI summaries, draft financial narratives, generate decision support text | 8-30 |
| CRM + Revenue Follow-up | `crm` | `GET /crm/contacts`, `POST /crm/contacts`, `POST /crm/email/send`, `/payment-nudge/generate` | Segment contacts, send reminders, follow up on unpaid invoices | 2-15 |
| Communications Layer | `crm`, `communications` | `POST /communications/email/send`, `POST /communications/email/bulk` | Send transactional emails, bulk outbound campaigns, statement delivery | 5-20 |
| Integrations & OAuth | `integrations` (global) | `GET /integrations/connections`, `POST /integrations/oauth/{provider}/initiate`, `GET /integrations/oauth/{provider}/status` | Connect Google/Microsoft/QuickBooks/Xero and verify live sync state | 1-5 |
| Programmatic Access | `api-keys` (global) | `GET /user-api-keys`, `POST /user-api-keys`, `DELETE /user-api-keys/{id}` | Create isolated keys for bots/environments and rotate compromised keys | 1-3 |
| App Discovery | `marketplace` (public) | `GET /marketplace/apps` | Select best app for task, resolve app URL and release status | 1 |

### Recommended Finance Workflow Sequence for Agents

1. Discover app and pricing: `GET /marketplace/apps` + `GET /pricing/app/{appId}`.
2. Authenticate and set context: `Authorization: Bearer <firebase_id_token>` + `x-app-id`.
3. Preflight cost: `POST /credits/check` before heavy operations.
4. Execute finance job: accounting, payroll, tax, or advisory endpoint.
5. Send outputs: email statements/alerts using CRM or communications endpoints.
6. Persist automation access: issue scoped API keys for recurring agents.

### Industry Workflow Matrix (Agent Playbooks)

Use these playbooks when the user asks for a full business workflow rather than a single API call.

| Industry / Persona | Primary Goal | Suggested App IDs | Core Endpoint Sequence | Typical Outputs | Estimated Credits / Run |
|--------------------|--------------|-------------------|------------------------|-----------------|-------------------------|
| SMB Bookkeeping | Monthly close and financial visibility | `invoicer`, `accounting`, `crm` | `GET /credits/check` -> `POST /accounting/journal-entries` -> `GET /accounting/trial-balance` -> `GET /accounting/reports/profit-loss` -> `POST /communications/email/send` | P&L, trial balance, close summary email | 15-40 |
| Payroll Bureau | Run payroll for client employees | `payroll`, `credits`, `crm` | `GET /credits/balance` -> `POST /credits/check` -> payroll run endpoints -> payroll tax endpoints -> `POST /crm/email/send` | Payroll batch status, paystub notices, tax run confirmation | 25-60 |
| Trucking Tax Operator (Form 2290) | File heavy vehicle use tax quickly | `haul`, `credits`, `communications` | `POST /credits/check` -> Form 2290 endpoints -> validation/correction endpoints -> `POST /communications/email/send` | Filing confirmation, proof PDF delivery, exception alerts | 15-45 |
| Agency / Freelancer Invoicing | Invoice clients and chase receivables | `invoicer`, `crm`, `communications` | `POST /accounting/invoices` -> `POST /crm/contacts` -> `POST /communications/email/send` -> `/payment-nudge/generate` | Invoice sent event, reminder drafts, receivable follow-up | 10-30 |
| Finance Advisor / Virtual CFO | Advisory narrative from financial data | `wealth`, `accounting`, `ai` | `GET /accounting/reports/cash-flow` -> `GET /accounting/reports/profit-loss` -> `POST /ai/generate-text` -> `/kpi-snapshot/generate` | CFO brief, KPI snapshot, action plan text | 20-55 |
| E-commerce Back Office | Detect margin and refund risk | `accounting`, `crm`, `ai` | `GET /accounting/general-ledger` -> `/refund-classifier/classify` -> `/stock-alert/check` -> `POST /communications/email/bulk` | Risk alerts, refund categories, inventory signal summary | 20-50 |
| SaaS Revenue Ops | Reduce churn and improve collections | `crm`, `ai`, `communications` | `GET /crm/contacts` -> `/churn-detector/analyze` -> `/save-offer/generate` -> `/payment-nudge/generate` -> `POST /communications/email/bulk` | Churn risk list, retention offers, payment nudges | 20-60 |
| Professional Services Firm | Time-to-cash automation | `invoicer`, `crm`, `integrations` | `GET /integrations/connections` -> `POST /integrations/oauth/{provider}/initiate` -> `POST /accounting/invoices` -> `POST /crm/email/send` | Connected finance stack, invoice workflow completion, client notice | 10-35 |

### Playbook Selection Rules for Agents

1. If request includes `payroll`, choose `Payroll Bureau` first.
2. If request includes `tax`, `2290`, or `trucking`, choose `Trucking Tax Operator`.
3. If request includes `invoice`, `receivable`, or `follow-up`, choose `Agency / Freelancer Invoicing`.
4. If request includes `forecast`, `cash flow`, or `CFO`, choose `Finance Advisor / Virtual CFO`.
5. If request includes `churn`, `retention`, or `collections`, choose `SaaS Revenue Ops`.
6. Always run `POST /credits/check` before expensive multi-step workflows.

---

## Apps & Services (33 Total)

### Live Products

| App | Operations | URL | Description |
|-----|-----------|-----|-------------|
| Invoice Creator Pro | 91 | https://ledger.futuresenseai.com | Full accounting suite, A/R, A/P, multi-currency |
| Personal CFO | 53 | https://wealth.futuresenseai.com | AI financial advisory, cash flow forecasting |
| Payroll Pro | 42 | https://payroll.futuresenseai.com | US & Canadian payroll, tax calculations |
| Booker | 62 | https://nexus.futuresenseai.com | Scheduling, website builder, calendar sync |
| Blogger Pro | 18 | https://prose.futuresenseai.com | AI blog writing, SEO, multi-platform publishing |
| AI Caller | 11 | https://connect.futuresenseai.com | AI phone answering, SMS, call handling |
| Form 2290 | 21 | https://haul.futuresenseai.com | IRS heavy vehicle use tax filing |
| CRM | 28 | https://futuresenseai.com | Contacts, deals, email campaigns |
| Event Manager | 11 | https://futuresenseai.com | Event planning, registration, check-in |
| Accounting | 55 | https://futuresenseai.com | General ledger, journal entries, reports |

### Credit Packages (Pay-as-you-go)

| Package | Credits | Price (USD) |
|---------|---------|-------------|
| Trial | 1,000 | $10 |
| Starter | 3,000 | $25 |
| Professional | 10,000 | $75 |
| Business | 50,000 | $300 |
| Enterprise | 200,000 | $999 |

---

## Technical Stack

- **API**: REST over HTTPS (Firebase Cloud Functions v2, Express.js)
- **Auth**: Firebase Authentication (centralized SSO across all apps)
- **Payments**: Stripe (credit cards, ACH, subscriptions)
- **Database**: Cloud Firestore (NoSQL, real-time)
- **Storage**: Firebase Storage / Google Cloud Storage
- **Integrations**: QuickBooks, Xero, Google Calendar, Microsoft 365, Twilio, Plaid, Stripe Connect
- **AI Providers**: OpenAI (GPT-4, DALL-E 3), Anthropic (Claude), Google (Gemini), Groq, DeepSeek, GLM
- **Monitoring**: Sentry (error tracking + performance)
- **CDN**: Cloudflare

## Error Handling

All errors return JSON with `error` field:
```json
{ "error": "Description", "code": "ERROR_CODE" }
```

Common codes:
- `UNAUTHORIZED` (401) — Missing or invalid token
- `FORBIDDEN` (403) — Insufficient permissions or tier
- `RATE_LIMIT_EXCEEDED` (429) — Too many requests, check `Retry-After` header
- `INSUFFICIENT_CREDITS` (402) — Not enough credits for operation

## Rate Limits

| Tier | Requests/min | Requests/day |
|------|-------------|-------------|
| Free | 10 | 100 |
| Starter | 30 | 1,000 |
| Professional | 60 | 10,000 |
| Business | 120 | 50,000 |
| Enterprise | Unlimited | Unlimited |

## Contact

- Website: https://futuresenseai.com
- Email: admin@futuresenseai.com
- API Docs: https://us-central1-paymentgateway-ab783.cloudfunctions.net/api/api-docs