openapi: 3.1.0 info: title: Memesio API Contracts agent-infra trend-alerts API version: 0.1.0 description: Contract baseline for AI jobs, trend alerts, collaboration, and billing surfaces. servers: - url: / tags: - name: trend-alerts paths: /api/ai/templates/suggest: post: summary: Rank Template Suggestions from Prompt + Trend Signals for Creative Ideation Flow tags: - trend-alerts security: - DeveloperApiKeyAuth: [] - AgentApiKeyAuth: [] - {} requestBody: required: true content: application/json: schema: type: object required: - prompt properties: prompt: type: string minLength: 1 trendSignals: type: array items: type: string maxItems: 20 limit: type: number minimum: 1 maximum: 60 responses: '200': description: Template suggestion ranking payload '400': description: Validation error /api/alerts: get: summary: List Trend Alerts with Optional Personalized Feed Ranking by Niche, Region, Topics, and Follower Count tags: - trend-alerts parameters: - name: query in: query schema: type: string - name: source in: query schema: type: string enum: - x - reddit - tiktok - youtube - name: status in: query schema: type: string enum: - new - opened - muted - archived - name: niche in: query schema: type: string - name: region in: query schema: type: string - name: actorId in: query schema: type: string - name: preferredNiche in: query schema: type: string - name: preferredRegion in: query schema: type: string - name: topics in: query schema: type: string - name: followerCount in: query schema: type: integer minimum: 0 - name: aggressiveness in: query schema: type: number minimum: 0 maximum: 1 - name: page in: query schema: type: integer minimum: 1 - name: pageSize in: query schema: type: integer minimum: 1 maximum: 50 responses: '200': description: Trend alerts list /api/alerts/connectors: get: summary: Get Trend Source Connectors and Data Contracts tags: - trend-alerts responses: '200': description: Trend source connector contract payload /api/alerts/ingestion: get: summary: Run/Retrieve Real-Time Trend Ingestion from X, Reddit, TikTok, and YouTube with Dedupe + Freshness Scoring tags: - trend-alerts parameters: - name: refresh in: query schema: type: boolean responses: '200': description: Trend ingestion output payload /api/alerts/ranking: get: summary: Rank Trend Alerts with Personalization by Niche, Geography, Follower Count, and Creator-Selected Topics tags: - trend-alerts parameters: - name: actorId in: query schema: type: string - name: preferredNiche in: query schema: type: string - name: preferredRegion in: query schema: type: string - name: topics in: query schema: type: string - name: followerCount in: query schema: type: integer minimum: 0 - name: aggressiveness in: query schema: type: number minimum: 0 maximum: 1 - name: limit in: query schema: type: integer minimum: 1 maximum: 50 responses: '200': description: Ranked trend alerts payload /api/alerts/preferences: get: summary: Get Trend Preference Vector for Actor tags: - trend-alerts parameters: - name: actorId in: query required: true schema: type: string responses: '200': description: Preference vector payload '400': description: Missing actor id post: summary: Upsert Trend Preference Vector from Explicit Interests and Behavior Events tags: - trend-alerts requestBody: required: true content: application/json: schema: type: object required: - actorId properties: actorId: type: string followerCount: type: integer minimum: 0 aggressiveness: type: number minimum: 0 maximum: 1 explicitNiches: type: array items: type: string explicitTopics: type: array items: type: string explicitRegions: type: array items: type: string explicitSources: type: array items: type: string event: type: object properties: action: type: string enum: - alert_opened - alert_marked_relevant - alert_marked_irrelevant - alert_marked_relevant - topic_followed - topic_muted - create_from_alert niche: type: string topic: type: string region: type: string source: type: string responses: '201': description: Updated preference vector payload '400': description: Validation error /api/alerts/feedback: get: summary: List Stored Trend Feedback Actions tags: - trend-alerts parameters: - name: actorId in: query schema: type: string - name: limit in: query schema: type: integer minimum: 1 maximum: 200 responses: '200': description: Trend feedback events payload post: summary: Record Trend Feedback Action and Update Preference Vector tags: - trend-alerts requestBody: required: true content: application/json: schema: type: object required: - actorId - alertId - action - topic properties: actorId: type: string alertId: type: string action: type: string enum: - topic_muted - alert_marked_relevant - alert_marked_irrelevant - topic_followed topic: type: string niche: type: string region: type: string source: type: string responses: '201': description: Feedback stored and vector updated '400': description: Validation error /api/alerts/triggers: get: summary: Evaluate Alert Trigger Thresholds and Cooldown Decisions tags: - trend-alerts responses: '200': description: Trigger decision payload post: summary: Run Trigger Execution, Persist Cooldown State, and Fan Out Delivery Across Inbox/Push/Email Channels with SLA Telemetry tags: - trend-alerts responses: '201': description: Trigger execution payload /api/alerts/delivery: get: summary: Retrieve Latest Delivery Report or Refresh Trigger-to-Delivery Fanout for in-App Inbox, Push (PWA), and Email Digest tags: - trend-alerts parameters: - name: refresh in: query schema: type: boolean responses: '200': description: Trend alert delivery report payload post: summary: Execute Trend Alert Delivery Fanout and Return P95 Delivery Latency Against the 5-Minute SLA Target tags: - trend-alerts requestBody: required: false content: application/json: schema: type: object properties: deliverAllAlerts: type: boolean channels: type: array items: type: string enum: - in_app_inbox - push_pwa - email_digest responses: '201': description: Trend alert delivery execution payload /api/alerts/message-templates: get: summary: Get Trend Alert Message Templates and Rendered Preview tags: - trend-alerts parameters: - name: templateId in: query schema: type: string responses: '200': description: Trend alert message templates payload /api/alerts/quality-report: get: summary: Generate or Retrieve Weekly Trend Alert Quality Report tags: - trend-alerts parameters: - name: refresh in: query schema: type: boolean responses: '200': description: Trend alert quality report payload components: securitySchemes: DeveloperApiKeyAuth: type: apiKey in: header name: x-developer-api-key description: 'Optional higher-rate free-tier auth. You can also send the key as Authorization: Bearer .' AgentApiKeyAuth: type: apiKey in: header name: x-agent-api-key description: 'Agent auth for free endpoints and agent-admin routes. You can also send the key as Authorization: Bearer .'