openapi: 3.1.0 info: title: Memesio API Contracts version: 0.1.0 description: Contract baseline for AI jobs, trend alerts, collaboration, and billing surfaces. servers: - url: / paths: /api/ai/jobs: get: summary: List AI Jobs tags: - ai-jobs parameters: - name: status in: query schema: type: string - name: page in: query schema: type: integer minimum: 1 - name: pageSize in: query schema: type: integer minimum: 1 maximum: 50 responses: '200': description: AI job list post: summary: Submit AI Job tags: - ai-jobs requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AiJobSubmitRequest' responses: '201': description: AI job created /api/ai/jobs/{jobId}: get: summary: Get AI Job Status tags: - ai-jobs parameters: - name: jobId in: path required: true schema: type: string responses: '200': description: AI job details content: application/json: schema: $ref: '#/components/schemas/AiJob' '404': description: Not found /api/ai/jobs/{jobId}/cancel: post: summary: Cancel AI Job tags: - ai-jobs parameters: - name: jobId in: path required: true schema: type: string requestBody: required: false content: application/json: schema: type: object properties: reason: type: string maxLength: 300 responses: '200': description: Canceled '404': description: Not found /api/ai/jobs/{jobId}/complete: post: summary: Complete AI Job and Log Metered AI Cost tags: - ai-jobs - billing parameters: - name: jobId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - workerId properties: workerId: type: string output: type: object additionalProperties: true estimatedCostUsd: type: number minimum: 0 providerId: type: string responses: '200': description: Completed job '404': description: Not found or not running /api/ai/edit-history: get: summary: List or Compare Versioned AI Edit History for a Layer tags: - ai-jobs - history parameters: - name: projectId in: query required: true schema: type: string - name: layerId in: query required: true schema: type: string - name: mode in: query schema: type: string enum: - list - compare - name: limit in: query schema: type: integer minimum: 1 maximum: 500 - name: fromVersionId in: query schema: type: string - name: toVersionId in: query schema: type: string responses: '200': description: Layer history payload '404': description: Versions not found for comparison post: summary: Record or Rollback Versioned AI Edit State for a Layer tags: - ai-jobs - history requestBody: required: true content: application/json: schema: type: object required: - action - projectId - layerId properties: action: type: string enum: - record - rollback projectId: type: string layerId: type: string layerType: type: string enum: - face_swap - background_remove - caption beforeState: type: object additionalProperties: true afterState: type: object additionalProperties: true versionId: type: string actorId: type: string metadata: type: object additionalProperties: true responses: '200': description: Rollback payload '201': description: Version recorded '400': description: Validation error '404': description: Version not found /api/ai/captions/scene: post: summary: Run Scene-Understanding Pipeline to Extract Entities, Tone Cues, and Trend References from Canvas + Template Metadata tags: - ai-captions requestBody: required: true content: application/json: schema: type: object required: - canvasText properties: canvasText: type: array items: type: string templateName: type: string templateDescription: type: string templateTags: type: array items: type: string trendSignals: type: array items: type: string responses: '200': description: Scene understanding payload '400': description: Validation error /api/ai/captions/tone-presets: get: summary: List Default + Custom Brand Tone Presets tags: - ai-captions parameters: - name: locale in: query schema: type: string responses: '200': description: Tone preset list payload post: summary: Create or Update Custom Brand Tone Preset tags: - ai-captions requestBody: required: true content: application/json: schema: type: object required: - name properties: name: type: string locale: type: string voiceRules: type: array items: type: string blockedTerms: type: array items: type: string responses: '201': description: Tone preset saved '400': description: Validation error /api/ai/captions/prompt: post: summary: Build Caption Prompt with Optional Inferred Scene Context and Locale Auto-Detect (En, Es, Pt-Br, Hi) tags: - ai-captions responses: '200': description: Caption prompt payload '400': description: Validation error /api/ai/captions/generate: get: summary: Read the Current Actor's Daily Caption Reroll Quota and Reset Window tags: - ai-captions - auth security: - AgentApiKeyAuth: [] - {} responses: '200': description: Current actor caption reroll quota snapshot post: summary: Generate Caption Reroll Options with Locale-Aware Output, Ranking, Inline Safety Highlights, and Full Caption-Set Alternatives tags: - ai-captions security: - AgentApiKeyAuth: [] - {} requestBody: required: true content: application/json: schema: type: object required: - tone properties: tone: type: string memeId: type: string memeSlug: type: string ownerToken: type: string sceneSummary: type: string entities: type: array items: type: string toneCues: type: array items: type: string trendReferences: type: array items: type: string trendKeywords: type: array items: type: string rewriteNote: type: string referenceCaptions: type: array items: type: string maxItems: 7 captionCount: type: integer minimum: 1 maximum: 7 optionCount: type: integer minimum: 1 maximum: 5 variationOffset: type: integer minimum: 0 maximum: 99 responses: '200': description: Caption generation + ranking payload with reroll quota snapshot content: application/json: schema: type: object properties: ok: type: boolean generationStrategy: type: string enum: - openai - heuristic providerId: type: string fallbackUsed: type: boolean captionSets: type: array items: type: object properties: id: type: string score: type: number captions: type: array items: type: object properties: text: type: string '400': description: Validation error '429': description: Daily caption reroll quota exceeded /api/ai/captions/rewrite: post: summary: Rewrite Caption Text with Shorten/Punchier/Less-Offensive/Brand-Safe Tools and Return Diff Preview tags: - ai-captions security: - AgentApiKeyAuth: [] - {} responses: '200': description: Caption rewrite payload '400': description: Validation error /api/ai/captions/rank: post: summary: Rank Caption Variants and Return Top Safe Selections tags: - ai-captions responses: '200': description: Caption ranking payload '400': description: Validation error /api/ai/captions/moderate: post: summary: Moderate Caption Candidates with Inline Highlights/Rationale and Enqueue Blocked Outputs tags: - ai-captions - moderation responses: '200': description: Caption moderation payload '400': description: Validation error /api/ai/memes/generate: get: summary: Read the Current Actor's Daily AI Meme Quota, Remaining Generations, and Next Action tags: - ai-providers - auth security: - DeveloperApiKeyAuth: [] - AgentApiKeyAuth: [] - {} responses: '200': description: Current actor AI quota snapshot post: summary: Select an Existing Meme Template, Generate Captions, and Return Editor-Ready Meme Variants tags: - ai-providers - ai-captions security: - DeveloperApiKeyAuth: [] - AgentApiKeyAuth: [] - {} requestBody: required: true content: application/json: schema: type: object required: - prompt properties: mode: type: string enum: - template prompt: type: string minLength: 1 maxLength: 500 flow: type: string enum: - text_to_meme captionSource: type: string enum: - input - prompt imageUrl: type: string templateId: type: string captions: type: array items: type: string maxItems: 6 editableCaptions: type: array items: $ref: '#/components/schemas/MemeCaption' maxItems: 8 tone: type: string enum: - sarcastic - deadpan - wholesome - absurd - corporate - dark-lite - brand toneCues: type: array items: type: string maxItems: 6 rewriteNote: type: string maxLength: 160 allowHeuristicFallback: type: boolean variantCount: type: number minimum: 1 maximum: 5 preferredProviderId: type: string enum: - hyperswitch_vision - onnx_local - openai_vision workspaceId: type: string correlationId: type: string responses: '200': description: Meme variant generation payload content: application/json: schema: $ref: '#/components/schemas/AiMemeGenerationSucceededResponse' '400': description: Validation error '429': description: Daily AI quota exceeded '500': description: Provider execution failure /api/auth/signup: post: summary: Create Email/Password Account and Send Verification Email tags: - auth requestBody: required: true content: application/json: schema: type: object required: - email - password properties: email: type: string format: email password: type: string minLength: 8 maxLength: 128 displayName: type: string maxLength: 80 responses: '201': description: Account created and verification sent '400': description: Validation error '409': description: Email already registered /api/auth/resend-verification: post: summary: Resend Email Verification Link tags: - auth responses: '200': description: Verification email sent '400': description: Validation error '404': description: Account not found '409': description: Already verified /api/v1/agents: get: summary: List User-Owned Agent Profiles tags: - agent-infra responses: '200': description: Agent profile list payload '401': description: Authentication required post: summary: Create a User-Owned Agent Profile tags: - agent-infra requestBody: required: true content: application/json: schema: type: object required: - name properties: slug: type: string name: type: string minLength: 1 maxLength: 120 description: type: string maxLength: 1000 websiteUrl: type: string maxLength: 2000 systemPrompt: type: string maxLength: 2000 watermarkText: type: string maxLength: 160 stylePreset: type: string maxLength: 80 locale: type: string maxLength: 40 responses: '201': description: Agent profile created '400': description: Validation error '401': description: Authentication required '409': description: Slug conflict /api/v1/agents/bootstrap: post: summary: Bootstrap a Standalone Agent Account with an Immediately Usable Approved Key tags: - agent-infra - auth requestBody: required: true content: application/json: schema: type: object required: - handle - name properties: handle: type: string minLength: 3 maxLength: 80 name: type: string minLength: 1 maxLength: 120 description: type: string maxLength: 1000 websiteUrl: type: string maxLength: 2000 systemPrompt: type: string maxLength: 2000 watermarkText: type: string maxLength: 160 stylePreset: type: string maxLength: 80 locale: type: string maxLength: 40 responses: '201': description: Standalone agent account created content: application/json: schema: $ref: '#/components/schemas/StandaloneAgentBootstrapResponse' '400': description: Validation error '409': description: Handle conflict '429': description: Rate limit exceeded '503': description: Agent infra schema unavailable /api/v1/agents/create-agent: post: summary: Create a Standalone Agent Account with an Immediately Usable Approved Key tags: - agent-infra - auth requestBody: required: true content: application/json: schema: type: object required: - handle - name properties: handle: type: string minLength: 3 maxLength: 80 name: type: string minLength: 1 maxLength: 120 description: type: string maxLength: 1000 websiteUrl: type: string maxLength: 2000 systemPrompt: type: string maxLength: 2000 watermarkText: type: string maxLength: 160 stylePreset: type: string maxLength: 80 locale: type: string maxLength: 40 responses: '201': description: Standalone agent account created content: application/json: schema: $ref: '#/components/schemas/StandaloneAgentBootstrapResponse' '400': description: Validation error '409': description: Handle conflict '429': description: Rate limit exceeded '503': description: Agent infra schema unavailable /api/v1/agents/{agentId}: get: summary: Get a Single User-Owned Agent Profile tags: - agent-infra parameters: - name: agentId in: path required: true schema: type: string responses: '200': description: Agent profile payload '401': description: Authentication required '404': description: Agent not found patch: summary: Update Agent Profile Defaults (Prompt, Watermark, Style, Locale, Status) tags: - agent-infra parameters: - name: agentId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: name: type: string maxLength: 120 description: type: string maxLength: 1000 websiteUrl: type: string maxLength: 2000 systemPrompt: type: string maxLength: 2000 watermarkText: type: string maxLength: 160 stylePreset: type: string maxLength: 80 locale: type: string maxLength: 40 status: type: string enum: - active - disabled responses: '200': description: Agent profile updated '401': description: Authentication required '404': description: Agent not found /api/v1/agents/{agentId}/keys: get: summary: List Agent API Keys for an Owned Agent tags: - agent-infra - auth parameters: - name: agentId in: path required: true schema: type: string responses: '200': description: Agent key list payload '401': description: Authentication required '404': description: Agent not found post: summary: Create a New Scoped API Key for an Owned Agent tags: - agent-infra - auth parameters: - name: agentId in: path required: true schema: type: string requestBody: required: false content: application/json: schema: type: object properties: scopes: type: array items: type: string enum: - generate - publish - analytics - admin responses: '201': description: Agent key created (plaintext returned once) '401': description: Authentication required '404': description: Agent not found /api/v1/agents/{agentId}/keys/{keyId}: delete: summary: Revoke an Active API Key for an Owned Agent tags: - agent-infra - auth parameters: - name: agentId in: path required: true schema: type: string - name: keyId in: path required: true schema: type: string responses: '200': description: Key revoked '401': description: Authentication required '404': description: Key not found /api/v1/agents/names:generate: post: summary: Generate 5 Candidate Agent Names with Slug Availability Checks tags: - agent-infra requestBody: required: true content: application/json: schema: type: object required: - prompt properties: prompt: type: string minLength: 1 maxLength: 300 responses: '200': description: Name suggestions payload '401': description: Agent API key required '429': description: Per-key name generation limit exceeded /api/v1/agents/{agentId}/channels/telegram/bind: post: summary: Bind Telegram Chat to an Owned Agent tags: - agent-infra - channels parameters: - name: agentId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - chatId properties: chatId: type: string userId: type: string metadata: type: object additionalProperties: true responses: '201': description: Telegram binding created/updated '401': description: Authentication required /api/v1/agents/{agentId}/channels/whatsapp/bind: post: summary: Bind WhatsApp Chat/Phone to an Owned Agent tags: - agent-infra - channels parameters: - name: agentId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - phoneOrChatId properties: phoneOrChatId: type: string userId: type: string metadata: type: object additionalProperties: true responses: '201': description: WhatsApp binding created/updated '401': description: Authentication required /api/v1/agents/webhooks/telegram: post: summary: Telegram Inbound Webhook Receiver with Dedupe and Agent Routing tags: - agent-infra - channels responses: '200': description: Webhook processed '202': description: Ignored non-message Telegram update '403': description: Invalid webhook secret when configured /api/v1/agents/webhooks/whatsapp: get: summary: WhatsApp Verification Handshake Endpoint tags: - agent-infra - channels responses: '200': description: Verification challenge accepted '403': description: Invalid verify token post: summary: WhatsApp Inbound Webhook Receiver with Dedupe and Agent Routing tags: - agent-infra - channels responses: '200': description: Webhook processed '202': description: Ignored non-message event /api/v1/agents/{agentId}/unlocks/social-action: post: summary: Submit Social Action Proof (X_follow) for Quota Boost Review tags: - agent-infra - growth parameters: - name: agentId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - action properties: action: type: string enum: - x_follow proof: type: object additionalProperties: true responses: '201': description: Unlock request submitted '401': description: Agent API key required '403': description: Insufficient key scope /api/v1/agents/unlocks/{unlockId}/approve: post: summary: Admin Approval for Social Unlock and Quota Boost tags: - agent-infra - growth parameters: - name: unlockId in: path required: true schema: type: string requestBody: required: false content: application/json: schema: type: object properties: quotaBoostPerDay: type: integer minimum: 1 maximum: 20 responses: '200': description: Unlock approved '403': description: Admin authorization required '404': description: Unlock not found /api/v1/agents/rewards/votes: post: summary: Cast Weekly Meme Vote (Deduped by Voter Hash) tags: - agent-infra - growth requestBody: required: true content: application/json: schema: type: object required: - memeSlug properties: memeSlug: type: string weekStart: type: string pattern: ^\\d{4}-\\d{2}-\\d{2}$ responses: '200': description: Duplicate vote ignored '201': description: Vote accepted '400': description: Validation error /api/v1/agents/rewards/leaderboard: get: summary: Get Weekly Meme Leaderboard tags: - agent-infra - growth parameters: - name: weekStart in: query schema: type: string pattern: ^\\d{4}-\\d{2}-\\d{2}$ - name: limit in: query schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Leaderboard payload /api/v1/agents/rewards/winner:close: post: summary: Close Weekly Winner Record for Manual Payout Workflow tags: - agent-infra - growth requestBody: required: false content: application/json: schema: type: object properties: weekStart: type: string pattern: ^\\d{4}-\\d{2}-\\d{2}$ payoutStatus: type: string enum: - pending - paid payoutReference: type: string responses: '200': description: Winner record created/updated '403': description: Admin authorization required '404': description: No votes for week /api/ai/templates/suggest: post: summary: Rank Template Suggestions from Prompt + Trend Signals for Creative Ideation Flow tags: - ai-providers - templates - 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/ai/templates/detect: post: summary: Detect Meme Template from Source Image and Return 1-2 Caption Slot Placement with Single/Split Assignment Plan tags: - ai-providers - templates requestBody: required: true content: application/json: schema: type: object required: - sourceImageUrl properties: sourceImageUrl: type: string texts: type: array items: type: string maxItems: 2 maxSlots: type: integer minimum: 1 maximum: 2 mappingMode: type: string enum: - single_or_split actorId: type: string workspaceId: type: string correlationId: type: string responses: '200': description: Template detection payload '400': description: Validation error '500': description: Detection failure /api/ai/face-swap: post: summary: Execute Real-Time Face Swap for Image/Video Frame, with Preview Fallback When GPU Estimate Exceeds 2 Seconds tags: - ai-jobs - face-swap requestBody: required: true content: application/json: schema: type: object required: - sourceAssetUrl - targetAssetUrl - mediaType - width - height - detectedFaceCount properties: sourceAssetUrl: type: string targetAssetUrl: type: string mediaType: type: string enum: - image - video_frame width: type: number minimum: 1 height: type: number minimum: 1 detectedFaceCount: type: number minimum: 1 sourceFaceIndex: type: number minimum: 0 targetFaceIndex: type: number minimum: 0 frameTimeMs: type: number minimum: 0 consentAttested: type: boolean celebrityConfidence: type: number minimum: 0 maximum: 1 nsfwScore: type: number minimum: 0 maximum: 1 actorId: type: string workspaceId: type: string responses: '200': description: Real-time face swap completed '202': description: Preview fallback served and async job queued '403': description: Blocked by content policy /api/ai/face-targets: post: summary: Detect Multiple Face Targets and Return Selector Payload for Target Selection UI tags: - ai-jobs - face-swap requestBody: required: true content: application/json: schema: type: object required: - sourceImageUrl properties: sourceImageUrl: type: string maxFaces: type: number minimum: 1 maximum: 8 responses: '200': description: Face target detection payload '400': description: Validation error /api/ai/background-remove: post: summary: Run One-Click Background Removal for Image or Video Frame with Edge Refinement Slider and Optional Mask Brush Edits tags: - ai-jobs - background-remove requestBody: required: true content: application/json: schema: type: object required: - sourceAssetUrl - width - height properties: sourceAssetUrl: type: string mediaType: type: string enum: - image - video_frame frameTimeMs: type: number minimum: 0 width: type: number minimum: 1 height: type: number minimum: 1 edgeRefinement: type: number minimum: 0 maximum: 1 brushEdits: type: array items: type: object required: - mode - x - y - radius properties: mode: type: string enum: - add - erase x: type: number y: type: number radius: type: number minimum: 1 intensity: type: number minimum: 0.1 maximum: 1 responses: '200': description: Background removal result and mask stats '400': description: Validation error /api/ai/providers/face-swap-benchmark: get: summary: Run or Retrieve Face-Swap Provider Benchmark and Recommendation tags: - ai-providers parameters: - name: refresh in: query schema: type: boolean responses: '200': description: Face-swap provider benchmark report /api/ai/providers/background-remove-benchmark: get: summary: Run or Retrieve Background-Remove Provider Benchmark and Recommendation tags: - ai-providers parameters: - name: refresh in: query schema: type: boolean responses: '200': description: Background-remove provider benchmark report /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 - data-eng 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 - data-eng 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 - data-science 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 - personalization 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 - personalization 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 - personalization 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 - personalization 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 - backend 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 - backend 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 - notifications 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 - notifications 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 - product-marketing 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 - data-ops parameters: - name: refresh in: query schema: type: boolean responses: '200': description: Trend alert quality report payload /api/collab/comments: get: summary: List Collaboration Comments tags: - collaboration parameters: - name: projectId in: query required: true schema: type: string - name: page in: query schema: type: integer minimum: 1 - name: pageSize in: query schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Comment list post: summary: Create Collaboration Comment tags: - collaboration requestBody: required: true content: application/json: schema: type: object required: - projectId - message properties: projectId: type: string message: type: string minLength: 1 maxLength: 1500 authorId: type: string responses: '201': description: Comment created /api/billing/usage: get: summary: Get Billing Usage Snapshot tags: - billing parameters: - name: workspaceId in: query schema: type: string - name: windowDays in: query schema: type: integer minimum: 1 maximum: 365 responses: '200': description: Usage snapshot /api/analytics/metric-dictionary: get: summary: Get Metric Dictionary and Ownership Mapping tags: - analytics responses: '200': description: Metric dictionary payload /api/analytics/dashboards/activation-retention: get: summary: Get Activation and Retention Dashboard Spec (Looker) tags: - analytics responses: '200': description: Dashboard spec payload /api/analytics/dashboards/feature-adoption: get: summary: Get Feature Adoption Dashboard Spec by Plan and Segment (Looker) tags: - analytics responses: '200': description: Dashboard spec payload /api/analytics/dashboards/backend-reliability: get: summary: Get Backend Reliability Dashboard Spec and Live Latency/Error-Rate/Queue-Depth Snapshot tags: - analytics - observability parameters: - name: windowHours in: query schema: type: integer minimum: 1 maximum: 168 responses: '200': description: Backend reliability dashboard + metrics snapshot payload /api/analytics/experiments/templates: get: summary: Get Pricing/Paywall Experiment Analysis Templates tags: - analytics - experimentation parameters: - name: templateId in: query schema: type: string responses: '200': description: Pricing experiment templates payload /api/analytics/anomalies/ai: get: summary: Run AI Cost/Failure Anomaly Detection and Return Alert State tags: - analytics - finops responses: '200': description: AI anomaly detection summary /api/analytics/alerts/backend: get: summary: Run Backend 5xx and Render Latency Alert Checks tags: - analytics - observability responses: '200': description: Backend alerting summary payload /api/compliance/content-policy: get: summary: Get Content and Face-Swap Usage Policy with Enforcement Points tags: - compliance - safety responses: '200': description: Content usage policy payload /api/growth/viral-triggers: get: summary: Get Viral Loop Trigger Definitions and Instrumentation Mapping tags: - growth - analytics responses: '200': description: Viral loop trigger payload /api/growth/referrals: get: summary: Get Referral Credits for Actor tags: - growth parameters: - name: actorId in: query schema: type: string responses: '200': description: Referral credit balance '400': description: Missing actor identity post: summary: Create or Redeem Referral Invite Code with Fraud Checks tags: - growth requestBody: required: true content: application/json: schema: type: object required: - action properties: action: type: string enum: - create - redeem actorId: type: string shareSlug: type: string code: type: string responses: '200': description: Redeemed referral code '201': description: Created referral code '400': description: Invalid request '404': description: Referral code not found '409': description: Fraud/eligibility check failed /api/growth/trend-campaigns: get: summary: Generate or Retrieve Weekly Trend-Driven Template Campaigns tags: - growth - marketing-ops parameters: - name: weekStart in: query schema: type: string pattern: ^\\d{4}-\\d{2}-\\d{2}$ - name: limit in: query schema: type: integer minimum: 1 maximum: 12 - name: publishedOnly in: query schema: type: boolean responses: '200': description: Weekly campaign pack payload '404': description: No published campaign pack found post: summary: Publish Weekly Trend-Driven Template Campaigns for Marketing Ops tags: - growth - marketing-ops requestBody: required: true content: application/json: schema: type: object required: - action properties: action: type: string enum: - publish weekStart: type: string pattern: ^\\d{4}-\\d{2}-\\d{2}$ limit: type: integer minimum: 1 maximum: 12 responses: '201': description: Published weekly campaign pack '400': description: Invalid request /api/growth/social-publish: get: summary: Get Social Publish Gate State, Connected Accounts, and Recent Publishes tags: - growth - distribution parameters: - name: actorId in: query required: true schema: type: string - name: publishLimit in: query schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Social publish state payload '400': description: Missing actor id post: summary: Connect/Disconnect Social Accounts and One-Click Publish (Phase-Gated) tags: - growth - distribution requestBody: required: true content: application/json: schema: type: object required: - action - actorId properties: action: type: string enum: - connect - disconnect - publish actorId: type: string platform: type: string enum: - tiktok - instagram_reels - youtube_shorts - x handle: type: string externalAccountId: type: string accountId: type: string memeSlug: type: string caption: type: string responses: '200': description: Disconnect response '201': description: Connect/publish response '400': description: Validation error '403': description: Phase gate denied '404': description: Account not found for disconnect /api/growth/lifecycle-messaging: get: summary: Get Lifecycle Messaging Flow Config and Recent Dispatch History tags: - growth - lifecycle responses: '200': description: Lifecycle messaging config payload post: summary: Preview/Run Lifecycle Messaging Flows (Activation, Resurrection, Upgrade) tags: - growth - lifecycle requestBody: required: true content: application/json: schema: type: object required: - action properties: action: type: string enum: - preview - run - history now: type: string format: date-time limit: type: integer minimum: 1 maximum: 200 profiles: type: array items: type: object required: - actorId - planTier - createdAt - lastActiveAt - publishes7d - aiJobs7d - monthlyCreditsUsed - monthlyCreditsLimit properties: actorId: type: string planTier: type: string enum: - free - pro - team createdAt: type: string format: date-time lastActiveAt: type: string format: date-time publishes7d: type: integer minimum: 0 aiJobs7d: type: integer minimum: 0 monthlyCreditsUsed: type: number minimum: 0 monthlyCreditsLimit: type: number minimum: 0 responses: '200': description: Preview/history payload '201': description: Run payload '400': description: Validation error /api/growth/experiments/decision: get: summary: Decision Service for Growth Experiments with Optional Exposure Logging tags: - growth - experimentation parameters: - name: actorId in: query required: true schema: type: string - name: surface in: query schema: type: string - name: logExposure in: query schema: type: boolean responses: '200': description: Experiment decisions payload '400': description: Missing actor id post: summary: Request Decisions or Query Exposure History for Growth Experiments tags: - growth - experimentation requestBody: required: true content: application/json: schema: type: object required: - action properties: action: type: string enum: - decide - history actorId: type: string surface: type: string logExposure: type: boolean limit: type: integer minimum: 1 maximum: 2000 responses: '200': description: Exposure history payload '201': description: Decision payload '400': description: Validation error /api/video/formats: get: summary: Get Supported Video Input/Output Formats, Duration Caps, and Optional Cost Estimate tags: - video - platform parameters: - name: planTier in: query schema: type: string enum: - free - pro - team - name: inputFormat in: query schema: type: string - name: mimeType in: query schema: type: string - name: outputPresetId in: query schema: type: string - name: durationSeconds in: query schema: type: number minimum: 0.1 responses: '200': description: Video format policy payload post: summary: Estimate Cost and Validate Planned Video Export Job Against Policy tags: - video - platform requestBody: required: true content: application/json: schema: type: object required: - planTier - inputFormat - mimeType - outputPresetId - durationSeconds properties: planTier: type: string enum: - free - pro - team inputFormat: type: string mimeType: type: string outputPresetId: type: string durationSeconds: type: number minimum: 0.1 responses: '200': description: Video job estimate payload '400': description: Validation error /api/video/export-settings: get: summary: Get Export Preset Catalog (TikTok, Reels, Shorts, MP4 Square) and Optional Watermark Decision Preview tags: - video - growth parameters: - name: planTier in: query schema: type: string enum: - free - pro - team - name: presetId in: query schema: type: string - name: container in: query schema: type: string - name: bitrateKbps in: query schema: type: number minimum: 1 - name: watermarkEnabled in: query schema: type: boolean - name: watermarkText in: query schema: type: string responses: '200': description: Export policy payload post: summary: Evaluate Export Settings with Plan-Tier Watermark Rules for TikTok/Reels/Shorts/MP4 Square Presets tags: - video - growth requestBody: required: true content: application/json: schema: type: object required: - planTier - presetId properties: planTier: type: string enum: - free - pro - team presetId: type: string container: type: string bitrateKbps: type: number minimum: 1 watermarkEnabled: type: boolean watermarkText: type: string responses: '200': description: Export settings decision payload '400': description: Validation error /api/video/timeline: get: summary: List Timeline Projects or Load One Timeline Project (Supports Up to 8 Layers for Video/Audio/Sticker/Text Tracks) tags: - video - platform parameters: - name: projectId in: query schema: type: string - name: limit in: query schema: type: integer minimum: 1 maximum: 200 responses: '200': description: Timeline project payload '404': description: Project not found post: summary: Mutate Timeline Project via Action-Based API (Create/Add Track/Add Asset/Attach Asset/Keyframe) with Keyframe-Level Adjustments tags: - video - platform requestBody: required: true content: application/json: schema: type: object required: - action properties: action: type: string enum: - create - add_track - add_asset - attach_asset - upsert_keyframe projectId: type: string durationMs: type: number minimum: 1 frameRate: type: number minimum: 12 maximum: 60 type: type: string enum: - video - audio - sticker - text - overlay name: type: string sourceUrl: type: string trackId: type: string assetId: type: string startMs: type: number minimum: 0 offsetMs: type: number minimum: 0 atMs: type: number minimum: 0 property: type: string value: type: number easing: type: string enum: - linear - ease_in - ease_out - ease_in_out responses: '200': description: Timeline updated '201': description: Timeline created '400': description: Validation error /api/video/audio-library: get: summary: List Licensed Meme/Punchline Audio Clips with Beat-Sync Suggestions for Target BPM tags: - video - audio parameters: - name: query in: query schema: type: string - name: kind in: query schema: type: string enum: - meme_loop - punchline - name: tag in: query schema: type: string - name: targetBpm in: query schema: type: integer minimum: 60 maximum: 220 - name: toleranceBpm in: query schema: type: integer minimum: 2 maximum: 60 - name: limit in: query schema: type: integer minimum: 1 maximum: 100 responses: '200': description: Audio library + beat sync suggestions payload /api/video/text-animations: get: summary: List Text Animation Presets and Generate Preview Keyframes tags: - video - motion parameters: - name: presetId in: query schema: type: string - name: startMs in: query schema: type: number minimum: 0 - name: durationMs in: query schema: type: number minimum: 1 - name: intensity in: query schema: type: number minimum: 0.2 maximum: 2 responses: '200': description: Text animation preset payload post: summary: Preview or Apply Text Animation Preset Keyframes to a Timeline Track tags: - video - motion requestBody: required: true content: application/json: schema: type: object required: - presetId properties: action: type: string enum: - preview - apply presetId: type: string startMs: type: number minimum: 0 durationMs: type: number minimum: 1 intensity: type: number minimum: 0.2 maximum: 2 projectId: type: string trackId: type: string responses: '200': description: Preview keyframes payload '201': description: Preset applied to timeline '400': description: Validation error '404': description: Preset or timeline project not found /api/video/subtitles: get: summary: Load Subtitle Style Presets and Optional Subtitle Preview with Beat-Grid Sync for Kinetic Text tags: - video - ai parameters: - name: transcript in: query schema: type: string - name: tone in: query schema: type: string - name: locale in: query schema: type: string - name: stylePresetId in: query schema: type: string - name: trendKeywords in: query schema: type: string - name: syncToBeatGrid in: query schema: type: boolean - name: bpm in: query schema: type: integer minimum: 60 maximum: 220 - name: beatOffsetMs in: query schema: type: integer minimum: -60000 maximum: 60000 responses: '200': description: Subtitle style preset + preview payload post: summary: Preview or Apply Generated Subtitles from Script or Audio-Asset Transcript Into Timeline Track with Beat-Synced Kinetic Text tags: - video - ai requestBody: required: true content: application/json: schema: type: object properties: action: type: string enum: - preview - apply transcript: type: string audioAssetId: type: string tone: type: string locale: type: string stylePresetId: type: string trendKeywords: type: array items: type: string syncToBeatGrid: type: boolean bpm: type: integer minimum: 60 maximum: 220 beatOffsetMs: type: integer minimum: -60000 maximum: 60000 projectId: type: string trackId: type: string responses: '200': description: Subtitle preview payload '201': description: Subtitles applied to timeline '400': description: Validation error '404': description: Preset or timeline project not found /api/video/render-queue: get: summary: Get Render Queue Snapshot or List Render Jobs tags: - video - platform parameters: - name: mode in: query schema: type: string enum: - snapshot - list - name: status in: query schema: type: string enum: - queued - running - completed - failed - cancelled - name: planTier in: query schema: type: string enum: - free - pro - team - name: limit in: query schema: type: integer minimum: 1 maximum: 500 responses: '200': description: Render queue payload post: summary: Mutate Render Queue (Enqueue/Claim/Progress/Complete/Fail) tags: - video - platform requestBody: required: true content: application/json: schema: type: object required: - action properties: action: type: string enum: - enqueue - claim_next - progress - complete - fail projectId: type: string outputPresetId: type: string planTier: type: string enum: - free - pro - team durationSeconds: type: number minimum: 0.1 workerId: type: string jobId: type: string progressPercent: type: number minimum: 0 maximum: 100 stage: type: string outputUrl: type: string error: type: string cancelled: type: boolean responses: '200': description: Queue mutation payload '201': description: Render job enqueued '204': description: No queued job available '400': description: Validation error /api/video/render-performance: get: summary: Get Latest Video Render Load-Test Summary or Refresh Simulation tags: - video - platform - performance parameters: - name: refresh in: query schema: type: boolean responses: '200': description: Video render performance summary payload '500': description: Policy validation or simulation failure /api/video/drafts: get: summary: Load Cloud Video Drafts Used by 15-Second Autosave and Cross-Device Resume tags: - video - platform parameters: - name: projectId in: query schema: type: string - name: limit in: query schema: type: integer minimum: 1 maximum: 200 responses: '200': description: Video draft payload '404': description: Draft not found post: summary: Save/Resume Crash-Safe Cloud Video Draft Snapshots for Cross-Device Recovery tags: - video - platform requestBody: required: true content: application/json: schema: type: object properties: action: type: string enum: - save - resume project: type: object additionalProperties: true projectId: type: string updatedAt: type: string format: date-time sourceDeviceId: type: string responses: '200': description: Draft resume payload '201': description: Draft saved payload '400': description: Validation error '404': description: Draft not found /api/media/signed-url: post: summary: Generate Signed Upload/Download Media URLS tags: - media requestBody: required: true content: application/json: schema: type: object required: - action properties: action: type: string enum: - upload - download path: type: string prefix: type: string enum: - templates - memes ownerToken: type: string contentType: type: string expiresInSeconds: type: integer minimum: 30 maximum: 86400 responses: '200': description: Signed URL generated '201': description: Signed upload URL generated '400': description: Invalid request '403': description: Private download signing requires a valid ownerToken /api/memes: get: summary: List Hosted Memes with Canonical Share Metadata tags: - memes parameters: - name: query in: query schema: type: string - name: templateSlug in: query schema: type: string - name: visibility in: query schema: type: string enum: - public - private - all - name: ownerToken in: query schema: type: string format: uuid - name: officialOnly in: query schema: type: boolean - name: excludeTemplateClones in: query schema: type: boolean - name: includeNsfw in: query schema: type: boolean - name: page in: query schema: type: integer minimum: 1 - name: pageSize in: query schema: type: integer minimum: 1 maximum: 50 responses: '200': description: Meme search results content: application/json: schema: $ref: '#/components/schemas/ListMemesResponse' '400': description: Validation error '429': description: Rate limit exceeded post: summary: Store a Rendered Meme and Return Canonical Share/Image URLS tags: - memes requestBody: required: true content: application/json: schema: type: object required: - sourceImageUrl - captions - imageDataUrl properties: templateSlug: type: string sourceImageUrl: type: string captions: type: array items: $ref: '#/components/schemas/MemeCaption' overlays: type: array items: $ref: '#/components/schemas/MemeOverlayImage' imageDataUrl: type: string visibility: type: string enum: - public - private title: type: string maxLength: 140 canvas: $ref: '#/components/schemas/MemeCanvasConfig' watermark: $ref: '#/components/schemas/MemeWatermarkConfig' generationRunId: type: - string - 'null' generationVariantId: type: - string - 'null' responses: '201': description: Meme stored content: application/json: schema: $ref: '#/components/schemas/CreateMemeResponse' '400': description: Validation error '401': description: Invalid guest session token '403': description: Origin validation failed '409': description: Idempotency conflict '422': description: Validation blocked by content policy or unchanged template clone '429': description: Rate limit exceeded /api/memes/{slug}: get: summary: Read One Meme by Opaque Slug, Public Slug, or Source Slug tags: - memes parameters: - name: slug in: path required: true schema: type: string - name: ownerToken in: query schema: type: string format: uuid responses: '200': description: Meme details content: application/json: schema: $ref: '#/components/schemas/MemeDetailResponse' '400': description: Validation error '403': description: Private meme requires owner token '404': description: Meme not found '429': description: Rate limit exceeded delete: summary: Delete One Signed-in Account-Owned Meme and Purge Public Access Paths tags: - memes - auth parameters: - name: slug in: path required: true schema: type: string responses: '200': description: Meme deleted content: application/json: schema: $ref: '#/components/schemas/DeleteMemeResponse' '400': description: Invalid slug '401': description: Authentication required '403': description: Origin validation failed '404': description: Meme not found for the signed-in user '429': description: Rate limit exceeded /api/free/templates: get: summary: Search Public Meme Templates for Agent-Friendly Discovery tags: - public-free parameters: - name: query in: query schema: type: string - name: q in: query schema: type: string - name: tag in: query schema: type: string - name: page in: query schema: type: integer minimum: 1 - name: pageSize in: query schema: type: integer minimum: 1 maximum: 50 - name: sort in: query schema: type: string enum: - curated - trending - name: mode in: query schema: type: string enum: - lexical - hybrid security: - DeveloperApiKeyAuth: [] - AgentApiKeyAuth: [] - {} responses: '200': description: Template search results content: application/json: schema: $ref: '#/components/schemas/FreeTemplateSearchResponse' '401': description: Invalid developer or agent API key '429': description: Rate limit exceeded /api/free/memes/caption: post: summary: Caption a Stored Template Without AI and Return Hosted Meme URLS with a Memesio Watermark tags: - public-free security: - DeveloperApiKeyAuth: [] - AgentApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FreeCaptionMemeRequest' responses: '201': description: Captioned meme created content: application/json: schema: $ref: '#/components/schemas/FreeCaptionMemeSuccessResponse' '400': description: Validation error or unsupported template '401': description: Invalid developer or agent API key '429': description: Rate limit exceeded /api/v1/templates/ideas: post: summary: Return Ranked Meme Template Ideas for a Prompt Using a Developer or Agent Key tags: - developer-api - templates - ai-providers 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 idea ranking payload '400': description: Validation error '401': description: Developer or agent API key required '429': description: Rate limit exceeded /api/v1/memes/caption-template: post: summary: Render a Hosted Meme from a Stored Template Using Anonymous or Keyed Caption Input tags: - developer-api - memes security: - DeveloperApiKeyAuth: [] - AgentApiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FreeCaptionMemeRequest' responses: '201': description: Captioned meme created content: application/json: schema: $ref: '#/components/schemas/FreeCaptionMemeSuccessResponse' '400': description: Validation error or unsupported template '401': description: Invalid API key when one is provided '429': description: Rate limit exceeded /api/v1/memes/caption-upload: post: summary: Upload an Image, Place Top or Bottom Caption Boxes, and Store the Hosted Meme tags: - developer-api - memes - uploads security: - DeveloperApiKeyAuth: [] - AgentApiKeyAuth: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - file - captions properties: file: type: string format: binary captions: type: string description: JSON array of caption slot objects with text, x, y, boxWidthPct, boxHeightPct, fontSize, and alignment fields. title: type: string maxLength: 140 visibility: type: string enum: - private - public watermark: type: string description: Optional JSON watermark object. Non-premium callers are forced to the default Memesio watermark; premium callers can customize enabled, text, position, and scale. responses: '201': description: Uploaded meme created content: application/json: schema: $ref: '#/components/schemas/UploadCaptionMemeSuccessResponse' '400': description: Validation error '401': description: Invalid API key when one is provided '415': description: Unsupported upload content '429': description: Rate limit exceeded /api/v1/memes/generate: get: summary: Read the Keyed Actor's Daily AI Meme Quota Snapshot tags: - developer-api - ai-providers - auth security: - DeveloperApiKeyAuth: [] - AgentApiKeyAuth: [] responses: '200': description: Current keyed actor AI quota snapshot '401': description: Developer or agent API key required post: summary: Generate AI Meme Variants Synchronously for a Developer or Standalone Agent Key tags: - developer-api - ai-providers - ai-captions security: - DeveloperApiKeyAuth: [] - AgentApiKeyAuth: [] requestBody: required: true content: application/json: schema: type: object required: - prompt properties: mode: type: string enum: - template prompt: type: string minLength: 1 maxLength: 500 flow: type: string enum: - text_to_meme captionSource: type: string enum: - input - prompt imageUrl: type: string templateId: type: string captions: type: array items: type: string maxItems: 6 editableCaptions: type: array items: $ref: '#/components/schemas/MemeCaption' maxItems: 8 tone: type: string enum: - sarcastic - deadpan - wholesome - absurd - corporate - dark-lite - brand toneCues: type: array items: type: string maxItems: 6 rewriteNote: type: string maxLength: 160 allowHeuristicFallback: type: boolean variantCount: type: number minimum: 1 maximum: 5 preferredProviderId: type: string enum: - hyperswitch_vision - onnx_local - openai_vision workspaceId: type: string correlationId: type: string responses: '200': description: Meme variant generation payload content: application/json: schema: $ref: '#/components/schemas/AiMemeGenerationSucceededResponse' '400': description: Validation error '401': description: Developer or agent API key required '429': description: Daily AI quota exceeded '500': description: Provider execution failure components: schemas: AiJobSubmitRequest: type: object required: - capability properties: capability: type: string enum: - face_swap - background_remove - caption_generate input: type: object additionalProperties: true maxAttempts: type: integer minimum: 1 maximum: 10 timeoutMs: type: integer minimum: 1000 maximum: 300000 runAfterMs: type: integer minimum: 0 traceId: type: string pattern: ^[a-f0-9]{32}$ actorId: type: string workspaceId: type: string AiJob: type: object required: - id - status - capability properties: id: type: string traceId: type: string pattern: ^[a-f0-9]{32}$ capability: type: string status: type: string attempts: type: integer maxAttempts: type: integer timeoutMs: type: integer createdAt: type: string format: date-time updatedAt: type: string format: date-time MemeCaption: type: object required: - id - text - x - y - fontSize properties: id: type: string text: type: string x: type: number y: type: number fontSize: type: number rotationDeg: type: number hidden: type: boolean locked: type: boolean boxWidthPct: type: number boxHeightPct: type: number paddingPct: type: number maxLines: type: integer lineHeight: type: number backgroundEnabled: type: boolean backgroundColor: type: string backgroundOpacity: type: number letterSpacingEm: type: number shadowStrength: type: number color: type: string stroke: type: string fontFamily: type: string enum: - impact - arial textAlign: type: string enum: - left - center - right semanticRole: type: string enum: - setup - contrast - punchline - reaction - label preferredCase: type: string enum: - uppercase - sentence - title - preserve exampleText: type: string recommendedWordsMin: type: integer minimum: 1 recommendedWordsMax: type: integer minimum: 1 recommendedCharsMin: type: integer minimum: 1 recommendedCharsMax: type: integer minimum: 1 MemeOverlayImage: type: object required: - id - label - imageUrl - x - y - widthPercent - rotationDeg - opacity properties: id: type: string label: type: string imageUrl: type: string sourceImageUrl: type: string x: type: number y: type: number widthPercent: type: number rotationDeg: type: number opacity: type: number hidden: type: boolean locked: type: boolean flippedX: type: boolean backgroundRemoved: type: boolean MemeCanvasConfig: type: object required: - aspectRatio - focusX - focusY - zoomPercent - crop - spacing - guides - sourceAdjustments - layerOrder - transform properties: aspectRatio: type: string enum: - original - '1:1' - '4:5' - '16:9' focusX: type: number focusY: type: number zoomPercent: type: number crop: type: object required: - x - y - width - height properties: x: type: number y: type: number width: type: number height: type: number spacing: type: object additionalProperties: true guides: type: object additionalProperties: true sourceAdjustments: type: object additionalProperties: true layerOrder: type: array items: type: string transform: type: object additionalProperties: true MemeWatermarkConfig: type: object required: - enabled - text - position - scale properties: enabled: type: boolean text: type: string position: type: string enum: - top_left - top_right - bottom_left - bottom_right scale: type: number MemeSummary: type: object required: - slug - shareSlug - shareUrl - title - altText - tags - templateSlug - visibility - createdAt - imageUrl - canonicalImageUrl - nsfwStatus - shareViews properties: slug: type: string shareSlug: type: string shareUrl: type: string title: type: string altText: type: string tags: type: array items: type: string templateSlug: type: string visibility: type: string enum: - public - private createdAt: type: string format: date-time imageUrl: type: string canonicalImageUrl: type: string nsfwStatus: type: string enum: - clear - flagged shareViews: type: integer minimum: 0 MemeDetailResponse: allOf: - $ref: '#/components/schemas/MemeSummary' - type: object required: - sourceImageUrl - captions - overlays - canvas - watermark properties: sourceImageUrl: type: string captions: type: array items: $ref: '#/components/schemas/MemeCaption' overlays: type: array items: $ref: '#/components/schemas/MemeOverlayImage' canvas: $ref: '#/components/schemas/MemeCanvasConfig' watermark: $ref: '#/components/schemas/MemeWatermarkConfig' ListMemesResponse: type: object required: - items - total - nextPage - page - pageSize properties: items: type: array items: $ref: '#/components/schemas/MemeSummary' total: type: integer minimum: 0 nextPage: type: - integer - 'null' page: type: integer minimum: 1 pageSize: type: integer minimum: 1 maximum: 50 CreateMemeResponse: type: object required: - slug - shareSlug - shareUrl - imageUrl - canonicalImageUrl - altText - tags - ownerToken - visibility - guestSessionId properties: slug: type: string shareSlug: type: string shareUrl: type: string imageUrl: type: string canonicalImageUrl: type: string altText: type: string tags: type: array items: type: string ownerToken: type: string visibility: type: string enum: - public - private guestSessionId: type: - string - 'null' DeleteMemeResponse: type: object required: - ok - deleted - slug - shareSlug properties: ok: type: boolean deleted: type: boolean slug: type: string shareSlug: type: string MemeGenerationVariant: type: object required: - id - mode - providerId - variantKind - memeUrl - pageUrl - templateName - fallbackUsed - attempts - estimatedCostUsd properties: id: type: string mode: type: string enum: - template providerId: type: string variantKind: type: string enum: - template_captioned - rendered_image memeUrl: type: - string - 'null' pageUrl: type: - string - 'null' templateName: type: - string - 'null' templateSlug: type: - string - 'null' sourceImageUrl: type: - string - 'null' templateSelectionStrategy: type: - string - 'null' enum: - provided_template - provided_image - library_search - recommendation - null captionGenerationStrategy: type: - string - 'null' enum: - openai - heuristic - provided - null captions: type: array items: $ref: '#/components/schemas/MemeCaption' editable: type: boolean fallbackUsed: type: boolean attempts: type: array items: type: object additionalProperties: true estimatedCostUsd: type: number minimum: 0 AiMemeGenerationSucceededResponse: type: object required: - ok - flow - mode - status - variantCount - variants properties: ok: type: boolean const: true runId: type: string flow: type: string enum: - text_to_meme mode: type: string enum: - template status: type: string const: succeeded variantCount: type: integer minimum: 0 variants: type: array items: $ref: '#/components/schemas/MemeGenerationVariant' degradedFromAsync: type: boolean AiMemeGenerationFailedResponse: type: object required: - ok - flow - mode - status properties: ok: type: boolean runId: type: string flow: type: string enum: - text_to_meme mode: type: string enum: - template status: type: string enum: - failed - canceled errorCode: type: - string - 'null' errorMessage: type: - string - 'null' AgentProfile: type: object required: - id - slug - name - description - websiteUrl - systemPrompt - watermarkText - stylePreset - locale - premiumStatus - status - createdAt - updatedAt properties: id: type: string slug: type: string name: type: string description: type: string websiteUrl: type: - string - 'null' systemPrompt: type: - string - 'null' watermarkText: type: - string - 'null' stylePreset: type: - string - 'null' locale: type: - string - 'null' premiumStatus: type: string enum: - pending - approved - denied status: type: string enum: - active - disabled createdAt: type: string format: date-time updatedAt: type: string format: date-time AgentApiKey: type: object required: - id - keyPrefix - scopes - status - createdAt - revokedAt properties: id: type: string keyPrefix: type: string scopes: type: array items: type: string enum: - generate - publish - analytics - admin status: type: string enum: - active - revoked createdAt: type: string format: date-time revokedAt: type: - string - 'null' format: date-time StandaloneAgentBootstrapResponse: type: object required: - ok - accountType - agent - key properties: ok: type: boolean const: true accountType: type: string enum: - standalone_agent - standalone_agent_compat agent: $ref: '#/components/schemas/AgentProfile' key: allOf: - type: object required: - id - keyPrefix - scopes - status - createdAt - revokedAt properties: id: type: string keyPrefix: type: string scopes: type: array items: type: string enum: - generate - publish - analytics - admin status: type: string enum: - active - revoked createdAt: type: string format: date-time revokedAt: type: - string - 'null' format: date-time - type: object required: - plaintextKey - authMode properties: plaintextKey: type: string authMode: type: string enum: - agent - developer FreeMemeWatermark: type: object description: Caption API requests accept watermark input, but non-premium callers are forced to the default Memesio watermark. Premium callers can customize enabled, text, position, and scale. properties: enabled: type: boolean text: type: string maxLength: 64 position: type: string enum: - top_left - top_right - bottom_left - bottom_right scale: type: number minimum: 0.6 maximum: 3 FreeCaptionMemeRequest: type: object required: - templateSlug - captions properties: templateSlug: type: string captions: type: array items: oneOf: - type: string maxLength: 300 - $ref: '#/components/schemas/CaptionInput' title: type: string maxLength: 140 visibility: type: string enum: - private - public watermark: $ref: '#/components/schemas/FreeMemeWatermark' FreeCaptionMemeSuccessResponse: type: object required: - success - data properties: success: type: boolean const: true data: type: object required: - slug - shareSlug - templateSlug - title - visibility - imageUrl - canonicalImageUrl - altText - tags - apiUrl - pageUrl - ownerToken - captions - watermark properties: slug: type: string shareSlug: type: string templateSlug: type: string title: type: string visibility: type: string enum: - private - public imageUrl: type: string canonicalImageUrl: type: string altText: type: string tags: type: array items: type: string apiUrl: type: string pageUrl: type: string ownerToken: type: string captions: type: array items: type: string watermark: $ref: '#/components/schemas/FreeMemeWatermark' CaptionInput: type: object required: - text properties: id: type: string maxLength: 64 text: type: string maxLength: 300 x: type: number y: type: number fontSize: type: number boxWidthPct: type: number boxHeightPct: type: number maxLines: type: integer minimum: 1 textAlign: type: string enum: - left - center - right fontFamily: type: string enum: - impact - arial UploadCaptionMemeSuccessResponse: type: object required: - ok - data properties: ok: type: boolean const: true data: type: object required: - slug - shareSlug - templateSlug - title - visibility - sourceImageUrl - imageUrl - canonicalImageUrl - altText - tags - apiUrl - pageUrl - ownerToken - captions - watermark properties: slug: type: string shareSlug: type: string templateSlug: type: string title: type: string visibility: type: string enum: - private - public sourceImageUrl: type: string imageUrl: type: string canonicalImageUrl: type: string altText: type: string tags: type: array items: type: string apiUrl: type: string pageUrl: type: string ownerToken: type: string captions: type: array items: $ref: '#/components/schemas/CaptionInput' watermark: $ref: '#/components/schemas/FreeMemeWatermark' FreeTemplateSearchResponse: type: object required: - items - total - nextPage - page - pageSize properties: searchMode: type: string enum: - lexical - hybrid fallbackApplied: type: boolean items: type: array items: type: object required: - id - sourceTemplateId - slug - name - description - imageUrl - width - height - captionCount - boxCount - captions properties: id: type: string sourceTemplateId: type: - string - 'null' slug: type: string name: type: string description: type: string imageUrl: type: string width: type: - number - 'null' height: type: - number - 'null' captionCount: type: integer minimum: 0 boxCount: type: integer minimum: 0 captions: type: array items: $ref: '#/components/schemas/MemeCaption' tags: type: array items: type: string total: type: integer minimum: 0 nextPage: type: - integer - 'null' minimum: 1 page: type: integer minimum: 1 pageSize: type: integer minimum: 1 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 .'