API Documentation
Integrate Sovereign AI with your existing systems. Access leads, bookings, invoices, analytics, embeddable widgets, webhooks, and Zapier triggers programmatically.
Authentication
Most API endpoints require authentication. The method depends on the endpoint group:
- REST API & Zapier -- Bearer token in the Authorization header. Generate keys from Dashboard → Settings → API Keys.
- Session -- HTTP-only cookie set by the auth endpoints (magic link or Google OAuth).
- Webhooks -- Signature verification using the service-specific secret (e.g., STRIPE_WEBHOOK_SECRET).
- Portal & Field -- Scoped magic-link sessions for customers and technicians.
curl -H "Authorization: Bearer sk_live_abc123..." \
https://www.trysovereignai.com/api/v1/leadsRate Limits
All endpoints are rate limited. Exceeded requests return 429 Too Many Requests with a Retry-After header.
- REST API (v1): 100 requests/min per API key
- Zapier auth: 30 requests/hour per IP
- Health check: 30 requests/min per IP
- Deep health: 60 requests/min per IP
- Embed widgets: Served at the edge, no explicit rate limit
Response Format
REST API v1 endpoints return JSON with a consistent envelope:
{
"data": [ ... ],
"pagination": {
"page": 1,
"pageSize": 50,
"total": 142,
"totalPages": 3
}
}Authentication
Public endpoints for user authentication. Magic-link and Google OAuth flows. No API key required for initiating auth -- session cookies are set on success.
/api/auth/send-magic-linkSend a magic-link email to the given address
/api/auth/verifyVerify a magic-link token and create a session
/api/auth/googleInitiate Google OAuth flow (redirects to Google)
/api/auth/google/callbackGoogle OAuth callback -- sets session cookie on success
/api/auth/sessionReturn the current session (or null)
/api/auth/signoutSign out and clear the session cookie
/api/auth/rotate-sessionRotate the session token for the current user
/api/auth/sessionsList all active sessions for the current user
/api/auth/sessionsRevoke one or all sessions
Webhooks (Inbound)
Endpoints that receive events from third-party services. Each webhook validates its own signature or secret. Do not call these directly -- they are triggered by the respective service.
/api/payments/webhooks/stripeStripe payment and subscription events (signature verified via STRIPE_WEBHOOK_SECRET)
/api/webhooks/sendgridSendGrid email event notifications (opens, clicks, bounces, spam reports)
/api/webhooks/sendgrid/inboundSendGrid inbound parse -- receive emails as HTTP POSTs
/api/webhooks/telegramTelegram bot incoming message webhook
/api/services/voice/inboundTwilio voice inbound call webhook (TwiML response)
Embed Widgets
JavaScript widget bundles served at the edge. Embed them on any website with a single script tag. Each widget reads a data-* attribute for configuration.
/embed/chatbot.jsAI chatbot widget -- add <script data-chatbot-id="..."> to any page
/embed/booking.jsOnline booking widget -- lets visitors schedule appointments
/embed/reviews.jsReview showcase widget -- displays recent 5-star reviews
/embed/estimate.jsInstant estimate widget -- visitors get a price range for their project
/embed/social-proof.jsSocial proof toast notifications ("John from Dallas just booked...")
Zapier API (v1)
Endpoints consumed by the Sovereign AI Zapier integration. Authenticate with your API key (Bearer sk_live_xxx). Triggers use polling; Zapier calls them every few minutes.
/api/v1/zapier/authZapier authentication test -- verifies the API key is valid
/api/v1/zapier/triggers/new-leadTrigger: fires when a new lead is captured
/api/v1/zapier/triggers/new-bookingTrigger: fires when a booking is confirmed
/api/v1/zapier/triggers/new-reviewTrigger: fires when a new review is received
REST API (v1)
General-purpose REST endpoints for integrators and custom apps. All requests require Authorization: Bearer sk_live_xxx. Responses use a { data, pagination?, error? } envelope.
/api/v1/leadsList leads with pagination and filters (?page=1&limit=50&status=new&source=chatbot)
/api/v1/leads/:idGet a single lead by ID
/api/v1/leadsCreate a new lead from an external system (body: { name, email, phone?, source?, notes? })
/api/v1/bookingsList bookings with pagination (?page=1&limit=50&status=confirmed)
/api/v1/invoicesList invoices with pagination (?page=1&limit=50&status=paid)
/api/v1/analyticsKPI summary: leads, revenue, conversion rate, and bookings
/api/v1/servicesList active services for the authenticated account
Health & Status
Public monitoring endpoints for uptime services (UptimeRobot, BetterUptime, Cronitor, etc.). No authentication required. Responses include Cache-Control: no-store.
/api/healthLightweight health check -- returns 200 (healthy) or 503 (degraded) with DB latency
/api/health/deepDeep dependency check -- probes database, Redis, Stripe, SendGrid, Twilio, and memory
/api/statusPublic status page data -- service list with operational/degraded/down states
Customer Portal
Endpoints for the white-labeled customer portal. Customers authenticate via a portal-specific magic link scoped to a client slug.
/api/portal/[clientSlug]/authSend a portal magic link or verify a token for the customer portal
/api/portal/[clientSlug]Portal dashboard data -- service history, upcoming bookings, and invoices
/api/portal/[clientSlug]/quotesList quotes visible to the portal customer
/api/portal/[clientSlug]/membershipsMembership plans and current enrollment status
/api/portal/[clientSlug]/equipmentCustomer equipment records and service history
Field (Technician)
Mobile-first API for field technicians. Authenticated via a field-session cookie (magic link sent to technician email or phone).
/api/field/authSend a magic link to a technician (email or phone) and verify field session tokens
/api/field/scheduleTechnician daily schedule with job details and routing
/api/field/jobs/[bookingId]Single job detail -- customer info, scope, parts, notes
/api/field/jobs/[bookingId]Update job status (en-route, started, completed)
/api/field/jobs/[bookingId]/notesAdd a technician note or photo to the job
/api/field/jobs/[bookingId]/signatureCapture customer signature on completion
/api/field/jobs/[bookingId]/partsLog parts used for the job
Need Help Integrating?
Contact our team at support@trysovereignai.com or use the Atlas chatbot in your dashboard for real-time API integration support.