{"name":"Admin Substitute API Documentation","version":"1.0.0","base_url":"https://adminsubstitute.com/api/v1","description":"AI-native trade business management platform. This API lets AI agents programmatically manage Australian trade businesses — leads, quoting, job scheduling, invoicing, client management, and financials.","quick_start":{"steps":[{"step":1,"title":"Create an account","description":"POST to /onboard with your business details. You get back an API key.","example":{"method":"POST","url":"https://adminsubstitute.com/api/v1/onboard","headers":{"Content-Type":"application/json"},"body":{"business_name":"Smith Plumbing","email":"agent@smithplumbing.com.au","plan":"starter","trade_type":"plumbing","contact_name":"John Smith"}}},{"step":2,"title":"Store your API key","description":"The api_key field in the response is shown ONCE. Store it securely. It starts with ask_."},{"step":3,"title":"Make authenticated requests","description":"Include your API key as a Bearer token in the Authorization header.","example":{"method":"GET","url":"https://adminsubstitute.com/api/v1/leads","headers":{"Authorization":"Bearer ask_your_key_here"}}},{"step":4,"title":"Monitor usage","description":"Check /billing for plan info and /usage for current consumption vs limits."}]},"authentication":{"type":"Bearer token","header":"Authorization","format":"Bearer ask_...","description":"All authenticated endpoints require a valid API key. Obtain one via POST /onboard or the web developer portal. The key uses the ask_ prefix and is hashed server-side (SHA-256). Include it as: Authorization: Bearer ask_yourKeyHere","rate_limits":{"description":"Rate limits are plan-dependent. Check /usage for current consumption.","default":"1000 API calls/month on starter, 5000 on professional, 25000 on business."}},"endpoints":{"onboarding":{"POST /onboard":{"auth":"none","description":"Create a new account programmatically. Returns company_id, user_id, api_key, plan details, and all endpoint URLs.","request_body":{"required":{"business_name":"string (min 2 chars)","email":"valid email","plan":"free | starter | professional | business"},"optional":{"contact_name":"string","trade_type":"string (e.g. plumbing, electrical)","phone":"string","abn":"string","password":"string (auto-generated if omitted)","referral_code":"string","api_key_name":"string","billing_cycle":"monthly | yearly (default: monthly)","stripe_payment_method_id":"Stripe PM token for immediate subscription activation"}},"responses":{"201":"Account created with api_key, company_id, subscription details","400":"Validation error or invalid plan","409":"Email already registered","429":"Rate limited"}}},"leads":{"GET /leads":{"auth":"Bearer token, scope: leads","description":"List leads with optional filters. Returns paginated results.","query_params":{"status":"New | Contacted | Qualified | Quoted | Won | Lost","priority":"Low | Normal | High | Urgent","limit":"int (default 50, max 100)","offset":"int (default 0)"},"response":"{ leads: Lead[], total: int, limit: int, offset: int }"},"POST /leads":{"auth":"Bearer token, scope: leads, permission: write","description":"Create a new lead.","request_body":{"required":{"name":"string"},"optional":{"phone":"string","email":"string","serviceType":"string","message":"string","address":"string","suburb":"string","source":"string","priority":"Low | Normal | High | Urgent"}},"response":"{ lead: Lead }"}},"quotes":{"GET /quotes":{"auth":"Bearer token, scope: quotes","description":"List quotes with optional status filter.","query_params":{"status":"Draft | Sent | Viewed | Accepted | Declined | Expired","limit":"int","offset":"int"}}},"jobs":{"GET /jobs":{"auth":"Bearer token, scope: jobs","description":"List jobs with optional status filter.","query_params":{"status":"Scheduled | In Progress | Completed | Cancelled","limit":"int","offset":"int"}}},"clients":{"GET /clients":{"auth":"Bearer token, scope: clients","description":"List clients (leads with completed jobs).","query_params":{"limit":"int","offset":"int"}}},"financials":{"GET /financials":{"auth":"Bearer token, scope: financials","description":"Financial summary — revenue, outstanding invoices, cash flow metrics.","query_params":{"days":"int (lookback period, default 30)"}}},"billing":{"GET /billing":{"auth":"Bearer token","description":"Current plan, subscription status, trial info, Stripe portal link.","response":"{ company_id, plan, subscription, trial, actions }"}},"usage":{"GET /usage":{"auth":"Bearer token","description":"Current-period usage vs plan limits. API calls, SMS, emails, LLM calls, users, resource counts.","response":"{ company_id, plan, period, usage, resources }"}},"mcp":{"POST /mcp":{"auth":"Bearer token (requires mcpAccess feature flag)","description":"MCP (Model Context Protocol) endpoint for AI agent integration. Supports JSON-RPC 2.0 with methods: initialize, tools/list, tools/call, resources/list, resources/read. Stateless — each request is independently authenticated.","protocol_version":"2024-11-05","supported_methods":["initialize","tools/list","tools/call","resources/list","resources/read"],"example":{"method":"POST","url":"https://adminsubstitute.com/api/v1/mcp","headers":{"Authorization":"Bearer ask_yourKey","Content-Type":"application/json"},"body":{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}},"available_tools":["list_leads","create_lead","list_quotes","create_quote","list_jobs","create_job","get_financials","list_clients"]},"GET /mcp":{"auth":"none","description":"MCP server discovery — returns server info, available tools, and resources."}},"webhooks":{"GET /webhooks":{"auth":"Bearer token (requires webhookInbound feature flag)","description":"List registered webhook subscriptions."},"POST /webhooks":{"auth":"Bearer token (requires webhookInbound feature flag)","description":"Register a webhook URL to receive real-time events.","supported_events":["lead.created","lead.updated","quote.sent","quote.accepted","job.completed","job.scheduled","payment.received","invoice.sent"]}},"discovery":{"GET /openapi.json":{"auth":"none","description":"OpenAPI 3.1 specification. Machine-readable API schema."},"GET /docs":{"auth":"none","description":"This document. Comprehensive API documentation."},"GET /.well-known/agent-card.json":{"auth":"none","description":"A2A Agent Card for AI agent discovery. Located at the domain root.","url":"https://adminsubstitute.com/.well-known/agent-card.json"}}},"protocols":{"rest":{"description":"Standard REST API with JSON request/response. All endpoints under /api/v1/.","content_type":"application/json"},"mcp":{"description":"Model Context Protocol (MCP) over HTTP. JSON-RPC 2.0 transport. Stateless — no session management needed. Each request authenticated independently via Bearer token.","endpoint":"https://adminsubstitute.com/api/v1/mcp","version":"2024-11-05","transport":"HTTP POST (JSON-RPC 2.0)"},"webhooks":{"description":"Register webhook URLs to receive real-time event notifications. Events are POST-ed as JSON to your URL with HMAC-SHA256 signature verification.","endpoint":"https://adminsubstitute.com/api/v1/webhooks"}},"plans":{"free":{"price":"$0/mo","api_calls":100,"features":"Basic lead capture, limited quoting"},"starter":{"price":"$49/mo AUD","api_calls":1000,"features":"Lead management, quoting, job tracking, REST API (read-only)"},"professional":{"price":"$149/mo AUD","api_calls":5000,"features":"Full automation, AI features, team management, REST API (read+write)"},"business":{"price":"$299/mo AUD","api_calls":25000,"features":"Everything + MCP server, webhooks, advanced analytics, priority support"}},"error_codes":{"validation_error":"400 — Request body failed validation. Check messages array.","invalid_plan":"400 — Plan slug not found. Check available_plans in response.","unauthorized":"401 — Missing or invalid API key.","forbidden":"403 — API key lacks required scope or feature flag.","email_taken":"409 — Email already registered.","rate_limited":"429 — Too many requests. Check retry_after_seconds.","internal_error":"500 — Server error. Retry or contact support."},"support":{"email":"hello@adminsubstitute.com","website":"https://adminsubstitute.com","agent_card":"https://adminsubstitute.com/.well-known/agent-card.json"}}