{"openapi":"3.1.0","info":{"title":"Admin Substitute API","version":"1.0.0","description":"AI-native trade business management platform API. Manages leads, quotes, jobs, clients, invoicing, and financials for Australian trade businesses. Designed for autonomous AI agent operation.","contact":{"email":"hello@adminsubstitute.com","url":"https://adminsubstitute.com"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://adminsubstitute.com/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key with ask_ prefix. Obtain via POST /api/v1/onboard or the developer portal."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}},"Lead":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"phone":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"serviceType":{"type":"string","nullable":true},"status":{"type":"string","enum":["New","Contacted","Qualified","Quoted","Won","Lost"]},"priority":{"type":"string","enum":["Low","Normal","High","Urgent"]},"message":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"suburb":{"type":"string","nullable":true},"source":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"Quote":{"type":"object","properties":{"id":{"type":"string"},"quoteNumber":{"type":"string"},"status":{"type":"string","enum":["Draft","Sent","Viewed","Accepted","Declined","Expired"]},"total":{"type":"number"},"clientName":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"Job":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["Scheduled","In Progress","Completed","Cancelled"]},"scheduledDate":{"type":"string","format":"date-time","nullable":true},"address":{"type":"string","nullable":true},"amount":{"type":"number","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"Client":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"OnboardRequest":{"type":"object","required":["business_name","email","plan"],"properties":{"business_name":{"type":"string","description":"Name of the trade business","minLength":2},"email":{"type":"string","format":"email","description":"Primary contact email"},"plan":{"type":"string","enum":["free","starter","professional","business"],"description":"Plan to subscribe to"},"contact_name":{"type":"string","description":"Name of the primary contact"},"trade_type":{"type":"string","description":"Type of trade (e.g. plumbing, electrical)"},"phone":{"type":"string"},"abn":{"type":"string","description":"Australian Business Number"},"password":{"type":"string","description":"Account password. If omitted, one is auto-generated."},"referral_code":{"type":"string"},"api_key_name":{"type":"string","description":"Label for the API key"},"billing_cycle":{"type":"string","enum":["monthly","yearly"],"description":"Billing frequency (default: monthly)"},"stripe_payment_method_id":{"type":"string","description":"Stripe payment method token for immediate subscription activation"}}},"OnboardResponse":{"type":"object","properties":{"company_id":{"type":"string"},"user_id":{"type":"string"},"email":{"type":"string"},"api_key":{"type":"string","description":"API key — shown once. Store securely."},"api_key_prefix":{"type":"string"},"plan":{"type":"object"},"endpoints":{"type":"object"},"message":{"type":"string"}}},"BillingResponse":{"type":"object","properties":{"company_id":{"type":"string"},"plan":{"type":"object"},"subscription":{"type":"object"},"trial":{"type":"object","nullable":true},"actions":{"type":"object"}}},"UsageResponse":{"type":"object","properties":{"company_id":{"type":"string"},"plan":{"type":"string"},"period":{"type":"object"},"usage":{"type":"object"},"resources":{"type":"object"}}}}},"paths":{"/onboard":{"post":{"operationId":"onboard","summary":"Programmatic signup","description":"Create a company account, user, and API key in one call. No authentication required.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardRequest"}}}},"responses":{"201":{"description":"Account created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardResponse"}}}},"400":{"description":"Validation error"},"409":{"description":"Email already registered"},"429":{"description":"Rate limited"}}}},"/leads":{"get":{"operationId":"listLeads","summary":"List leads","description":"Returns paginated leads for the authenticated company.","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"priority","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Lead list","content":{"application/json":{"schema":{"type":"object","properties":{"leads":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"total":{"type":"integer"}}}}}}}},"post":{"operationId":"createLead","summary":"Create a lead","description":"Create a new lead in the pipeline.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"serviceType":{"type":"string"},"message":{"type":"string"},"address":{"type":"string"},"suburb":{"type":"string"},"source":{"type":"string"},"priority":{"type":"string"}}}}}},"responses":{"201":{"description":"Lead created"}}}},"/quotes":{"get":{"operationId":"listQuotes","summary":"List quotes","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Quote list"}}}},"/jobs":{"get":{"operationId":"listJobs","summary":"List jobs","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Job list"}}}},"/clients":{"get":{"operationId":"listClients","summary":"List clients","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Client list"}}}},"/financials":{"get":{"operationId":"getFinancials","summary":"Get financial summary","description":"Revenue, outstanding invoices, and cash flow metrics.","responses":{"200":{"description":"Financial summary"}}}},"/plans":{"get":{"operationId":"listPlans","summary":"List available plans","description":"Public endpoint — returns all active plans with pricing, features, limits, and feature flags. No authentication required.","security":[],"responses":{"200":{"description":"List of plans with pricing"}}}},"/billing":{"get":{"operationId":"getBilling","summary":"Get billing status","description":"Current plan, subscription status, trial info, payment actions.","responses":{"200":{"description":"Billing info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingResponse"}}}}}}},"/billing/checkout":{"post":{"operationId":"createCheckout","summary":"Create checkout session","description":"Creates a Stripe Checkout session for purchasing or upgrading a plan. Returns a URL for the human operator to complete payment.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["plan_slug"],"properties":{"plan_slug":{"type":"string","description":"Plan slug to purchase"},"billing_cycle":{"type":"string","enum":["monthly","yearly"],"description":"Billing cycle (default: monthly)"}}}}}},"responses":{"200":{"description":"Checkout URL and session ID"}}}},"/billing/portal":{"post":{"operationId":"createPortal","summary":"Create billing portal session","description":"Creates a Stripe Billing Portal session for the human to manage subscription, payment methods, and invoices.","responses":{"200":{"description":"Portal URL"}}}},"/usage":{"get":{"operationId":"getUsage","summary":"Get usage metrics","description":"Current-period usage vs plan limits. API calls, SMS, emails, LLM calls, resource counts.","responses":{"200":{"description":"Usage metrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}}}}},"/mcp":{"post":{"operationId":"mcpRequest","summary":"MCP server endpoint","description":"Model Context Protocol endpoint for AI agent integration. Requires mcpAccess feature flag.","responses":{"200":{"description":"MCP response"}}}},"/webhooks":{"get":{"operationId":"listWebhooks","summary":"List webhook subscriptions","responses":{"200":{"description":"Webhook list"}}},"post":{"operationId":"createWebhook","summary":"Register a webhook","description":"Subscribe to real-time events (lead.created, quote.sent, job.completed, payment.received).","responses":{"201":{"description":"Webhook created"}}}},"/docs":{"get":{"operationId":"getDocs","summary":"API documentation","description":"Comprehensive API documentation with examples, quick-start guide, and error codes.","security":[],"responses":{"200":{"description":"API documentation JSON"}}}},"/openapi.json":{"get":{"operationId":"getOpenApiSpec","summary":"OpenAPI specification","description":"This document. Machine-readable API specification.","security":[],"responses":{"200":{"description":"OpenAPI 3.1 spec"}}}}}}