{"openapi":"3.1.0","info":{"title":"LeadSysGen API","version":"1.0.0","description":"REST API for workspace data — leads, campaigns, creatives, KPIs, and alert rules. Authenticate with a workspace API key (PRO or AGENCY plan). All responses include a requestId for support."},"servers":[{"url":"https://staging.leadsysgen.com/api/v1"}],"tags":[{"name":"Leads","description":"Create, read, update, and delete leads in your workspace pipeline."},{"name":"Campaigns","description":"List connected ad campaigns and fetch per-campaign KPI rollups."},{"name":"Creatives","description":"Browse ad creatives, variants, and creative-level performance."},{"name":"KPIs","description":"Workspace-wide performance summary over a rolling date window."},{"name":"Alerts","description":"Manage alert rules and inspect fired alert events."}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Workspace API key prefixed with lsg_live_"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED","FORBIDDEN","NOT_FOUND","VALIDATION","PLAN_LIMIT","RATE_LIMIT","INTERNAL"]},"message":{"type":"string"},"details":{}},"required":["code","message"]},"requestId":{"type":"string"}},"required":["error"]},"ListMeta":{"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"Lead":{"type":"object","properties":{"id":{"type":"string"},"workspaceId":{"type":"string"},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"platform":{"type":"string","enum":["META","TIKTOK","GOOGLE","LINKEDIN","SNAPCHAT","MANUAL"]},"score":{"type":"integer","minimum":0,"maximum":100},"revenue":{"type":"number","nullable":true},"notes":{"type":"string","nullable":true},"campaignId":{"type":"string","nullable":true},"campaign":{"type":"string","nullable":true},"pipelineStatusId":{"type":"string"},"status":{"type":"string"},"statusLabel":{"type":"string"},"formData":{"type":"object","additionalProperties":true,"nullable":true},"utmSource":{"type":"string","nullable":true},"utmMedium":{"type":"string","nullable":true},"utmCampaign":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"LeadCreate":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"platform":{"type":"string","enum":["META","TIKTOK","GOOGLE","LINKEDIN","SNAPCHAT","MANUAL"],"default":"MANUAL"},"campaignId":{"type":"string"},"pipelineStatusId":{"type":"string"},"company":{"type":"string"},"city":{"type":"string"},"notes":{"type":"string"},"revenue":{"type":"number"},"formData":{"type":"object","additionalProperties":true}}},"LeadUpdate":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"platform":{"type":"string","enum":["META","TIKTOK","GOOGLE","LINKEDIN","SNAPCHAT","MANUAL"]},"campaignId":{"type":"string"},"pipelineStatusId":{"type":"string"},"company":{"type":"string"},"city":{"type":"string"},"notes":{"type":"string"},"revenue":{"type":"number"},"score":{"type":"integer","minimum":0,"maximum":100},"formData":{"type":"object","additionalProperties":true}}},"Campaign":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"objective":{"type":"string","nullable":true},"budget":{"type":"number","nullable":true},"currency":{"type":"string"},"platformId":{"type":"string"},"platform":{"type":"string","enum":["META","TIKTOK","GOOGLE","LINKEDIN","SNAPCHAT","MANUAL"]},"accountName":{"type":"string","nullable":true},"clientId":{"type":"string","nullable":true},"leadCount":{"type":"integer"},"startDate":{"type":"string","format":"date","nullable":true},"endDate":{"type":"string","format":"date","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Creative":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"platform":{"type":"string","enum":["META","TIKTOK","GOOGLE","LINKEDIN","SNAPCHAT","MANUAL"]},"status":{"type":"string"},"approvalStatus":{"type":"string","enum":["DRAFT","PENDING_REVIEW","APPROVED","REJECTED"],"nullable":true},"headline":{"type":"string","nullable":true},"body":{"type":"string","nullable":true},"ctaText":{"type":"string","nullable":true},"imageUrl":{"type":"string","nullable":true},"imageUrls":{"type":"array","items":{"type":"string"}},"videoUrl":{"type":"string","nullable":true},"thumbnailUrl":{"type":"string","nullable":true},"batchId":{"type":"string","nullable":true},"variantLabel":{"type":"string","nullable":true},"adSetId":{"type":"string","nullable":true},"hasMetrics":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"KpiSummary":{"type":"object","properties":{"periodDays":{"type":"integer"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"spend":{"type":"number"},"leads":{"type":"integer"},"conversions":{"type":"integer"},"impressions":{"type":"string","description":"BigInt serialized as string"},"clicks":{"type":"string","description":"BigInt serialized as string"},"cpl":{"type":"number","description":"Cost per lead (MAD)"},"cpc":{"type":"number","description":"Cost per click (MAD)"},"ctr":{"type":"number","description":"Click-through rate (0–1)"},"cvr":{"type":"number","description":"Conversion rate (0–1)"}}},"CampaignKpiSummary":{"allOf":[{"$ref":"#/components/schemas/KpiSummary"},{"type":"object","properties":{"campaignId":{"type":"string"},"campaignName":{"type":"string"},"impressions":{"type":"integer"},"clicks":{"type":"integer"}}}]},"CreativeKpiSummary":{"allOf":[{"$ref":"#/components/schemas/KpiSummary"},{"type":"object","properties":{"creativeId":{"type":"string"},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"videoViews":{"type":"integer"}}}]},"AlertRule":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"metric":{"type":"string","enum":["cpl","ctr","leads","spend","cpc","budget_util"]},"operator":{"type":"string","enum":["gt","lt","eq"]},"threshold":{"type":"number","minimum":0},"platform":{"type":"string","enum":["META","TIKTOK","GOOGLE","LINKEDIN","SNAPCHAT","MANUAL"],"nullable":true},"channel":{"type":"string","enum":["EMAIL","TELEGRAM","SLACK","WEBHOOK","WHATSAPP"]},"destination":{"type":"string"},"action":{"type":"string","enum":["NOTIFY_ONLY","PAUSE_CAMPAIGN","INCREASE_BUDGET","DECREASE_BUDGET"]},"maxBudgetChangePercent":{"type":"integer","minimum":1,"maximum":100},"actionCooldownMinutes":{"type":"integer","minimum":5,"maximum":1440},"isActive":{"type":"boolean"},"campaignId":{"type":"string","nullable":true},"campaignName":{"type":"string","nullable":true},"clientId":{"type":"string","nullable":true},"clientName":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"AlertRuleCreate":{"type":"object","required":["name","metric","operator","threshold","channel","destination"],"properties":{"name":{"type":"string","maxLength":100},"metric":{"type":"string","enum":["cpl","ctr","leads","spend","cpc","budget_util"]},"operator":{"type":"string","enum":["gt","lt","eq"]},"threshold":{"type":"number","minimum":0},"platform":{"type":"string","enum":["META","TIKTOK","GOOGLE","LINKEDIN","SNAPCHAT","MANUAL"]},"campaignId":{"type":"string"},"clientId":{"type":"string"},"channel":{"type":"string","enum":["EMAIL","TELEGRAM","SLACK","WEBHOOK","WHATSAPP"]},"destination":{"type":"string","maxLength":512},"action":{"type":"string","enum":["NOTIFY_ONLY","PAUSE_CAMPAIGN","INCREASE_BUDGET","DECREASE_BUDGET"],"default":"NOTIFY_ONLY"},"maxBudgetChangePercent":{"type":"integer","minimum":1,"maximum":100,"default":20},"actionCooldownMinutes":{"type":"integer","minimum":5,"maximum":1440,"default":60}}},"AlertRuleUpdate":{"type":"object","properties":{"name":{"type":"string","maxLength":100},"metric":{"type":"string","enum":["cpl","ctr","leads","spend","cpc","budget_util"]},"operator":{"type":"string","enum":["gt","lt","eq"]},"threshold":{"type":"number","minimum":0},"platform":{"type":"string","enum":["META","TIKTOK","GOOGLE","LINKEDIN","SNAPCHAT","MANUAL"]},"campaignId":{"type":"string"},"clientId":{"type":"string"},"channel":{"type":"string","enum":["EMAIL","TELEGRAM","SLACK","WEBHOOK","WHATSAPP"]},"destination":{"type":"string","maxLength":512},"action":{"type":"string","enum":["NOTIFY_ONLY","PAUSE_CAMPAIGN","INCREASE_BUDGET","DECREASE_BUDGET"]},"maxBudgetChangePercent":{"type":"integer","minimum":1,"maximum":100},"actionCooldownMinutes":{"type":"integer","minimum":5,"maximum":1440},"isActive":{"type":"boolean"}}},"AlertEvent":{"type":"object","properties":{"id":{"type":"string"},"ruleId":{"type":"string"},"ruleName":{"type":"string"},"message":{"type":"string"},"value":{"type":"number"},"firedAt":{"type":"string","format":"date-time"}}}}},"paths":{"/leads":{"get":{"summary":"List leads","description":"Paginated lead list with optional search and filters. Requires `leads.read`.","operationId":"listLeads","tags":["Leads"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Search name, email, phone, company, city"},{"name":"platform","in":"query","schema":{"type":"string","enum":["META","TIKTOK","GOOGLE","LINKEDIN","SNAPCHAT","MANUAL"]}},{"name":"city","in":"query","schema":{"type":"string"}},{"name":"campaignId","in":"query","schema":{"type":"string"}},{"name":"pipelineStatusId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated lead list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"meta":{"$ref":"#/components/schemas/ListMeta"},"requestId":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient permission (leads.read required)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create lead","description":"Insert a manual or webhook-sourced lead. Requires `leads.write`.","operationId":"createLead","tags":["Leads"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadCreate"}}}},"responses":{"201":{"description":"Lead created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Lead"},"requestId":{"type":"string"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Insufficient permission or plan limit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/{id}":{"get":{"summary":"Get lead","operationId":"getLead","tags":["Leads"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID (CUID)"}],"responses":{"200":{"description":"Lead","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Lead"},"requestId":{"type":"string"}}}}}},"404":{"description":"Lead not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update lead","operationId":"updateLead","tags":["Leads"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID (CUID)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadUpdate"}}}},"responses":{"200":{"description":"Updated lead","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Lead"},"requestId":{"type":"string"}}}}}},"404":{"description":"Lead not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete lead","operationId":"deleteLead","tags":["Leads"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID (CUID)"}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Lead not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/campaigns":{"get":{"summary":"List campaigns","description":"Paginated campaigns synced from connected ad platforms. Requires `campaigns.read`.","operationId":"listCampaigns","tags":["Campaigns"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Filter by name"},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"clientId","in":"query","schema":{"type":"string"},"description":"Agency client scope"}],"responses":{"200":{"description":"Paginated campaign list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}},"meta":{"$ref":"#/components/schemas/ListMeta"},"requestId":{"type":"string"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/campaigns/{id}":{"get":{"summary":"Get campaign","operationId":"getCampaign","tags":["Campaigns"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID (CUID)"}],"responses":{"200":{"description":"Campaign","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Campaign"},"requestId":{"type":"string"}}}}}},"404":{"description":"Campaign not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/campaigns/{id}/kpi":{"get":{"summary":"Campaign KPI summary","description":"Rolled-up spend, leads, CPL, CTR, and CVR from creative metrics. Requires `kpis.read`.","operationId":"getCampaignKpi","tags":["Campaigns","KPIs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID (CUID)"},{"name":"days","in":"query","schema":{"type":"integer","default":30,"minimum":1,"maximum":365},"description":"Rolling window in days (UTC timezone)"}],"responses":{"200":{"description":"Campaign KPI rollup","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CampaignKpiSummary"},"requestId":{"type":"string"}}}}}},"404":{"description":"Campaign not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/creatives":{"get":{"summary":"List creatives","description":"Paginated ad creatives including AI-generated variants. Requires `creatives.read`.","operationId":"listCreatives","tags":["Creatives"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"platform","in":"query","schema":{"type":"string","enum":["META","TIKTOK","GOOGLE","LINKEDIN","SNAPCHAT","MANUAL"]}},{"name":"approvalStatus","in":"query","schema":{"type":"string","enum":["DRAFT","PENDING_REVIEW","APPROVED","REJECTED"]}},{"name":"batchId","in":"query","schema":{"type":"string"},"description":"A/B batch ID"}],"responses":{"200":{"description":"Paginated creative list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Creative"}},"meta":{"$ref":"#/components/schemas/ListMeta"},"requestId":{"type":"string"}}}}}}}}},"/creatives/{id}":{"get":{"summary":"Get creative","operationId":"getCreative","tags":["Creatives"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID (CUID)"}],"responses":{"200":{"description":"Creative","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Creative"},"requestId":{"type":"string"}}}}}},"404":{"description":"Creative not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/creatives/{id}/kpi":{"get":{"summary":"Creative KPI summary","description":"Per-creative performance over a rolling window. Requires `kpis.read`.","operationId":"getCreativeKpi","tags":["Creatives","KPIs"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID (CUID)"},{"name":"days","in":"query","schema":{"type":"integer","default":30,"minimum":1,"maximum":365},"description":"Rolling window in days (UTC timezone)"}],"responses":{"200":{"description":"Creative KPI rollup","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CreativeKpiSummary"},"requestId":{"type":"string"}}}}}},"404":{"description":"Creative not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/kpis":{"get":{"summary":"Workspace KPI summary","description":"Aggregated workspace metrics from daily KPI snapshots. Requires `kpis.read`.","operationId":"getWorkspaceKpi","tags":["KPIs"],"parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":30,"minimum":1,"maximum":365},"description":"Rolling window in days (UTC timezone)"}],"responses":{"200":{"description":"Workspace KPI summary","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/KpiSummary"},"requestId":{"type":"string"}}}}}}}}},"/alerts":{"get":{"summary":"List alert rules","operationId":"listAlertRules","tags":["Alerts"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"Paginated alert rules","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AlertRule"}},"meta":{"$ref":"#/components/schemas/ListMeta"},"requestId":{"type":"string"}}}}}}}},"post":{"summary":"Create alert rule","description":"Automated alert actions require AGENCY plan. Requires `alerts.write`.","operationId":"createAlertRule","tags":["Alerts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertRuleCreate"}}}},"responses":{"201":{"description":"Alert rule created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AlertRule"},"requestId":{"type":"string"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan limit or permission denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/alerts/{id}":{"get":{"summary":"Get alert rule","operationId":"getAlertRule","tags":["Alerts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID (CUID)"}],"responses":{"200":{"description":"Alert rule","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AlertRule"},"requestId":{"type":"string"}}}}}},"404":{"description":"Alert rule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update alert rule","operationId":"updateAlertRule","tags":["Alerts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID (CUID)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertRuleUpdate"}}}},"responses":{"200":{"description":"Updated alert rule","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AlertRule"},"requestId":{"type":"string"}}}}}},"404":{"description":"Alert rule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete alert rule","operationId":"deleteAlertRule","tags":["Alerts"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Resource ID (CUID)"}],"responses":{"204":{"description":"Deleted"},"404":{"description":"Alert rule not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/alerts/events":{"get":{"summary":"List alert events","description":"History of fired alerts, newest first. Requires `alerts.read`.","operationId":"listAlertEvents","tags":["Alerts"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"Paginated alert events","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AlertEvent"}},"meta":{"$ref":"#/components/schemas/ListMeta"},"requestId":{"type":"string"}}}}}}}}}}}