AgentSurge Docs

API and Integration Reference

Use these endpoints to integrate the scanner, waitlist funnel, and deployment checks into your workflow.

Back to Landing Rules Center Join Waitlist

POST/api/audit

Run AI visibility checks for a domain and return score, grade, pillars, and top fixes.

curl -X POST https://agentsurge.io/api/audit \
  -H "Content-Type: application/json" \
  -d '{"domain":"shopify-store.com"}'

POST/api/waitlist

Create or update waitlist lead and send confirmation email when configured.

curl -X POST https://agentsurge.io/api/waitlist \
  -H "Content-Type: application/json" \
  -d '{"email":"team@example.com","website":"example.com","role":"CTO / Engineering Leader","source":"docs"}'

GET/api/health

Runtime health endpoint for deployment checks and environment readiness.

curl https://agentsurge.io/api/health

GET/api/track/click

Public touchpoint tracking endpoint. Records attribution and redirects, or returns JSON with mode=json.

curl "https://agentsurge.io/api/track/click?t=trk_abc123&mode=json&provider=openai&source=webmcp&ts=1730000000&sig=<hmac>"

POST/api/track/convert

Public conversion tracking endpoint. Supports signed JSON or form-urlencoded conversion events.

curl -X POST https://agentsurge.io/api/track/convert \
  -H "Content-Type: application/json" \
  -H "x-agentsurge-timestamp: 1730000000" \
  -H "x-agentsurge-signature: <hmac>" \
  -d '{"t":"trk_abc123","provider":"openai","orderRef":"ORD-1001","revenue":249.99,"currency":"USD","status":"confirmed"}'

POST/api/app/attribution/links/:id/sign

Authenticated helper endpoint that returns server-signed click URL and conversion request templates for a link.

curl -X POST https://agentsurge.io/api/app/attribution/links/<link-id>/sign \
  -H "Cookie: agentsurge_session=..."

POST/api/app/reports/weekly

Authenticated async trigger for weekly value report jobs used by the $39 Starter closure workflow.

curl -X POST https://agentsurge.io/api/app/reports/weekly \
  -H "Content-Type: application/json" \
  -H "Cookie: agentsurge_session=..." \
  -d '{"periodDays":7}'

POST/api/app/jobs/:id/retry

Authenticated control-plane action to requeue failed or canceled async jobs from Alerts.

curl -X POST https://agentsurge.io/api/app/jobs/<job-id>/retry \
  -H "Cookie: agentsurge_session=..."

POST/api/app/jobs/:id/cancel

Authenticated control-plane action to cancel queued/processing async jobs from Alerts.

curl -X POST https://agentsurge.io/api/app/jobs/<job-id>/cancel \
  -H "Cookie: agentsurge_session=..."

POST/api/internal/jobs/scheduler

Internal recurring scheduler endpoint that queues weekly reports, SOMV snapshots, and bulk audits by cadence.

curl -X POST https://agentsurge.io/api/internal/jobs/scheduler \
  -H "x-agentsurge-job-secret: $INTERNAL_JOB_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"limitUsers":120,"triggerWorker":true}'

Discovery Endpoints

/robots.txt
/sitemap.xml
/llms.txt
/.well-known/llms.txt
/openapi.json
/.well-known/security.txt
/humans.txt
/opengraph-image
/twitter-image
/sdk/agentsurge-tracking.js

Billing Integration (Polar)

Pricing CTAs are pre-wired to environment-based Polar checkout URLs. Set `NEXT_PUBLIC_POLAR_STARTER_CHECKOUT_URL`, `NEXT_PUBLIC_POLAR_GROWTH_CHECKOUT_URL`, and `NEXT_PUBLIC_POLAR_AGENCY_CHECKOUT_URL` and redeploy.

Tracking SDK

AgentSurge provides two SDK options for signed attribution: server-side TypeScript (`lib/tracking-sdk.ts`) and browser drop-in script (`/sdk/agentsurge-tracking.js`).

TypeScript (Server-side)

import { createSignedClickUrl, postSignedConversion } from "@/lib/tracking-sdk";

const clickUrl = await createSignedClickUrl({
  baseUrl: "https://agentsurge.io",
  trackingCode: "trk_abc123",
  secret: process.env.ATTRIBUTION_TRACKING_SECRET!,
  provider: "openai",
  source: "webmcp",
});

await postSignedConversion({
  baseUrl: "https://agentsurge.io",
  trackingCode: "trk_abc123",
  secret: process.env.ATTRIBUTION_TRACKING_SECRET!,
  provider: "openai",
  orderRef: "ORD-1001",
  revenue: 249.99,
  currency: "USD",
});

Browser (Drop-in)

<!-- 1) Load SDK -->
<script src="https://agentsurge.io/sdk/agentsurge-tracking.js"></script>
<script>
  // 2) Fetch a pre-signed click URL from your backend (recommended)
  //    Your backend keeps ATTRIBUTION_TRACKING_SECRET private.
  const { clickUrl } = await fetch("/api/my-signed-link").then((r) => r.json());
  location.href = clickUrl;
</script>

Keep the signing secret server-side. Frontend should consume pre-signed URLs/requests only.

Download Browser SDK

API Integration Assets

OpenAPI JSON security.txt