{"openapi":"3.1.0","info":{"title":"AgentSurge API","version":"0.3.0","description":"API surface for audits, dashboard site management, waitlist intake, and runtime health checks."},"servers":[{"url":"https://agentsurge.io"}],"paths":{"/api/audit":{"post":{"summary":"Run AI visibility audit","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"Domain or URL to audit.","examples":["shopify-store.com"]}},"required":["domain"]}}}},"responses":{"200":{"description":"Audit result"},"400":{"description":"Invalid payload"},"422":{"description":"Invalid domain"},"429":{"description":"Rate limited"}}}},"/api/audit/fix-plan":{"post":{"summary":"Generate prioritized remediation plan from audit findings","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","description":"Domain to audit and generate fixes for (used when audit payload is omitted)."},"platform":{"type":"string","enum":["shopify","wordpress","nextjs","generic"]},"preferAi":{"type":"boolean","description":"If true, attempts AI-blended fix guidance when enabled by env."},"audit":{"type":"object","description":"Existing audit result payload to avoid an extra audit call."}}}}}},"responses":{"200":{"description":"Fix plan generated"},"422":{"description":"Missing input (audit or domain)"},"429":{"description":"Rate limited"}}}},"/api/waitlist":{"post":{"summary":"Create or update waitlist lead","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"website":{"type":"string"},"role":{"type":"string"},"source":{"type":"string"},"utmSource":{"type":"string"},"utmMedium":{"type":"string"},"utmCampaign":{"type":"string"},"utmTerm":{"type":"string"},"utmContent":{"type":"string"}},"required":["email"]}}}},"responses":{"200":{"description":"Waitlist write successful"},"422":{"description":"Validation error"},"429":{"description":"Rate limited"}}}},"/api/health":{"get":{"summary":"Get runtime health status","responses":{"200":{"description":"Health payload"}}}},"/api/app/sites":{"get":{"summary":"List authenticated workspace sites","responses":{"200":{"description":"Site list"},"401":{"description":"Not authenticated"}}},"post":{"summary":"Add workspace site","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"website":{"type":"string","description":"Domain or URL to track."},"label":{"type":"string"}},"required":["website"]}}}},"responses":{"200":{"description":"Site created or resolved"},"401":{"description":"Not authenticated"},"422":{"description":"Validation error"}}}},"/api/app/sites/{id}/primary":{"post":{"summary":"Set primary workspace site","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Primary site updated"},"401":{"description":"Not authenticated"},"404":{"description":"Site not found"}}}},"/api/app/sites/{id}":{"post":{"summary":"Update or delete a workspace site","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["update_label","delete"]},"label":{"type":"string"}},"required":["action"]}}}},"responses":{"200":{"description":"Site updated or deleted"},"401":{"description":"Not authenticated"},"404":{"description":"Site not found"}}}},"/api/app/audits/run":{"post":{"summary":"Run and persist dashboard audit","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"siteId":{"type":"string","format":"uuid"},"domain":{"type":"string"}}}}}},"responses":{"200":{"description":"Audit run and persisted"},"401":{"description":"Not authenticated"},"422":{"description":"No site configured"}}}},"/api/app/audits/run-all":{"post":{"summary":"Queue asynchronous bulk dashboard audits for all tracked sites","responses":{"200":{"description":"Bulk audit job queued"},"401":{"description":"Not authenticated"},"422":{"description":"No site configured"}}}},"/api/app/endpoints":{"get":{"summary":"List endpoint configuration rows for authenticated user","responses":{"200":{"description":"Endpoint configuration list"},"401":{"description":"Not authenticated"}}},"post":{"summary":"Update one endpoint configuration row","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"configId":{"type":"string","format":"uuid"},"routePath":{"type":"string"},"httpMethod":{"type":"string"},"enabled":{"type":"boolean"}},"required":["configId"]}}}},"responses":{"200":{"description":"Endpoint row updated"},"401":{"description":"Not authenticated"},"404":{"description":"Config not found"}}}},"/api/app/endpoints/autofix":{"post":{"summary":"Apply endpoint automation actions","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["apply_recommended","disable_all"]}},"required":["action"]}}}},"responses":{"200":{"description":"Endpoint automation applied"},"401":{"description":"Not authenticated"},"422":{"description":"Invalid action or no endpoint configs"}}}},"/api/app/endpoints/probe":{"post":{"summary":"Execute endpoint probe validation (with optional replay)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"configId":{"type":"string","format":"uuid"},"replayRunId":{"type":"string","format":"uuid"}},"required":["configId"]}}}},"responses":{"200":{"description":"Probe completed and persisted"},"401":{"description":"Not authenticated"},"422":{"description":"Missing configId"}}}},"/api/app/somv/trackers":{"get":{"summary":"List SOMV trackers for authenticated user","responses":{"200":{"description":"Tracker list"},"401":{"description":"Not authenticated"}}},"post":{"summary":"Create SOMV tracker","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"siteId":{"type":"string","format":"uuid"},"provider":{"type":"string"},"keyword":{"type":"string"},"region":{"type":"string"},"samplingMode":{"type":"string","enum":["heuristic","provider_live"]},"competitors":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["siteId","provider","keyword"]}}}},"responses":{"200":{"description":"Tracker created"},"401":{"description":"Not authenticated"},"422":{"description":"Validation error"}}}},"/api/app/somv/trackers/{id}":{"post":{"summary":"Toggle active state or delete SOMV tracker","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["toggle_active","delete"]},"isActive":{"type":"boolean"}},"required":["action"]}}}},"responses":{"200":{"description":"Tracker updated or deleted"},"401":{"description":"Not authenticated"},"404":{"description":"Tracker not found"}}}},"/api/app/somv/run":{"post":{"summary":"Queue asynchronous SOMV snapshot generation from latest audits","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"trackerId":{"type":"string","format":"uuid"},"samplingMode":{"type":"string","enum":["heuristic","provider_live"]}}}}}},"responses":{"200":{"description":"Snapshot job queued"},"401":{"description":"Not authenticated"}}}},"/api/app/agency/exports/bulk":{"get":{"summary":"List agency bulk export jobs","responses":{"200":{"description":"Bulk export job list"},"401":{"description":"Not authenticated"},"403":{"description":"Plan requires agency tier"}}},"post":{"summary":"Queue agency bulk export generation","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","enum":["all","client","site"]},"format":{"type":"string","enum":["pdf","csv"]},"period":{"type":"number"},"client":{"type":"string"},"siteIds":{"type":"array","items":{"type":"string","format":"uuid"}},"brandName":{"type":"string"},"agencyName":{"type":"string"},"accent":{"type":"string"},"footer":{"type":"string"},"showPoweredBy":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Bulk export job queued"},"401":{"description":"Not authenticated"},"403":{"description":"Plan requires agency tier"},"422":{"description":"No export targets in selected scope"}}}},"/api/internal/jobs/worker":{"get":{"summary":"Process queued async jobs via query params (internal worker endpoint)","responses":{"200":{"description":"Worker batch completed"},"401":{"description":"Invalid internal worker secret"},"503":{"description":"Worker secret not configured"}}},"post":{"summary":"Process queued async jobs (internal worker endpoint)","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"number"},"workerId":{"type":"string"},"schedule":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Worker batch completed"},"401":{"description":"Invalid internal worker secret"},"503":{"description":"Worker secret not configured"}}}},"/api/internal/jobs/scheduler":{"get":{"summary":"Plan and queue recurring async jobs (internal scheduler endpoint)","responses":{"200":{"description":"Scheduler run completed"},"401":{"description":"Invalid internal scheduler secret"},"503":{"description":"Scheduler secret not configured"}}},"post":{"summary":"Run recurring async scheduler and optionally dispatch worker","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"limitUsers":{"type":"number"},"dryRun":{"type":"boolean"},"triggerWorker":{"type":"boolean"},"workerLimit":{"type":"number"}}}}}},"responses":{"200":{"description":"Scheduler run completed"},"401":{"description":"Invalid internal scheduler secret"},"503":{"description":"Scheduler secret not configured"}}}},"/api/app/jobs/{id}/retry":{"post":{"summary":"Retry a failed/canceled/completed async job for the authenticated workspace","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Job re-queued"},"401":{"description":"Not authenticated"},"404":{"description":"Job not found"},"409":{"description":"Job not retryable in current state"}}}},"/api/app/jobs/{id}/cancel":{"post":{"summary":"Cancel a queued/processing async job for the authenticated workspace","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Job canceled"},"401":{"description":"Not authenticated"},"409":{"description":"Job not cancelable in current state"}}}},"/api/app/settings":{"post":{"summary":"Update profile or workspace settings","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["profile","workspace","agency_profile"]},"name":{"type":"string"},"primarySiteId":{"type":"string","format":"uuid"},"companyName":{"type":"string"},"billingEmail":{"type":"string","format":"email"},"alertEmail":{"type":"string","format":"email"},"planTier":{"type":"string","enum":["free","starter","growth","agency","enterprise"]},"weeklyReportEnabled":{"type":"boolean"}},"required":["action"]}}}},"responses":{"200":{"description":"Settings updated"},"401":{"description":"Not authenticated"},"422":{"description":"Invalid action/payload"}}}},"/api/app/billing/checkout":{"post":{"summary":"Create authenticated Polar checkout redirect for selected plan","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"plan":{"type":"string","enum":["starter","growth","agency"]},"redirect":{"type":"string"}},"required":["plan"]}}}},"responses":{"303":{"description":"Redirect to Polar checkout"},"400":{"description":"Invalid payload"},"401":{"description":"Not authenticated"}}}},"/api/app/billing/portal":{"post":{"summary":"Create authenticated Polar customer portal redirect for current subscription","requestBody":{"required":false,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"redirect":{"type":"string"}}}}}},"responses":{"303":{"description":"Redirect to Polar customer portal"},"400":{"description":"Invalid payload"},"401":{"description":"Not authenticated"}}}},"/api/app/reports/weekly":{"post":{"summary":"Queue weekly value report async job","requestBody":{"required":false,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"periodDays":{"type":"integer","minimum":7,"maximum":31},"redirect":{"type":"string"}}}},"application/json":{"schema":{"type":"object","properties":{"periodDays":{"type":"integer","minimum":7,"maximum":31},"redirect":{"type":"string"}}}}}},"responses":{"200":{"description":"Weekly report job queued"},"303":{"description":"Redirect after form submit"},"400":{"description":"Invalid payload"},"401":{"description":"Not authenticated"}}}},"/api/app/attribution/export":{"get":{"summary":"Export attribution report (CSV or PDF)","parameters":[{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["csv","pdf"]}},{"name":"period","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":90}}],"responses":{"200":{"description":"Attribution export file"},"401":{"description":"Not authenticated"}}}},"/api/app/attribution/links":{"get":{"summary":"List authenticated attribution links","responses":{"200":{"description":"Attribution links list"},"401":{"description":"Not authenticated"}}},"post":{"summary":"Create an attribution tracking link","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"siteId":{"type":"string","format":"uuid"},"destinationUrl":{"type":"string","format":"uri"},"provider":{"type":"string"},"channel":{"type":"string"},"campaign":{"type":"string"}},"required":["destinationUrl"]}}}},"responses":{"200":{"description":"Tracking link created"},"401":{"description":"Not authenticated"},"422":{"description":"Validation error"}}}},"/api/app/attribution/links/{id}/sign":{"post":{"summary":"Generate server-signed click URL + conversion payload template for an attribution link","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string"},"source":{"type":"string"},"mode":{"type":"string","enum":["json"]},"revenue":{"type":"number"},"currency":{"type":"string"},"status":{"type":"string"},"orderRef":{"type":"string"},"touchpointId":{"type":"string"},"occurredAt":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Signed SDK payload generated"},"401":{"description":"Not authenticated"},"404":{"description":"Attribution link not found"},"503":{"description":"Tracking signing secret not configured"}}}},"/api/app/attribution/touchpoints":{"get":{"summary":"List attribution touchpoints","responses":{"200":{"description":"Touchpoint list"},"401":{"description":"Not authenticated"}}},"post":{"summary":"Record an attribution touchpoint (authenticated)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"trackingCode":{"type":"string"},"linkId":{"type":"string","format":"uuid"},"provider":{"type":"string"},"sourceType":{"type":"string"},"sessionKey":{"type":"string"},"visitorKey":{"type":"string"}}}}}},"responses":{"200":{"description":"Touchpoint recorded"},"401":{"description":"Not authenticated"}}}},"/api/app/attribution/conversions":{"get":{"summary":"List attribution conversions","responses":{"200":{"description":"Conversion list"},"401":{"description":"Not authenticated"}}},"post":{"summary":"Record an attribution conversion (authenticated)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"trackingCode":{"type":"string"},"orderRef":{"type":"string"},"revenue":{"type":"number"},"currency":{"type":"string"},"status":{"type":"string"}}}}}},"responses":{"200":{"description":"Conversion recorded"},"401":{"description":"Not authenticated"}}}},"/api/app/integrations/shopify/connect":{"get":{"summary":"List Shopify shop connections for authenticated workspace","responses":{"200":{"description":"Shopify connections list"},"401":{"description":"Not authenticated"}}},"post":{"summary":"Bind Shopify shop and optionally register webhooks","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shopDomain":{"type":"string","description":"my-store.myshopify.com"},"siteId":{"type":"string","format":"uuid"},"accessToken":{"type":"string"},"registerWebhooks":{"type":"boolean"}},"required":["shopDomain"]}}}},"responses":{"200":{"description":"Shopify connection saved"},"401":{"description":"Not authenticated"},"422":{"description":"Validation error"}}}},"/api/app/integrations/shopify/install":{"get":{"summary":"Start Shopify OAuth install and redirect to Shopify authorization","parameters":[{"name":"shopDomain","in":"query","required":true,"schema":{"type":"string"}},{"name":"siteId","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"redirect","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"303":{"description":"Redirect to Shopify OAuth authorization"},"401":{"description":"Not authenticated"},"500":{"description":"Shopify client config missing"}}},"post":{"summary":"Form adapter to start Shopify OAuth install","requestBody":{"required":false,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"shopDomain":{"type":"string"},"siteId":{"type":"string","format":"uuid"},"redirect":{"type":"string"}}}}}},"responses":{"303":{"description":"Redirect to install GET route"},"401":{"description":"Not authenticated"}}}},"/api/app/integrations/shopify/callback":{"get":{"summary":"Handle Shopify OAuth callback, store token, and register core webhooks","parameters":[{"name":"shop","in":"query","required":true,"schema":{"type":"string"}},{"name":"code","in":"query","required":true,"schema":{"type":"string"}},{"name":"state","in":"query","required":true,"schema":{"type":"string"}},{"name":"hmac","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"303":{"description":"Redirect back to settings with status or error"},"500":{"description":"Shopify client config missing"}}}},"/api/app/integrations/shopify/llms-access":{"post":{"summary":"Update Shopify llms feed visibility and token protection","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string","format":"uuid"},"llmsVisibility":{"type":"string","enum":["public","private"]},"llmsToken":{"type":"string"},"rotateToken":{"type":"boolean"}},"required":["connectionId","llmsVisibility"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"connectionId":{"type":"string","format":"uuid"},"llmsVisibility":{"type":"string","enum":["public","private"]},"llmsToken":{"type":"string"},"rotateToken":{"type":"string"},"redirect":{"type":"string"}},"required":["connectionId","llmsVisibility"]}}}},"responses":{"200":{"description":"llms access settings updated"},"303":{"description":"Redirected to settings when using form posts"},"401":{"description":"Not authenticated"},"422":{"description":"Validation error"}}}},"/api/app/integrations/shopify/llms-access/flash":{"post":{"summary":"Consume/clear one-time llms token reveal flash cookie","responses":{"200":{"description":"Flash cookie cleared"}}}},"/api/track/click":{"get":{"summary":"Public touchpoint tracking endpoint with redirect","parameters":[{"name":"t","in":"query","required":true,"schema":{"type":"string"},"description":"Attribution tracking code."},{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["openai","claude","grok","gemini","perplexity","openclaw","unknown"]},"description":"Optional provider label override for the touchpoint."},{"name":"source","in":"query","required":false,"schema":{"type":"string","enum":["webmcp","llms_txt","crawler","direct","manual","unknown"]},"description":"Optional source type override for attribution touchpoint."},{"name":"session","in":"query","required":false,"schema":{"type":"string"}},{"name":"visitor","in":"query","required":false,"schema":{"type":"string"}},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["json"]},"description":"Set mode=json to return JSON instead of redirect."},{"name":"utm_source","in":"query","required":false,"schema":{"type":"string"}},{"name":"utm_medium","in":"query","required":false,"schema":{"type":"string"}},{"name":"utm_campaign","in":"query","required":false,"schema":{"type":"string"}},{"name":"utm_content","in":"query","required":false,"schema":{"type":"string"}},{"name":"utm_term","in":"query","required":false,"schema":{"type":"string"}},{"name":"ts","in":"query","required":false,"schema":{"type":"string"},"description":"Unix timestamp used for signature validation (required when signature enforcement is enabled)."},{"name":"sig","in":"query","required":false,"schema":{"type":"string"},"description":"Hex HMAC-SHA256 signature (required when signature enforcement is enabled)."},{"name":"x-agentsurge-timestamp","in":"header","required":false,"schema":{"type":"string"},"description":"Header alternative to ts query parameter."},{"name":"x-agentsurge-signature","in":"header","required":false,"schema":{"type":"string"},"description":"Header alternative to sig query parameter."}],"responses":{"200":{"description":"JSON touchpoint response when mode=json"},"307":{"description":"Redirected to tracked destination"},"400":{"description":"Missing tracking code"},"401":{"description":"Invalid signature"},"404":{"description":"Tracking link not found"},"429":{"description":"Rate limited"}}}},"/api/track/convert":{"post":{"summary":"Public conversion tracking endpoint","parameters":[{"name":"ts","in":"query","required":false,"schema":{"type":"string"},"description":"Unix timestamp used for signature validation (required when signature enforcement is enabled)."},{"name":"sig","in":"query","required":false,"schema":{"type":"string"},"description":"Hex HMAC-SHA256 signature (required when signature enforcement is enabled)."},{"name":"x-agentsurge-timestamp","in":"header","required":false,"schema":{"type":"string"},"description":"Header alternative to ts query parameter."},{"name":"x-agentsurge-signature","in":"header","required":false,"schema":{"type":"string"},"description":"Header alternative to sig query parameter."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"t":{"type":"string","description":"Tracking code"},"orderRef":{"type":"string"},"revenue":{"type":"number"},"currency":{"type":"string"},"status":{"type":"string"}},"required":["t"]}},"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"t":{"type":"string","description":"Tracking code"},"orderRef":{"type":"string"},"revenue":{"type":"number"},"currency":{"type":"string"},"status":{"type":"string"},"provider":{"type":"string"},"touchpointId":{"type":"string"},"occurredAt":{"type":"string","format":"date-time"}},"required":["t"]}}}},"responses":{"201":{"description":"Conversion recorded"},"400":{"description":"Invalid conversion payload"},"401":{"description":"Invalid signature"},"404":{"description":"Tracking link not found"},"422":{"description":"Tracking code missing"},"429":{"description":"Rate limited"}}}},"/api/webhooks/shopify":{"post":{"summary":"Shopify webhook receiver with HMAC validation and idempotent processing","responses":{"200":{"description":"Webhook processed or ignored"},"202":{"description":"Shop not bound in workspace"},"401":{"description":"Invalid signature"},"500":{"description":"Processing failure"}}}},"/api/webhooks/polar":{"post":{"summary":"Polar billing webhook receiver with signature validation, idempotency, and plan sync","responses":{"200":{"description":"Billing webhook processed or duplicate acknowledged"},"202":{"description":"Event ignored (user could not be resolved)"},"401":{"description":"Invalid signature"},"500":{"description":"Processing failure"}}}}}}