API reference
Adsynth is in production for our team today, with partner and brand access rolling out on subscription. The application API is authenticated and consumed by the frontend on each user's behalf.
Application API (FastAPI)
The production service exposes HTTP endpoints consumed by the Next.js frontend over authenticated sessions and, where configured, tenant HMAC headers. Examples include organisation bootstrap, branding, billing webhooks, and privacy endpoints (GET/POST /api/privacy/*) for consent and data-subject requests. These routes require a valid user identity; they are not intended for anonymous internet access.
Google Ads API
Campaign, reporting, and optimisation operations use Google's official Google Ads API with OAuth credentials supplied by each customer's authorised users. Supported capabilities include GAQL search / streams, campaign and ad group lifecycle, budgets, bidding, keywords, negatives, extensions, Performance Max asset workflows, recommendations (retrieved and, with approval, applied), conversion actions, experiments, and extensive reporting views. The authoritative catalogue of tool names and behaviours is maintained in docs/ENDPOINTS.md in the repository.
Meta Marketing API
Where enabled, Meta Ads integrations follow Meta's Marketing API with OAuth per workspace policies. Scope and available actions depend on your organisation's configuration and Meta app review status.
Microsoft Bing Ads & Apple Search Ads
Where configured, Bing campaign and reporting tools use Microsoft Advertising APIs; Apple Search Ads reporting uses Apple's documented endpoints. Cross-channel snapshots feed the Insights dashboard and Outcome OS playbooks.
SEO & SERP intelligence
Search Console and GA4 data are joined for decay analysis, opportunity matrices, and technical audits. SERP intelligence (AI Overview, PAA) uses configured third-party APIs (e.g. SerpAPI) for competitive content planning and brief generation.
Shopify
Optional Shopify connections pull store revenue context into workspace analysis for ecommerce ROAS conversations.
YouTube & brand assets
Workspaces can link YouTube channels, list uploads, and import videos into the Creative hub for Performance Max, Demand Gen, and vision-ranked report workflows. Brand assets (images, video, copy) are searchable from chat and playbooks via list_brand_assets and search_brand_knowledge.
Brand training & knowledge
Each workspace maintains a Training library (uploads + optional email inbox). Documents are chunked and indexed; a synthesized Brand Brief profile is injected into agent system prompts. Agents retrieve relevant passages with search_brand_knowledge during analysis, reporting, and playbook runs.
Google Analytics 4 & Search Console
Read-only analytics and search analytics data use Google's documented APIs with the same user-consented OAuth model. Configuration details: GA4_GSC_CREDENTIALS.md.
MCP server (developers & editors)
For Cursor and compatible hosts, the repository ships an MCP server under mcp-server/ that exposes a structured tool surface for Google Ads operations. See the MCP README in the repo for installation — this is a developer integration path, separate from the SaaS UI.
Rate limits & quotas
Google Ads API usage is subject to Google's quotas and your developer token access level (Basic vs Standard). Adsynth batches work and caches where appropriate but cannot exceed Google's platform limits.