{"openapi":"3.1.0","info":{"title":"Social Perks API","version":"1.0.0","description":"Social Perks turns customers into your marketing team. Businesses offer perks (discounts/rewards) to customers in exchange for marketing actions across social media platforms. This API powers campaign management, submission tracking, AI-driven recommendations, perk programs, an influencer exchange, and more.","contact":{"name":"Social Perks API Support","url":"https://socialperks.app/support"},"license":{"name":"Proprietary"}},"servers":[{"url":"/api/v1","description":"API v1 (current, deprecation planned for 2026-12-31)"},{"url":"/api/v2","description":"API v2 (next generation)"}],"tags":[{"name":"Auth","description":"Authentication and session management"},{"name":"Campaigns","description":"Campaign creation and management"},{"name":"Submissions","description":"Proof submission and review"},{"name":"AI","description":"AI-powered campaign generation and recommendations (backend-only)"},{"name":"Billing","description":"Subscription and payment management"},{"name":"Programs","description":"Perk programs, members, cashback, and progress"},{"name":"Exchange","description":"Influencer/business marketplace and trading"},{"name":"Reference","description":"Pricing, actions, benchmarks, influencers, and legal data"},{"name":"Infrastructure","description":"Health, events, OAuth, webhooks, and seed data"}],"paths":{"/auth":{"get":{"summary":"Validate current session","tags":["Auth"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"}],"responses":{"200":{"description":"Current user information","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Login, signup, logout, refresh, or reset password","tags":["Auth"],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["login","signup","logout","refresh","reset-password"]},"email":{"type":"string","format":"email"},"password":{"type":"string"},"name":{"type":"string"}},"required":["action"]}}}},"responses":{"200":{"description":"Auth action result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/campaigns":{"get":{"summary":"List campaigns","tags":["Campaigns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Page number"},{"name":"perPage","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Items per page"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Filter by status"},{"name":"platform","in":"query","schema":{"type":"string"},"description":"Filter by platform"}],"responses":{"200":{"description":"List of campaigns","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create or launch a campaign","tags":["Campaigns"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"platform":{"type":"string"},"actionType":{"type":"string"},"discountValue":{"type":"number"},"discountType":{"type":"string"},"budget":{"type":"number"}},"required":["title","platform"]}}}},"responses":{"200":{"description":"Created campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/submissions":{"get":{"summary":"List submissions","tags":["Submissions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Page number"},{"name":"perPage","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Items per page"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Filter by status"},{"name":"campaignId","in":"query","schema":{"type":"string"},"description":"Filter by campaign"}],"responses":{"200":{"description":"List of submissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a submission with proof","tags":["Submissions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"proofUrl":{"type":"string","format":"uri"},"proofType":{"type":"string","enum":["url","screenshot","text"]},"comment":{"type":"string"}},"required":["campaignId","proofUrl"]}}}},"responses":{"200":{"description":"Created submission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/submissions/review":{"post":{"summary":"Approve or reject a submission","tags":["Submissions"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"submissionId":{"type":"string"},"action":{"type":"string","enum":["approve","reject"]},"reviewNote":{"type":"string"}},"required":["submissionId","action"]}}}},"responses":{"200":{"description":"Reviewed submission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/ai/generate":{"post":{"summary":"Generate AI campaign suggestions","tags":["AI"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessType":{"type":"string"},"industry":{"type":"string"},"goals":{"type":"array","items":{"type":"string"}},"budget":{"type":"number"},"platforms":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Generated campaign suggestions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/ai/recommend":{"post":{"summary":"Get AI optimization recommendations","tags":["AI"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"campaignId":{"type":"string"},"type":{"type":"string","enum":["optimize","expand","budget"]}}}}}},"responses":{"200":{"description":"AI recommendations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/ai/review":{"post":{"summary":"AI-powered submission review pipeline","tags":["AI"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"submissionId":{"type":"string"}},"required":["submissionId"]}}}},"responses":{"200":{"description":"AI review result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/ai/campaign-agent":{"post":{"summary":"Full AI-generated marketing plan","tags":["AI"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessId":{"type":"string"},"goals":{"type":"array","items":{"type":"string"}},"budget":{"type":"number"},"timeframe":{"type":"string"}}}}}},"responses":{"200":{"description":"Complete marketing plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/ai/quick-start":{"post":{"summary":"Quick-start single recommendation","tags":["AI"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"businessType":{"type":"string"},"platform":{"type":"string"}}}}}},"responses":{"200":{"description":"Quick-start recommendation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/billing":{"post":{"summary":"Manage subscription (create, update, cancel)","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["subscribe","update","cancel","portal"]},"planId":{"type":"string"}},"required":["action"]}}}},"responses":{"200":{"description":"Billing action result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/billing/webhook":{"post":{"summary":"Stripe webhook handler","tags":["Billing"],"parameters":[{"name":"Stripe-Signature","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Stripe webhook event","required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Webhook processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/programs":{"get":{"summary":"List perk programs","tags":["Programs"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Page number"},{"name":"perPage","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Items per page"}],"responses":{"200":{"description":"List of programs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a perk program","tags":["Programs"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"type":{"type":"string"},"rewards":{"type":"array","items":{"type":"object"}}},"required":["name"]}}}},"responses":{"200":{"description":"Created program","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/programs/{programId}":{"get":{"summary":"Get program details","tags":["Programs"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"},{"name":"programId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Program details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"put":{"summary":"Update a program","tags":["Programs"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"},{"name":"programId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"status":{"type":"string"}}}}}},"responses":{"200":{"description":"Updated program","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"End a program","tags":["Programs"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"},{"name":"programId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Program ended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/programs/{programId}/progress":{"get":{"summary":"Get member progress in a program","tags":["Programs"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"},{"name":"programId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Member progress data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/programs/{programId}/submit":{"post":{"summary":"Submit an action for a program","tags":["Programs"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"},{"name":"programId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"actionId":{"type":"string"},"proofUrl":{"type":"string","format":"uri"}},"required":["actionId","proofUrl"]}}}},"responses":{"200":{"description":"Submission result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/programs/{programId}/cashback":{"get":{"summary":"List cashback payouts","tags":["Programs"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"},{"name":"programId","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Page number"},{"name":"perPage","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Items per page"}],"responses":{"200":{"description":"List of cashback payouts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Request or manage cashback","tags":["Programs"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"},{"name":"programId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["request","approve","reject"]},"amount":{"type":"number"}},"required":["action"]}}}},"responses":{"200":{"description":"Cashback action result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/programs/{programId}/members":{"get":{"summary":"List program members","tags":["Programs"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"},{"name":"programId","in":"path","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Page number"},{"name":"perPage","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Items per page"}],"responses":{"200":{"description":"List of program members","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Enroll a member in a program","tags":["Programs"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"},{"name":"programId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"userId":{"type":"string"},"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Enrollment result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/exchange/opportunities":{"get":{"summary":"List market opportunities (public)","tags":["Exchange"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Page number"},{"name":"perPage","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Items per page"}],"responses":{"200":{"description":"Market opportunities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/exchange/market":{"get":{"summary":"Real-time market data (public)","tags":["Exchange"],"responses":{"200":{"description":"Market data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/exchange/orders":{"get":{"summary":"List orders","tags":["Exchange"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Page number"},{"name":"perPage","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Items per page"}],"responses":{"200":{"description":"List of orders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Place a buy/sell order","tags":["Exchange"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"side":{"type":"string","enum":["buy","sell"]},"amount":{"type":"number"},"price":{"type":"number"},"campaignId":{"type":"string"}},"required":["side","amount"]}}}},"responses":{"200":{"description":"Created order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/exchange/trades":{"get":{"summary":"List trades","tags":["Exchange"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Page number"},{"name":"perPage","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Items per page"}],"responses":{"200":{"description":"List of trades","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Trade lifecycle actions (settle, cancel, dispute)","tags":["Exchange"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tradeId":{"type":"string"},"action":{"type":"string","enum":["settle","cancel","dispute"]}},"required":["tradeId","action"]}}}},"responses":{"200":{"description":"Trade action result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/exchange/enroll":{"post":{"summary":"Agent auto-enrollment","tags":["Exchange"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"agentId":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Enrollment result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/pricing":{"get":{"summary":"Pricing oracle — platform action pricing","tags":["Reference"],"parameters":[{"name":"platform","in":"query","schema":{"type":"string"},"description":"Filter by platform"},{"name":"action","in":"query","schema":{"type":"string"},"description":"Filter by action type"}],"responses":{"200":{"description":"Pricing data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/actions":{"get":{"summary":"Action library — all 107 marketing actions","tags":["Reference"],"parameters":[{"name":"platform","in":"query","schema":{"type":"string"},"description":"Filter by platform"},{"name":"type","in":"query","schema":{"type":"string"},"description":"Filter by action type"}],"responses":{"200":{"description":"Action library","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/benchmarks":{"get":{"summary":"Industry benchmarks","tags":["Reference"],"parameters":[{"name":"industry","in":"query","schema":{"type":"string"},"description":"Filter by industry"}],"responses":{"200":{"description":"Benchmark data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/influencers":{"get":{"summary":"Search influencers","tags":["Reference"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Page number"},{"name":"perPage","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Items per page"},{"name":"platform","in":"query","schema":{"type":"string"},"description":"Filter by platform"},{"name":"tier","in":"query","schema":{"type":"string"},"description":"Filter by tier"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Search query"}],"responses":{"200":{"description":"Influencer list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Register as an influencer","tags":["Reference"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"platforms":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"handle":{"type":"string"},"followers":{"type":"integer"}}}}},"required":["name","email"]}}}},"responses":{"200":{"description":"Registered influencer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/recommendations":{"get":{"summary":"ML-powered recommendations","tags":["Reference"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"},{"name":"type","in":"query","schema":{"type":"string"},"description":"Recommendation type"}],"responses":{"200":{"description":"Recommendations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/legal":{"get":{"summary":"Legal compliance briefings","tags":["Reference"],"parameters":[{"name":"topic","in":"query","schema":{"type":"string"},"description":"Legal topic"}],"responses":{"200":{"description":"Legal briefing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/events":{"get":{"summary":"SSE real-time event stream","tags":["Infrastructure"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"}],"responses":{"200":{"description":"Server-Sent Events stream","content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}}}}},"/health":{"get":{"summary":"Health check","tags":["Infrastructure"],"responses":{"200":{"description":"Service health status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}}}}},"/oauth/connect":{"post":{"summary":"Start OAuth flow for a social platform","tags":["Infrastructure"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Authorization","in":"header","required":true,"schema":{"type":"string","example":"Bearer eyJhbGci..."},"description":"Bearer JWT token or session token"}],"requestBody":{"description":"Request body","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"platform":{"type":"string"},"redirectUri":{"type":"string","format":"uri"}},"required":["platform"]}}}},"responses":{"200":{"description":"OAuth redirect URL","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"429":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/oauth/{platform}":{"get":{"summary":"OAuth callback handler","tags":["Infrastructure"],"parameters":[{"name":"platform","in":"path","required":true,"schema":{"type":"string"}},{"name":"code","in":"query","schema":{"type":"string"},"description":"Authorization code"},{"name":"state","in":"query","schema":{"type":"string"},"description":"CSRF state token"}],"responses":{"200":{"description":"OAuth connection result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/verification/webhook":{"get":{"summary":"Webhook challenge verification (platform handshake)","tags":["Infrastructure"],"parameters":[{"name":"hub.challenge","in":"query","schema":{"type":"string"},"description":"Challenge token to echo back"}],"responses":{"200":{"description":"Challenge response","content":{"text/plain":{"schema":{"type":"string"}}}}}},"post":{"summary":"Platform webhook receiver (verification events)","tags":["Infrastructure"],"parameters":[{"name":"X-Hub-Signature-256","in":"header","schema":{"type":"string"},"description":"HMAC signature for payload verification"}],"requestBody":{"description":"Platform webhook event payload","required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Webhook processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/seed":{"post":{"summary":"Seed demo data (development only)","tags":["Infrastructure"],"responses":{"200":{"description":"Seed data created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessResponse"}}}},"400":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"SuccessResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"}},"required":["success","data"]},"PaginatedResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"},"pagination":{"type":"object","properties":{"page":{"type":"integer","example":1},"perPage":{"type":"integer","example":20},"total":{"type":"integer","example":100}}}},"required":["success","data"]},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"ERROR_CODE"},"message":{"type":"string","example":"Description of the error"}},"required":["code","message"]}},"required":["success","error"]},"Business":{"type":"object","properties":{"id":{"type":"string","example":"biz_abc123"},"name":{"type":"string","example":"Sol Coffee"},"email":{"type":"string","format":"email"},"industry":{"type":"string","example":"food-beverage"},"plan":{"type":"string","enum":["free","starter","pro","enterprise"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","email"]},"Campaign":{"type":"object","properties":{"id":{"type":"string","example":"camp_xyz789"},"businessId":{"type":"string"},"title":{"type":"string","example":"Share us on Instagram"},"platform":{"type":"string","example":"instagram"},"actionType":{"type":"string","example":"content"},"discountValue":{"type":"number","example":15},"discountType":{"type":"string","enum":["percentage","fixed","freeItem"]},"status":{"type":"string","enum":["draft","active","paused","ended","expired"]},"tier":{"type":"string","enum":["essential","highImpact","growth","premium","starter"]},"budget":{"type":"number","example":500},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","businessId","title","platform"]},"LaunchedCampaign":{"type":"object","properties":{"id":{"type":"string"},"campaignId":{"type":"string"},"businessId":{"type":"string"},"status":{"type":"string","enum":["active","paused","ended"]},"impressions":{"type":"integer"},"submissions":{"type":"integer"},"approved":{"type":"integer"},"launchedAt":{"type":"string","format":"date-time"}},"required":["id","campaignId","businessId","status"]},"Submission":{"type":"object","properties":{"id":{"type":"string","example":"sub_def456"},"campaignId":{"type":"string"},"userId":{"type":"string"},"proofUrl":{"type":"string","format":"uri"},"proofType":{"type":"string","enum":["url","screenshot","text"]},"status":{"type":"string","enum":["pending","approved","rejected","expired"]},"reviewNote":{"type":"string"},"submittedAt":{"type":"string","format":"date-time"},"reviewedAt":{"type":"string","format":"date-time"}},"required":["id","campaignId","userId","proofUrl","status"]},"Influencer":{"type":"object","properties":{"id":{"type":"string","example":"inf_ghi789"},"name":{"type":"string","example":"Priya Sharma"},"email":{"type":"string","format":"email"},"platforms":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"handle":{"type":"string"},"followers":{"type":"integer"}}}},"tier":{"type":"string","enum":["nano","micro","mid","macro","mega"]},"rateCard":{"type":"object"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","email"]},"PerkWallet":{"type":"object","properties":{"userId":{"type":"string"},"balance":{"type":"number","example":45.5},"lifetimeEarned":{"type":"number","example":200},"lifetimeRedeemed":{"type":"number","example":154.5},"perks":{"type":"array","items":{"$ref":"#/components/schemas/EarnedPerk"}}},"required":["userId","balance"]},"EarnedPerk":{"type":"object","properties":{"id":{"type":"string"},"campaignId":{"type":"string"},"businessId":{"type":"string"},"value":{"type":"number"},"type":{"type":"string","enum":["percentage","fixed","freeItem"]},"status":{"type":"string","enum":["active","redeemed","expired"]},"earnedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}},"required":["id","campaignId","value","status"]},"User":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"role":{"type":"string","enum":["business","influencer","admin"]},"businessId":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","email","role"]},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string","description":"Only returned on creation"},"name":{"type":"string"},"businessId":{"type":"string"},"scopes":{"type":"array","items":{"type":"string"}},"lastUsed":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}},"required":["id","name","businessId"]},"Webhook":{"type":"object","properties":{"id":{"type":"string","example":"whk_abc123_1"},"businessId":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"secret":{"type":"string","description":"HMAC signing secret"},"status":{"type":"string","enum":["active","inactive","failing"]},"failureCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","businessId","url","events","status"]},"Notification":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"title":{"type":"string"},"message":{"type":"string"},"read":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","type","title","message"]}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token obtained from POST /auth with action=login"},"apiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for programmatic access (enterprise plans)"}},"responses":{"BadRequest":{"description":"Bad request — invalid parameters or body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"success":false,"error":{"code":"NO_TOKEN","message":"Authentication required"}}}}},"RateLimited":{"description":"Too many requests — rate limit exceeded","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"security":[{"bearerAuth":[]},{"apiKeyAuth":[]}]}