openapi.yaml

openapi: 3.1.0
info:
  title: Zernio API
  version: "1.0.1"
  description: |
    API reference for Zernio. Authenticate with a Bearer API key.
    Base URL: https://zernio.com/api
  termsOfService: https://zernio.com/tos
  contact:
    name: Zernio Support
    url: https://zernio.com
    email: support@zernio.com
  # RapidAPI extensions for Hub listing
  x-logo:
    url: https://zernio.com/icon.png?v=3
  x-long-description: |
    Zernio is the social media API that replaces 14 integrations. Schedule posts, retrieve analytics,
    manage DMs, comments, and reviews across Twitter/X, Instagram, TikTok, LinkedIn, Facebook,
    YouTube, Threads, Reddit, Pinterest, Bluesky, Telegram, Google Business, and Snapchat, all
    from a single REST API.

    Key features: Unified posting to 14 platforms, aggregated analytics, unified inbox (DMs, comments, reviews), webhooks, OAuth connect, queue scheduling, and white-label support for agencies managing unlimited accounts.

    Supported platforms: Twitter/X, Instagram, WhatsApp, Facebook, LinkedIn, TikTok, YouTube, Pinterest, Reddit, Bluesky, Threads, Google Business, Telegram, Snapchat.
  x-category: Social
  x-website: https://zernio.com
  x-thumbnail: https://rapidapi-prod-apis.s3.amazonaws.com/b24d3df5-563c-4a50-9e1e-1ad3eb1fce69.png
  x-version-lifecycle: ACTIVE
  x-badges:
    - name: "social media"
      value: "social media"
    - name: "scheduling"
      value: "scheduling"
    - name: "instagram"
      value: "instagram"
    - name: "tiktok"
      value: "tiktok"
    - name: "twitter"
      value: "twitter"
    - name: "linkedin"
      value: "linkedin"
    - name: "facebook"
      value: "facebook"
    - name: "youtube"
      value: "youtube"
    - name: "social media api"
      value: "social media api"
    - name: "posting"
      value: "posting"

# RapidAPI Hub documentation tab (README)
x-documentation:
  readme: |
    # Zernio API

    The social media API that replaces 14 integrations. Build social media features into your app in minutes, not months.

    ## Quick Start

    **Base URL:** `https://zernio.com/api/v1`

    **Authentication:** All requests require a Bearer API key in the `Authorization` header.

    ```bash
    curl https://zernio.com/api/v1/user \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    Get your API key at [zernio.com/dashboard/api-keys](https://zernio.com/dashboard/api-keys).

    ## Core Concepts

    | Concept | Description |
    |---------|-------------|
    | **Profiles** | Containers that organize social accounts into brands or projects |
    | **Accounts** | Connected social media accounts belonging to a profile |
    | **Posts** | Content scheduled or published to one or more accounts |
    | **Queue** | Recurring time slots for automatic post scheduling |

    ## Create a Post

    ```bash
    curl -X POST https://zernio.com/api/v1/post \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "profileId": "your-profile-id",
        "text": "Hello from Zernio API!",
        "socialAccountIds": ["account-1", "account-2"],
        "scheduledAt": "2025-01-15T10:00:00Z"
      }'
    ```

    This single call publishes or schedules the post to all selected accounts across any platform.

    ## Supported Platforms

    | Platform | Post | Stories/Reels | Analytics | Inbox |
    |----------|------|---------------|-----------|-------|
    | Twitter/X | Yes | - | Yes | Yes |
    | Instagram | Yes | Yes | Yes | Yes |
    | Facebook | Yes | Stories | Yes | Yes |
    | LinkedIn | Yes | - | Yes | - |
    | TikTok | Yes | - | Yes | - |
    | YouTube | Yes | Shorts | Yes | Yes |
    | Pinterest | Yes | - | Yes | - |
    | Reddit | Yes | - | - | Yes |
    | Bluesky | Yes | - | - | Yes |
    | Threads | Yes | - | Yes | Yes |
    | Google Business | Yes | - | - | Yes |
    | Telegram | Yes | - | - | - |
    | Snapchat | Yes | - | - | - |

    ## Rate Limits

    | Plan | Requests/min | Posts/month |
    |------|-------------|-------------|
    | Free | 60 | 20 |
    | Build | 120 | 120 |
    | Accelerate | 600 | Unlimited |
    | Unlimited | 1,200 | Unlimited |

    All responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers.

    ## Webhooks

    Receive real-time notifications for post status changes, account events, and incoming messages:

    - `post.scheduled` - Post created and scheduled for publishing
    - `post.published` - Post successfully published
    - `post.failed` - Post failed on all platforms
    - `post.partial` - Post published to some platforms, failed on others
    - `post.cancelled` - Post publishing was cancelled
    - `post.recycled` - Post recycled (cloned and re-scheduled)
    - `account.connected` - Social account connected
    - `account.disconnected` - Social account disconnected (token expired)
    - `message.received` - New DM received
    - `message.sent` - DM sent via the API
    - `comment.received` - New comment received on a post
    - `webhook.test` - Test event sent when verifying a webhook endpoint

    Webhook payloads are signed with HMAC-SHA256 via the `X-Zernio-Signature` header.

    ## Full Documentation

    For complete guides, platform-specific details, and SDK references, visit [docs.zernio.com](https://docs.zernio.com).

    ## SDKs

    Official SDKs available for: [Node.js](https://www.npmjs.com/package/@zernio/node), [Python](https://pypi.org/project/zernio-sdk), Go, Ruby, Java, PHP, .NET, and Rust.

servers:
  - url: https://zernio.com/api
    description: Production
  - url: http://localhost:3000/api
    description: Local
tags:
  - name: Posts
  - name: Users
  - name: Usage
  - name: Profiles
  - name: Accounts
  - name: Account Groups
  - name: API Keys
  - name: Invites
  - name: Connect
  - name: Media
  - name: Reddit Search
  - name: Facebook
  - name: GMB Reviews
  - name: GMB Food Menus
  - name: GMB Location Details
  - name: GMB Media
  - name: GMB Attributes
  - name: GMB Place Actions
  - name: LinkedIn Mentions
  - name: Pinterest
  - name: TikTok
  - name: Queue
  - name: Analytics
  - name: Inbox Access
    description: |
      Check and manage inbox feature access.
  - name: Messages
    description: |
      Unified inbox API for managing conversations and direct messages across all connected accounts.
      All endpoints aggregate data from multiple social accounts in a single API call.
      Requires Inbox addon.
  - name: Comments
    description: |
      Unified inbox API for managing comments on posts across all connected accounts.
      Supports commenting on third-party posts for platforms that allow it (YouTube, Twitter, Reddit, Bluesky, Threads).
      All endpoints aggregate data from multiple social accounts in a single API call.
      Requires Inbox addon.
  - name: Reviews
    description: |
      Unified inbox API for managing reviews on Facebook Pages and Google Business accounts.
      All endpoints aggregate data from multiple social accounts in a single API call.
      Requires Inbox addon.
  - name: Twitter Engagement
    description: |
      X/Twitter-specific engagement endpoints for retweeting, bookmarking, and following.
      Rate limits: 50 requests per 15-min window per user. Retweets share the 300/3hr creation limit with tweet creation.
  - name: Validate
    description: |
      Pre-flight validation endpoints. Check post content, character limits, media URLs, and subreddit existence before publishing.
  - name: Account Settings
    description: |
      Platform-specific account settings: Facebook persistent menu, Instagram ice breakers, and Telegram bot commands.
  - name: Contacts
    description: |
      Cross-platform contact management (CRM). Contacts are unified identities linked to platform-specific
      channels (phone, IGSID, etc.). Created automatically when messages arrive, or manually via API.
  - name: Custom Fields
    description: |
      Custom field definitions for contacts. Define fields (text, number, date, boolean, select) that can be
      set on any contact for segmentation and personalization.
  - name: Broadcasts
    description: |
      Platform-agnostic broadcast campaigns. Send bulk messages to contacts via any inbox platform.
      WhatsApp broadcasts use templates; other platforms use generic messages.
  - name: Sequences
    description: |
      Drip campaign sequences. Send a series of messages to enrolled contacts with configurable delays
      between steps. Supports auto-exit on reply or unsubscribe.
  - name: Comment Automations
    description: |
      Comment-to-DM growth automations. Set up keyword triggers on Instagram/Facebook posts so
      commenters automatically receive a DM. Supports dedup, optional public comment reply, and
      auto-creates contacts.
  - name: Ads
    description: |
      Paid advertising management across Meta (Facebook/Instagram), Google, TikTok, LinkedIn, Pinterest, and X/Twitter.
      Create, boost, pause/resume ads and campaigns, view metrics, and manage audiences.
      Requires the Ads add-on.
  - name: Ad Campaigns
    description: |
      Campaign-level operations. Campaigns are virtual aggregations of ads grouped by their platform campaign ID.
      List campaigns with aggregate metrics, or pause/resume all ads in a campaign at once.
      Requires the Ads add-on.
  - name: Ad Audiences
    description: |
      Custom audience management for ad targeting. Create customer lists, website retargeting audiences,
      and lookalike audiences. Upload user data (hashed server-side). Currently Meta-only for creation,
      read-only for other platforms.
      Requires the Ads add-on.
  - name: Webhooks
    description: |
      Configure webhooks for real-time notifications. Events: post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled, account.connected, account.disconnected, message.received, message.sent, comment.received, webhook.test.
      Security: optional HMAC-SHA256 signature in X-Zernio-Signature header. Configure a secret key to enable verification. Custom headers supported.
  - name: Webhook Events
    description: |
      Incoming webhook deliveries sent by Zernio to your configured endpoint URL.
  - name: Logs
    description: |
      Publishing logs for transparency and debugging. Each log includes the platform API endpoint, HTTP status code, request/response bodies, duration, and retry attempts. Logs are automatically deleted after 7 days.
  - name: WhatsApp
    description: |
      WhatsApp Business API. Contact, broadcast, and group endpoints are **deprecated** in favor of the
      cross-platform `/v1/contacts`, `/v1/broadcasts`, and `/v1/sequences` endpoints.
      Template, business profile, and phone number endpoints remain active (no cross-platform equivalent).
      All endpoints require an accountId parameter identifying the WhatsApp-connected social account.
  - name: WhatsApp Flows
    description: |
      WhatsApp Flows let you build native interactive forms, surveys, and booking experiences inside WhatsApp.
      Flows are created in DRAFT status, populated with a Flow JSON definition, then published for sending.
      Published flows are immutable; to update, create a new flow (optionally cloning the old one).
      All endpoints require an accountId parameter identifying the WhatsApp-connected social account.
  - name: WhatsApp Phone Numbers
    description: |
      Manage WhatsApp phone numbers: purchase, verify, and release numbers for your WhatsApp Business account.
      Requires a paid plan.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: API key authentication - use your Zernio API key as a Bearer token
    connectToken:
      type: apiKey
      in: header
      name: X-Connect-Token
      description: |
        Short-lived connect token for API users during OAuth flows. 
        Automatically generated when initiating OAuth without a browser session.
        Valid for 15 minutes. Used to authenticate Facebook page selection API calls.
  parameters:
    PageParam:
      name: page
      in: query
      description: Page number (1-based)
      schema: { type: integer, minimum: 1, default: 1 }
    LimitParam:
      name: limit
      in: query
      description: Page size
      schema: { type: integer, minimum: 1, maximum: 100, default: 10 }
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Unauthorized
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Not found
  schemas:
    RedditPost:
      type: object
      description: A normalized Reddit post returned by the feed and search endpoints
      properties:
        id: { type: string, description: Reddit post ID (without type prefix) }
        fullname: { type: string, description: "Reddit fullname (e.g. t3_abc123)" }
        title: { type: string }
        author: { type: string }
        subreddit: { type: string }
        url: { type: string, description: Post URL (may be a gallery URL, external link, or self-post URL) }
        permalink: { type: string, description: Full permalink to the Reddit post }
        selftext: { type: string, description: Self-post body text (empty string for link posts) }
        createdUtc: { type: number, description: Unix timestamp of post creation }
        score: { type: integer }
        numComments: { type: integer }
        over18: { type: boolean, description: Whether the post is marked NSFW }
        stickied: { type: boolean }
        flairText: { type: string, nullable: true, description: Link flair text if set }
        isGallery: { type: boolean, description: Whether the post is a gallery with multiple images }
        galleryImages:
          type: array
          description: Individual image URLs for gallery posts (only present when isGallery is true)
          items: { type: string, format: uri }
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        details:
          type: object
          additionalProperties: true
    WhatsAppTemplateButton:
      type: object
      required: [type, text]
      properties:
        type:
          type: string
          enum: [quick_reply, url, phone_number, otp, flow, mpm, catalog]
        text:
          type: string
        url:
          type: string
          format: uri
          description: Required when type is URL
        example:
          type: array
          items: { type: string }
          description: Example values for URL suffix variables
        phone_number:
          type: string
          description: Required when type is phone_number
        otp_type:
          type: string
          enum: [copy_code, one_tap, zero_tap]
          description: Required when type is otp
        autofill_text:
          type: string
        package_name:
          type: string
        signature_hash:
          type: string
        flow_id:
          type: string
        flow_name:
          type: string
        flow_json:
          type: string
        flow_action:
          type: string
        navigate_screen:
          type: string
    WhatsAppTemplateComponent:
      oneOf:
        - $ref: '#/components/schemas/WhatsAppHeaderComponent'
        - $ref: '#/components/schemas/WhatsAppBodyComponent'
        - $ref: '#/components/schemas/WhatsAppFooterComponent'
        - $ref: '#/components/schemas/WhatsAppButtonsComponent'
      discriminator:
        propertyName: type
        mapping:
          header: '#/components/schemas/WhatsAppHeaderComponent'
          body: '#/components/schemas/WhatsAppBodyComponent'
          footer: '#/components/schemas/WhatsAppFooterComponent'
          buttons: '#/components/schemas/WhatsAppButtonsComponent'
    WhatsAppHeaderComponent:
      type: object
      required: [type, format]
      properties:
        type:
          type: string
          enum: [header]
        format:
          type: string
          enum: [text, image, video, gif, document, location]
        text:
          type: string
          description: Header text (may include {{1}} variable). Used when format is TEXT.
        example:
          type: object
          properties:
            header_text:
              type: array
              items: { type: string }
              description: Sample values for header text variables
            header_handle:
              type: array
              minItems: 1
              maxItems: 1
              items:
                type: string
                format: uri
              description: When the header format is a media type (image, video, gif, document), provide a public URL here. Zernio will download and upload it to WhatsApp on your behalf, replacing it with the internal file handle before creating the template.
    WhatsAppBodyComponent:
      type: object
      required: [type, text]
      properties:
        type:
          type: string
          enum: [body]
        text:
          type: string
          description: Body text with optional {{n}} variables
        add_security_recommendation:
          type: boolean
          description: Add security recommendation text (authentication templates only)
        example:
          type: object
          properties:
            body_text:
              type: array
              items:
                type: array
                items: { type: string }
              description: Sample values for body variables (array of arrays)
    WhatsAppFooterComponent:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [footer]
        text:
          type: string
          description: Static footer text
        code_expiration_minutes:
          type: integer
          minimum: 1
          description: OTP code expiry in minutes (authentication templates only)
    WhatsAppButtonsComponent:
      type: object
      required: [type, buttons]
      properties:
        type:
          type: string
          enum: [buttons]
        buttons:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/WhatsAppTemplateButton'
    FoodMenuLabel:
      type: object
      required: [displayName]
      properties:
        displayName: { type: string, description: Display name of the item/section/menu }
        description: { type: string, description: Optional description }
        languageCode: { type: string, description: "BCP-47 language code (e.g. en, es)" }
    Money:
      type: object
      required: [currencyCode, units]
      properties:
        currencyCode: { type: string, description: "ISO 4217 currency code (e.g. USD, EUR)" }
        units: { type: string, description: Whole units of the amount }
        nanos: { type: integer, description: Nano units (10^-9) of the amount }
    FoodMenuItemAttributes:
      type: object
      properties:
        price: { $ref: '#/components/schemas/Money' }
        spiciness: { type: string, description: "Spiciness level (e.g. MILD, MEDIUM, HOT)" }
        allergen:
          type: array
          items: { type: string }
          description: "Allergens (e.g. DAIRY, GLUTEN, SHELLFISH)"
        dietaryRestriction:
          type: array
          items: { type: string }
          description: "Dietary labels (e.g. VEGETARIAN, VEGAN, GLUTEN_FREE)"
        servesNumPeople: { type: integer, description: Number of people the item serves }
        preparationMethods:
          type: array
          items: { type: string }
          description: "Preparation methods (e.g. GRILLED, FRIED)"
        mediaKeys:
          type: array
          items: { type: string }
          description: Media references for item photos
    FoodMenuItem:
      type: object
      required: [labels]
      properties:
        labels:
          type: array
          items: { $ref: '#/components/schemas/FoodMenuLabel' }
        attributes: { $ref: '#/components/schemas/FoodMenuItemAttributes' }
        options:
          type: array
          items:
            type: object
            properties:
              labels:
                type: array
                items: { $ref: '#/components/schemas/FoodMenuLabel' }
              attributes: { $ref: '#/components/schemas/FoodMenuItemAttributes' }
          description: Item variants/options (e.g. sizes, preparations)
    FoodMenuSection:
      type: object
      required: [labels]
      properties:
        labels:
          type: array
          items: { $ref: '#/components/schemas/FoodMenuLabel' }
        items:
          type: array
          items: { $ref: '#/components/schemas/FoodMenuItem' }
    FoodMenu:
      type: object
      required: [labels]
      properties:
        labels:
          type: array
          items: { $ref: '#/components/schemas/FoodMenuLabel' }
        sections:
          type: array
          items: { $ref: '#/components/schemas/FoodMenuSection' }
        cuisines:
          type: array
          items: { type: string }
          description: "Cuisine types (e.g. AMERICAN, ITALIAN, JAPANESE)"
        sourceUrl:
          type: string
          description: URL of the original menu source
    YouTubeDailyViewsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        videoId:
          type: string
          description: The YouTube video ID
        dateRange:
          type: object
          properties:
            startDate:
              type: string
              format: date
            endDate:
              type: string
              format: date
        totalViews:
          type: integer
          description: Sum of views across all days in the range
        dailyViews:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                format: date
              views:
                type: integer
              estimatedMinutesWatched:
                type: number
              averageViewDuration:
                type: number
                description: Average view duration in seconds
              subscribersGained:
                type: integer
              subscribersLost:
                type: integer
              likes:
                type: integer
              comments:
                type: integer
              shares:
                type: integer
        lastSyncedAt:
          type: string
          format: date-time
          nullable: true
          description: When the data was last synced from YouTube
        scopeStatus:
          type: object
          properties:
            hasAnalyticsScope:
              type: boolean
    YouTubeScopeMissingResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: "To access daily video analytics, please reconnect your YouTube account to grant the required permissions."
        code:
          type: string
          example: youtube_analytics_scope_missing
        scopeStatus:
          type: object
          properties:
            hasAnalyticsScope:
              type: boolean
              example: false
            requiresReauthorization:
              type: boolean
              example: true
            reauthorizeUrl:
              type: string
              format: uri
              description: URL to redirect user for reauthorization
    InstagramAccountInsightsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        accountId:
          type: string
          description: The Zernio SocialAccount ID
        platform:
          type: string
          example: "instagram"
        dateRange:
          type: object
          properties:
            since:
              type: string
              format: date
            until:
              type: string
              format: date
        metricType:
          type: string
          enum: [time_series, total_value]
        breakdown:
          type: string
          description: Breakdown dimension used (only present when breakdown was requested)
        metrics:
          type: object
          description: |
            Object keyed by metric name. For time_series: each metric has "total" (number) and "values" (array of {date, value}).
            For total_value: each metric has "total" (number) and optionally "breakdowns" (array of {dimension, value}).
          additionalProperties:
            type: object
            properties:
              total:
                type: number
                description: Sum or aggregate value for the metric
              values:
                type: array
                description: Daily values (only for time_series)
                items:
                  type: object
                  properties:
                    date:
                      type: string
                      format: date
                    value:
                      type: number
              breakdowns:
                type: array
                description: Breakdown values (only for total_value with breakdown)
                items:
                  type: object
                  properties:
                    dimension:
                      type: string
                    value:
                      type: number
        dataDelay:
          type: string
          example: "Data may be delayed up to 48 hours"
    InstagramDemographicsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        accountId:
          type: string
          description: The Zernio SocialAccount ID
        platform:
          type: string
          example: "instagram"
        metric:
          type: string
          enum: [follower_demographics, engaged_audience_demographics]
        timeframe:
          type: string
          enum: [this_week, this_month]
          description: The timeframe used for demographic data
        demographics:
          type: object
          description: Object keyed by breakdown dimension (age, city, country, gender)
          additionalProperties:
            type: array
            items:
              type: object
              properties:
                dimension:
                  type: string
                  description: The dimension value (e.g., "25-34", "US", "M")
                value:
                  type: number
                  description: Count of accounts in this dimension
        note:
          type: string
          example: "Demographics show top 45 entries per dimension. Requires 100+ followers."
    YouTubeDemographicsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        accountId:
          type: string
          description: The Zernio SocialAccount ID
        platform:
          type: string
          example: "youtube"
        demographics:
          type: object
          description: Object keyed by breakdown dimension (age, gender, country)
          additionalProperties:
            type: array
            items:
              type: object
              properties:
                dimension:
                  type: string
                  description: The dimension value (e.g., "25-34", "US", "male")
                value:
                  type: number
                  description: Viewer percentage (age/gender) or view count (country)
        dateRange:
          type: object
          properties:
            startDate:
              type: string
              example: "2026-01-01"
            endDate:
              type: string
              example: "2026-03-31"
        note:
          type: string
          example: "Age/gender values are viewer percentages (0-100). Country values are view counts. Data based on signed-in viewers only, with 2-3 day delay."
    Webhook:
      type: object
      description: Individual webhook configuration for receiving real-time notifications
      properties:
        _id:
          type: string
          description: Unique webhook identifier
        name:
          type: string
          description: Webhook name (for identification)
          maxLength: 50
        url:
          type: string
          format: uri
          description: Webhook endpoint URL
        secret:
          type: string
          description: Secret key for HMAC-SHA256 signature (not returned in responses for security)
        events:
          type: array
          items:
            type: string
            enum: [post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled, account.connected, account.disconnected, message.received, message.sent, comment.received]
          description: Events subscribed to
        isActive:
          type: boolean
          description: Whether webhook delivery is enabled
        lastFiredAt:
          type: string
          format: date-time
          description: Timestamp of last successful webhook delivery
        failureCount:
          type: integer
          description: Consecutive delivery failures (resets on success, webhook disabled at 10)
        customHeaders:
          type: object
          additionalProperties:
            type: string
          description: Custom headers included in webhook requests
    WebhookLog:
      type: object
      description: Webhook delivery log entry
      properties:
        _id:
          type: string
        webhookId:
          type: string
          description: ID of the webhook that was triggered
        webhookName:
          type: string
          description: Name of the webhook that was triggered
        event:
          type: string
          enum: [post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled, account.connected, account.disconnected, message.received, message.sent, comment.received, webhook.test]
        url:
          type: string
          format: uri
        status:
          type: string
          enum: [success, failed]
        statusCode:
          type: integer
          description: HTTP status code from webhook endpoint
        requestPayload:
          type: object
          description: Payload sent to webhook endpoint
        responseBody:
          type: string
          description: Response body from webhook endpoint (truncated to 10KB)
        errorMessage:
          type: string
          description: Error message if delivery failed
        attemptNumber:
          type: integer
          description: Delivery attempt number (max 3 retries)
        responseTime:
          type: integer
          description: Response time in milliseconds
        createdAt:
          type: string
          format: date-time
    WebhookPayloadPost:
      type: object
      description: Webhook payload for post events
      required: [id, event, post, timestamp]
      properties:
        id:
          type: string
          description: Stable webhook event ID
        event:
          type: string
          enum: [post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled]
        post:
          type: object
          required: [id, content, status, scheduledFor, platforms]
          properties:
            id:
              type: string
            content:
              type: string
            status:
              type: string
            scheduledFor:
              type: string
              format: date-time
            publishedAt:
              type: string
              format: date-time
            platforms:
              type: array
              items:
                type: object
                required: [platform, status]
                properties:
                  platform:
                    type: string
                  status:
                    type: string
                  platformPostId:
                    type: string
                  publishedUrl:
                    type: string
                  error:
                    type: string
        timestamp:
          type: string
          format: date-time
    WebhookPayloadAccountConnected:
      type: object
      description: Webhook payload for account connected events
      required: [id, event, account, timestamp]
      properties:
        id:
          type: string
          description: Stable webhook event ID
        event:
          type: string
          enum: [account.connected]
        account:
          type: object
          required: [accountId, profileId, platform, username]
          properties:
            accountId:
              type: string
              description: The account's unique identifier (same as used in /v1/accounts/{accountId})
            profileId:
              type: string
              description: The profile's unique identifier this account belongs to
            platform:
              type: string
            username:
              type: string
            displayName:
              type: string
        timestamp:
          type: string
          format: date-time
    WebhookPayloadAccountDisconnected:
      type: object
      description: Webhook payload for account disconnected events
      required: [id, event, account, timestamp]
      properties:
        id:
          type: string
          description: Stable webhook event ID
        event:
          type: string
          enum: [account.disconnected]
        account:
          type: object
          required: [accountId, profileId, platform, username, disconnectionType, reason]
          properties:
            accountId:
              type: string
              description: The account's unique identifier (same as used in /v1/accounts/{accountId})
            profileId:
              type: string
              description: The profile's unique identifier this account belongs to
            platform:
              type: string
            username:
              type: string
            displayName:
              type: string
            disconnectionType:
              type: string
              enum: [intentional, unintentional]
              description: Whether the disconnection was intentional (user action) or unintentional (token expired/revoked)
            reason:
              type: string
              description: Human-readable reason for the disconnection
        timestamp:
          type: string
          format: date-time
    WebhookPayloadComment:
      type: object
      description: Webhook payload for comment received events (Instagram, Facebook, Twitter/X, YouTube, LinkedIn, Bluesky, Reddit)
      required: [id, event, comment, post, account, timestamp]
      properties:
        id:
          type: string
          description: Stable webhook event ID
        event:
          type: string
          enum: [comment.received]
        comment:
          type: object
          required: [id, postId, platformPostId, platform, text, author, createdAt, isReply, parentCommentId]
          properties:
            id:
              type: string
              description: Platform comment ID
            postId:
              type: string
              description: Internal post ID
            platformPostId:
              type: string
              description: Platform's post ID
            platform:
              type: string
              enum: [instagram, facebook, twitter, youtube, linkedin, bluesky, reddit]
            text:
              type: string
              description: Comment text content
            author:
              type: object
              required: [id]
              properties:
                id:
                  type: string
                  description: Author's platform ID
                username:
                  type: string
                name:
                  type: string
                picture:
                  type: string
                  nullable: true
            createdAt:
              type: string
              format: date-time
            isReply:
              type: boolean
              description: Whether this is a reply to another comment
            parentCommentId:
              type: string
              nullable: true
              description: Parent comment ID if this is a reply
        post:
          type: object
          required: [id, platformPostId]
          properties:
            id:
              type: string
              description: Internal post ID
            platformPostId:
              type: string
              description: Platform's post ID
        account:
          type: object
          required: [id, platform, username]
          properties:
            id:
              type: string
              description: Social account ID
            platform:
              type: string
            username:
              type: string
        timestamp:
          type: string
          format: date-time
    WebhookPayloadMessage:
      type: object
      description: Webhook payload for message received events
      required: [id, event, message, conversation, account, timestamp]
      properties:
        id:
          type: string
          description: Stable webhook event ID
        event:
          type: string
          enum: [message.received]
        message:
          type: object
          required: [id, conversationId, platform, platformMessageId, direction, text, attachments, sender, sentAt, isRead]
          properties:
            id:
              type: string
              description: Internal message ID
            conversationId:
              type: string
              description: Internal conversation ID
            platform:
              type: string
              enum: [instagram, facebook, telegram, whatsapp]
            platformMessageId:
              type: string
              description: Platform's message ID
            direction:
              type: string
              enum: [incoming, outgoing]
            text:
              type: string
              nullable: true
              description: Message text content
            attachments:
              type: array
              items:
                type: object
                required: [type, url]
                properties:
                  type:
                    type: string
                    description: Attachment type (image, video, file, sticker, audio)
                  url:
                    type: string
                    description: Attachment URL (may expire for Meta platforms)
                  payload:
                    type: object
                    description: Additional attachment metadata
            sender:
              type: object
              required: [id]
              properties:
                id:
                  type: string
                name:
                  type: string
                username:
                  type: string
                picture:
                  type: string
                instagramProfile:
                  type: object
                  description: Instagram profile data for the sender. Only present for Instagram conversations.
                  properties:
                    isFollower:
                      type: boolean
                      nullable: true
                      description: Whether the sender follows your Instagram business account
                    isFollowing:
                      type: boolean
                      nullable: true
                      description: Whether your Instagram business account follows the sender
                    followerCount:
                      type: integer
                      nullable: true
                      description: The sender's follower count on Instagram
                    isVerified:
                      type: boolean
                      nullable: true
                      description: Whether the sender is a verified Instagram user
            sentAt:
              type: string
              format: date-time
            isRead:
              type: boolean
        conversation:
          type: object
          required: [id, platformConversationId, status]
          properties:
            id:
              type: string
            platformConversationId:
              type: string
            participantId:
              type: string
            participantName:
              type: string
            participantUsername:
              type: string
            participantPicture:
              type: string
            status:
              type: string
              enum: [active, archived]
        account:
          type: object
          required: [id, platform, username]
          properties:
            id:
              type: string
              description: Social account ID
            platform:
              type: string
            username:
              type: string
            displayName:
              type: string
        metadata:
          type: object
          nullable: true
          description: Interactive message metadata (present when message is a quick reply tap, postback button tap, or inline keyboard callback)
          properties:
            quickReplyPayload:
              type: string
              description: Payload from a quick reply tap (Meta platforms)
            postbackPayload:
              type: string
              description: Payload from a postback button tap (Meta platforms)
            postbackTitle:
              type: string
              description: Title of the tapped postback button (Meta platforms)
            callbackData:
              type: string
              description: Callback data from an inline keyboard button tap (Telegram)
        timestamp:
          type: string
          format: date-time
    WebhookPayloadMessageSent:
      type: object
      description: Webhook payload for message sent events (fired when a message is sent via the API)
      required: [id, event, message, conversation, account, timestamp]
      properties:
        id:
          type: string
          description: Stable webhook event ID
        event:
          type: string
          enum: [message.sent]
        message:
          type: object
          required: [id, conversationId, platform, platformMessageId, direction, text, attachments, sender, sentAt, isRead]
          properties:
            id:
              type: string
              description: Internal message ID
            conversationId:
              type: string
              description: Internal conversation ID
            platform:
              type: string
              enum: [instagram, facebook, telegram, whatsapp]
            platformMessageId:
              type: string
              description: Platform's message ID
            direction:
              type: string
              enum: [incoming, outgoing]
            text:
              type: string
              nullable: true
              description: Message text content
            attachments:
              type: array
              items:
                type: object
                required: [type, url]
                properties:
                  type:
                    type: string
                    description: Attachment type (image, video, file, sticker, audio)
                  url:
                    type: string
                    description: Attachment URL (may expire for Meta platforms)
                  payload:
                    type: object
                    description: Additional attachment metadata
            sender:
              type: object
              required: [id]
              properties:
                id:
                  type: string
                name:
                  type: string
                username:
                  type: string
                picture:
                  type: string
            sentAt:
              type: string
              format: date-time
            isRead:
              type: boolean
        conversation:
          type: object
          required: [id, platformConversationId, status]
          properties:
            id:
              type: string
            platformConversationId:
              type: string
            participantId:
              type: string
            participantName:
              type: string
            participantUsername:
              type: string
            participantPicture:
              type: string
            status:
              type: string
              enum: [active, archived]
        account:
          type: object
          required: [id, platform, username]
          properties:
            id:
              type: string
              description: Social account ID
            platform:
              type: string
            username:
              type: string
            displayName:
              type: string
        timestamp:
          type: string
          format: date-time
    WebhookPayloadTest:
      type: object
      description: Webhook payload for test deliveries
      required: [id, event, message, timestamp]
      properties:
        id:
          type: string
          description: Stable webhook event ID
        event:
          type: string
          enum: [webhook.test]
        message:
          type: string
          description: Human-readable test message
        timestamp:
          type: string
          format: date-time
    PostLog:
      type: object
      description: Publishing log entry showing details of a post publishing attempt
      properties:
        _id:
          type: string
        postId:
          oneOf:
            - type: string
            - type: object
              description: Populated post reference
              properties:
                _id:
                  type: string
                content:
                  type: string
                status:
                  type: string
        userId:
          type: string
        profileId:
          type: string
        platform:
          type: string
          enum: [tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat]
        accountId:
          type: string
        accountUsername:
          type: string
        action:
          type: string
          enum: [publish, retry, media_upload, rate_limit_pause, token_refresh, cancelled]
          description: "Type of action logged: publish (initial attempt), retry (after failure), media_upload, rate_limit_pause, token_refresh, cancelled"
        status:
          type: string
          enum: [success, failed, pending, skipped]
        statusCode:
          type: integer
          description: HTTP status code from platform API
        endpoint:
          type: string
          description: Platform API endpoint called
        request:
          type: object
          properties:
            contentPreview:
              type: string
              description: First 200 chars of caption
            mediaCount:
              type: integer
            mediaTypes:
              type: array
              items:
                type: string
            mediaUrls:
              type: array
              items:
                type: string
              description: URLs of media items sent to platform
            scheduledFor:
              type: string
              format: date-time
            rawBody:
              type: string
              description: Full request body JSON (max 5000 chars)
        response:
          type: object
          properties:
            platformPostId:
              type: string
              description: ID returned by platform on success
            platformPostUrl:
              type: string
              description: URL of published post
            errorMessage:
              type: string
              description: Error message on failure
            errorCode:
              type: string
              description: Platform-specific error code
            rawBody:
              type: string
              description: Full response body JSON (max 5000 chars)
        durationMs:
          type: integer
          description: How long the operation took in milliseconds
        attemptNumber:
          type: integer
          description: Attempt number (1 for first try, 2+ for retries)
        createdAt:
          type: string
          format: date-time
    ConnectionLog:
      type: object
      description: Connection event log showing account connection/disconnection history
      properties:
        _id:
          type: string
        userId:
          type: string
          description: User who owns the connection (may be null for early OAuth failures)
        profileId:
          type: string
        accountId:
          type: string
          description: The social account ID (present on successful connections and disconnects)
        platform:
          type: string
          enum: [tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat]
        eventType:
          type: string
          enum: [connect_success, connect_failed, disconnect, reconnect_success, reconnect_failed]
          description: "Type of connection event: connect_success, connect_failed, disconnect, reconnect_success, reconnect_failed"
        connectionMethod:
          type: string
          enum: [oauth, credentials, invitation]
          description: How the connection was initiated
        error:
          type: object
          description: Error details (present on failed events)
          properties:
            code:
              type: string
              description: Error code (e.g., oauth_denied, token_exchange_failed)
            message:
              type: string
              description: Human-readable error message
            rawResponse:
              type: string
              description: Raw error response (truncated to 2000 chars)
        success:
          type: object
          description: Success details (present on successful events)
          properties:
            displayName:
              type: string
            username:
              type: string
            profilePicture:
              type: string
            permissions:
              type: array
              items:
                type: string
              description: OAuth scopes/permissions granted
            tokenExpiresAt:
              type: string
              format: date-time
            accountType:
              type: string
              description: Account type (personal, business, organization)
        context:
          type: object
          description: Additional context about the connection attempt
          properties:
            isHeadlessMode:
              type: boolean
            hasCustomRedirectUrl:
              type: boolean
            isReconnection:
              type: boolean
            isBYOK:
              type: boolean
              description: Using bring-your-own-keys
            invitationToken:
              type: string
            connectToken:
              type: string
        durationMs:
          type: integer
          description: How long the operation took in milliseconds
        metadata:
          type: object
          description: Additional metadata
        createdAt:
          type: string
          format: date-time
    MediaItem:
      type: object
      description: Media referenced in posts. URLs must be publicly reachable over HTTPS. Use POST /v1/media/presign for uploads up to 5GB. Zernio auto-compresses images and videos that exceed platform limits (videos over 200 MB may not be compressed).
      properties:
        type:
          type: string
          enum: [image, video, gif, document]
        url:
          type: string
          format: uri
        title:
          type: string
          description: Optional title for the media item. Used as the document title for LinkedIn PDF/carousel posts. If omitted, falls back to the post title, then the filename.
        filename:
          type: string
        size:
          type: integer
          description: Optional file size in bytes
        mimeType:
          type: string
          description: Optional MIME type (e.g. image/jpeg, video/mp4)
        thumbnail:
          type: string
          format: uri
          description: Optional custom thumbnail/cover image URL for videos. Supported for Facebook video posts, Facebook Reels, and regular video uploads. Max 10MB, JPG/PNG recommended.
        instagramThumbnail:
          type: string
          format: uri
          description: "Custom cover image URL for Instagram Reels. Can also be set via platformSpecificData.instagramThumbnail or platformSpecificData.reelCover. Resolution order: this field > platformSpecificData.instagramThumbnail > platformSpecificData.reelCover > platformSpecificData.thumbnailUrl (legacy)."
        tiktokProcessed:
          type: boolean
          description: Internal flag indicating the image was resized for TikTok
    PlatformTarget:
      type: object
      properties:
        platform:
          type: string
          example: twitter
          description: "Supported values: twitter, threads, instagram, youtube, facebook, linkedin, pinterest, reddit, tiktok, bluesky, googlebusiness, telegram"
        accountId:
          oneOf:
            - type: string
            - $ref: '#/components/schemas/SocialAccount'
        customContent:
          type: string
          description: Platform-specific text override. When set, this content is used instead of the top-level post content for this platform. Useful for tailoring captions per platform (e.g. keeping tweets under 280 characters).
        customMedia:
          type: array
          items:
            $ref: '#/components/schemas/MediaItem'
        scheduledFor:
          type: string
          format: date-time
          description: Optional per-platform scheduled time override (uses post.scheduledFor when omitted)
        platformSpecificData:
          description: Platform-specific overrides and options.
          oneOf:
            - $ref: '#/components/schemas/TwitterPlatformData'
            - $ref: '#/components/schemas/ThreadsPlatformData'
            - $ref: '#/components/schemas/FacebookPlatformData'
            - $ref: '#/components/schemas/InstagramPlatformData'
            - $ref: '#/components/schemas/LinkedInPlatformData'
            - $ref: '#/components/schemas/PinterestPlatformData'
            - $ref: '#/components/schemas/YouTubePlatformData'
            - $ref: '#/components/schemas/GoogleBusinessPlatformData'
            - $ref: '#/components/schemas/TikTokPlatformData'
            - $ref: '#/components/schemas/TelegramPlatformData'
            - $ref: '#/components/schemas/SnapchatPlatformData'
            - $ref: '#/components/schemas/RedditPlatformData'
            - $ref: '#/components/schemas/BlueskyPlatformData'
          additionalProperties: true
        status:
          type: string
          example: pending
          description: "Platform-specific status: pending, publishing, published, failed"
        platformPostId:
          type: string
          description: The native post ID on the platform (populated after successful publish)
          example: "1234567890123456789"
        platformPostUrl:
          type: string
          format: uri
          description: Public URL of the published post. Included in the response for immediate posts; for scheduled posts, fetch via GET /v1/posts/{postId} after publish time.
          example: "https://twitter.com/acmecorp/status/1234567890123456789"
        publishedAt:
          type: string
          format: date-time
          description: Timestamp when the post was published to this platform
        errorMessage:
          type: string
          description: Human-readable error message when status is failed. Contains platform-specific error details explaining why the publish failed.
        errorCategory:
          type: string
          enum: [auth_expired, user_content, user_abuse, account_issue, platform_rejected, platform_error, system_error, unknown]
          description: "Error category for programmatic handling: auth_expired (token expired/revoked), user_content (wrong format/too long), user_abuse (rate limits/spam), account_issue (config problems), platform_rejected (policy violation), platform_error (5xx/maintenance), system_error (Zernio infra), unknown"
        errorSource:
          type: string
          enum: [user, platform, system]
          description: "Who caused the error: user (fix content/reconnect), platform (outage/API change), system (Zernio issue, rare)"
    Post:
      type: object
      properties:
        _id: { type: string }
        userId:
          oneOf:
            - type: string
            - $ref: '#/components/schemas/User'
        title:
          type: string
          description: |
            YouTube: title must be ≤ 100 characters.
        content: { type: string }
        mediaItems:
          type: array
          items: { $ref: '#/components/schemas/MediaItem' }
        platforms:
          type: array
          items: { $ref: '#/components/schemas/PlatformTarget' }
        scheduledFor: { type: string, format: date-time }
        timezone: { type: string }
        status: { type: string, enum: [draft, scheduled, publishing, published, failed, partial] }
        tags:
          type: array
          description: "YouTube constraints: each tag max 100 chars, combined max 500 chars, duplicates removed."
          items: { type: string }
        hashtags:
          type: array
          items: { type: string }
        mentions:
          type: array
          description: "Stored for reference only. This field does NOT automatically create @mentions when publishing. For LinkedIn @mentions, use the /v1/accounts/{accountId}/linkedin-mentions endpoint to resolve profile URLs to URNs, then embed the returned mentionFormat directly in the post content field."
          items: { type: string }
        visibility: { type: string, enum: [public, private, unlisted] }
        metadata:
          type: object
          additionalProperties: true
        recycling:
          $ref: '#/components/schemas/RecyclingState'
        recycledFromPostId:
          type: string
          description: ID of the original post if this post was created via recycling
        queuedFromProfile:
          type: string
          description: Profile ID if the post was scheduled via the queue
        queueId:
          type: string
          description: Queue ID if the post was scheduled via a specific queue
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }

    RecyclingConfig:
      type: object
      description: |
        Configure automatic post recycling (reposting at regular intervals).
        After the post is published, the system creates new scheduled copies at the
        specified interval until expiration conditions are met. Supports weekly or
        monthly intervals. Maximum 10 active recycling posts per account.
        YouTube and TikTok platforms are excluded from recycling.
        Content variations are recommended for Twitter and Pinterest to avoid duplicate flags.
      properties:
        enabled:
          type: boolean
          default: true
          description: Set to false to disable recycling on this post
        gap:
          type: integer
          minimum: 1
          description: Number of interval units between each repost. Required when enabling recycling.
          example: 2
        gapFreq:
          type: string
          enum: [week, month]
          default: month
          description: Interval unit for the gap. Defaults to 'month'.
        startDate:
          type: string
          format: date-time
          description: When to start the recycling cycle. Defaults to the post's scheduledFor date.
        expireCount:
          type: integer
          minimum: 1
          description: Stop recycling after this many copies have been created
          example: 5
        expireDate:
          type: string
          format: date-time
          description: Stop recycling after this date, regardless of count
        contentVariations:
          type: array
          items:
            type: string
          maxItems: 20
          description: |
            Array of content variations for recycled copies. On each recycle, the next
            variation is used in round-robin order. Recommended for Twitter and Pinterest
            to avoid duplicate content flags. If omitted, the original post content is
            used for all recycled copies. Send an empty array [] to clear existing
            variations. Must have 2+ entries when setting variations. Platform-level
            customContent still overrides the base content per platform.
    RecyclingState:
      type: object
      description: Current recycling configuration and state on a post
      properties:
        enabled:
          type: boolean
          description: Whether recycling is currently active
        gap:
          type: integer
          description: Number of interval units between reposts
        gapFreq:
          type: string
          enum: [week, month]
          description: Interval unit (week or month)
        startDate: { type: string, format: date-time }
        expireCount: { type: integer }
        expireDate: { type: string, format: date-time }
        contentVariations:
          type: array
          items:
            type: string
          description: Content variations for recycled copies (if configured)
        contentVariationIndex:
          type: integer
          description: Current position in the content variations rotation (read-only)
        recycleCount:
          type: integer
          description: How many recycled copies have been created so far (read-only)
        nextRecycleAt:
          type: string
          format: date-time
          description: When the next recycled copy will be created (read-only)
        lastRecycledAt:
          type: string
          format: date-time
          description: When the last recycled copy was created (read-only)

    TwitterPlatformData:
      type: object
      properties:
        replyToTweetId:
          type: string
          description: ID of an existing tweet to reply to. The published tweet will appear as a reply in that tweet's thread. For threads, only the first tweet replies to the target; subsequent tweets chain normally.
        replySettings:
          type: string
          enum: [following, mentionedUsers, subscribers, verified]
          description: Controls who can reply to the tweet. "following" allows only people you follow, "mentionedUsers" allows only mentioned users, "subscribers" allows only subscribers, "verified" allows only verified users. Omit for default (everyone can reply). For threads, applies to the first tweet only. Cannot be combined with replyToTweetId.
        threadItems:
          type: array
          description: >
            Complete sequence of tweets in a thread. The first item becomes the root tweet,
            subsequent items are chained as replies. When threadItems is provided, the top-level
            content field is used only for display and search purposes, it is NOT published.
            You must include your first tweet as threadItems[0].
          items:
            type: object
            properties:
              content: { type: string }
              mediaItems:
                type: array
                items: { $ref: '#/components/schemas/MediaItem' }
        poll:
          type: object
          description: Create a poll with this tweet. Mutually exclusive with media attachments and threads.
          properties:
            options:
              type: array
              minItems: 2
              maxItems: 4
              items:
                type: string
                minLength: 1
                maxLength: 25
              description: Poll options (2-4 choices, max 25 characters each)
            duration_minutes:
              type: integer
              minimum: 5
              maximum: 10080
              description: Poll duration in minutes (5 min to 7 days)
          required:
            - options
            - duration_minutes
        longVideo:
          type: boolean
          default: false
          description: Enable long video uploads (over 140 seconds) using amplify_video media category. Requires the connected X account to have an active X Premium subscription. When true, videos are uploaded with the amplify_video category which supports longer durations (up to 10 minutes via API). When false or omitted, the standard tweet_video category is used (140 second limit). Note that not all Premium accounts have API long-video access, as X may require separate allowlisting.

    ThreadsPlatformData:
      type: object
      properties:
        topic_tag:
          type: string
          minLength: 1
          maxLength: 50
          description: Topic tag for post categorization and discoverability on Threads. Must be 1-50 characters, cannot contain periods (.) or ampersands (&). Overrides auto-extraction from content hashtags when provided.
        threadItems:
          type: array
          description: >
            Complete sequence of posts in a Threads thread. The first item becomes the root post,
            subsequent items are chained as replies. When threadItems is provided, the top-level
            content field is used only for display and search purposes, it is NOT published.
            You must include your first post as threadItems[0].
          items:
            type: object
            properties:
              content: { type: string }
              mediaItems:
                type: array
                items: { $ref: '#/components/schemas/MediaItem' }
      description: Up to 10 images per carousel (no videos). Videos must be H.264/AAC MP4, max 5 min. Images JPEG/PNG, max 8 MB. Use threadItems for reply chains.

    FacebookPlatformData:
      type: object
      properties:
        draft:
          type: boolean
          description: When true, creates the post as an unpublished draft visible in Facebook Publishing Tools instead of publishing immediately. Supported for feed posts (text, link, image, video) and reels. Not supported for stories. Drafts expire after ~30 days.
          default: false
        contentType:
          type: string
          enum: [story, reel]
          description: Set to 'story' for Page Stories (24h ephemeral) or 'reel' for Reels (short vertical video). Defaults to feed post if omitted.
        title:
          type: string
          description: Reel title (only for contentType=reel). Separate from the caption/content field.
        firstComment:
          type: string
          description: Optional first comment to post immediately after publishing (feed posts and reels, not stories). Skipped when draft is true.
        pageId:
          type: string
          description: Target Facebook Page ID for multi-page posting. If omitted, uses the default page. Use GET /v1/accounts/{id}/facebook-page to list pages.
      description: Feed posts support up to 10 images (no mixed video+image). Stories require single media (24h, no captions). Reels require single vertical video (9:16, 3-60s).

    InstagramPlatformData:
      type: object
      properties:
        contentType:
          type: string
          enum: [story]
          description: Set to 'story' to publish as a Story. Default posts become Reels or feed depending on media.
        shareToFeed:
          type: boolean
          default: true
          description: For Reels only. When true (default), the Reel appears on both the Reels tab and your main profile feed. Set to false to post to the Reels tab only.
        collaborators:
          type: array
          items: { type: string }
          description: Up to 3 Instagram usernames to invite as collaborators (feed/Reels only)
        firstComment:
          type: string
          description: Optional first comment to add after the post is created (not applied to Stories)
        trialParams:
          type: object
          description: Trial Reels configuration. Trial reels are shared to non-followers first and can later be graduated to regular reels manually or automatically based on performance. Only applies to Reels.
          properties:
            graduationStrategy:
              type: string
              enum: [MANUAL, SS_PERFORMANCE]
              description: "MANUAL (graduate from Instagram app) or SS_PERFORMANCE (auto-graduate if performs well with non-followers)"
        userTags:
          type: array
          description: Tag Instagram users in photos by username and position. Not supported for stories or videos. For carousels, use mediaIndex to target specific slides (defaults to 0). Tags on video items are silently skipped.
          items:
            type: object
            required: [username, x, y]
            properties:
              username:
                type: string
                description: Instagram username (@ symbol is optional and will be removed automatically)
                example: friend_username
              x:
                type: number
                minimum: 0
                maximum: 1
                description: X coordinate position from left edge (0.0 = left, 0.5 = center, 1.0 = right)
                example: 0.5
              y:
                type: number
                minimum: 0
                maximum: 1
                description: Y coordinate position from top edge (0.0 = top, 0.5 = center, 1.0 = bottom)
                example: 0.5
              mediaIndex:
                type: integer
                minimum: 0
                description: Zero-based index of the carousel item to tag. Defaults to 0. Tags on video items or out-of-range indices are ignored.
                example: 0
        audioName:
          type: string
          description: Custom name for original audio in Reels. Replaces the default "Original Audio" label. Can only be set once.
          example: "My Podcast Intro"
        thumbOffset:
          type: integer
          minimum: 0
          description: Millisecond offset from video start for the Reel cover frame. Ignored when instagramThumbnail or reelCover is provided. Defaults to 0.
          example: 5000
        instagramThumbnail:
          type: string
          format: uri
          description: Custom cover image URL for Instagram Reels (JPG or PNG, publicly accessible). Overrides thumbOffset when provided. Also accepted as reelCover (alias).
        reelCover:
          type: string
          format: uri
          description: Alias for instagramThumbnail. If both are provided, instagramThumbnail takes priority.
      description: Feed aspect ratio 0.8-1.91, carousels up to 10 items, stories require media (no captions). User tag coordinates 0.0-1.0 from top-left. Images over 8 MB and videos over platform limits are auto-compressed.

    LinkedInPlatformData:
      type: object
      properties:
        documentTitle:
          type: string
          description: Title displayed on LinkedIn document (PDF/carousel) posts. Required by LinkedIn for document posts. If omitted, falls back to the media item title, then the filename.
        organizationUrn:
          type: string
          description: Target LinkedIn Organization URN (e.g. "urn:li:organization:123456789"). If omitted, uses the default org. Use GET /v1/accounts/{id}/linkedin-organizations to list orgs.
        firstComment:
          type: string
          description: Optional first comment to add after the post is created
        disableLinkPreview:
          type: boolean
          description: Set to true to disable automatic link previews for URLs in the post content (default is false)
      description: Up to 20 images, no multi-video. Single PDF supported (max 100MB). Link previews auto-generated when no media attached. Use organizationUrn for multi-org posting.

    PinterestPlatformData:
      type: object
      properties:
        title:
          type: string
          maxLength: 100
          description: Pin title. Defaults to first line of content or "Pin". Must be ≤ 100 characters.
        boardId:
          type: string
          description: Target Pinterest board ID. If omitted, the first available board is used.
        link:
          type: string
          format: uri
          description: Destination link (pin URL)
        coverImageUrl:
          type: string
          format: uri
          description: Optional cover image for video pins
        coverImageKeyFrameTime:
          type: integer
          description: Optional key frame time in seconds for derived video cover

    YouTubePlatformData:
      type: object
      properties:
        title:
          type: string
          maxLength: 100
          description: Video title. Defaults to first line of content or "Untitled Video". Must be ≤ 100 characters.
        visibility:
          type: string
          enum: [public, private, unlisted]
          default: public
          description: "Video visibility: public (default, anyone can watch), unlisted (link only), private (invite only)"
        madeForKids:
          type: boolean
          default: false
          description: COPPA compliance flag. Set true for child-directed content (restricts comments, notifications, ad targeting). Defaults to false. YouTube may block views if not explicitly set.
        firstComment:
          type: string
          maxLength: 10000
          description: Optional first comment to post immediately after video upload. Up to 10,000 characters (YouTube's comment limit).
        containsSyntheticMedia:
          type: boolean
          default: false
          description: AI-generated content disclosure. Set true if the video contains synthetic content that could be mistaken for real. YouTube may add a label.
        categoryId:
          type: string
          default: '22'
          description: "YouTube video category ID. Defaults to 22 (People & Blogs). Common: 1 (Film), 2 (Autos), 10 (Music), 15 (Pets), 17 (Sports), 20 (Gaming), 23 (Comedy), 24 (Entertainment), 25 (News), 26 (Howto), 27 (Education), 28 (Science & Tech)."
        playlistId:
          type: string
          description: "Optional YouTube playlist ID to add the video to after upload (e.g. 'PLxxxxxxxxxxxxx'). Use GET /v1/accounts/{id}/youtube-playlists to list available playlists. Works for both immediate and scheduled uploads. Quota cost: 50 YouTube API units per call."
      description: Videos under 3 min auto-detected as Shorts. Custom thumbnails for regular videos only. Scheduled videos are uploaded immediately with the specified visibility.

    GoogleBusinessPlatformData:
      type: object
      properties:
        locationId:
          type: string
          description: Target GBP location ID (e.g. "locations/123456789"). If omitted, uses the default location. Use GET /v1/accounts/{id}/gmb-locations to list locations.
        languageCode:
          type: string
          description: BCP 47 language code (e.g. "en", "de", "es"). Auto-detected if omitted. Set explicitly for short or mixed-language posts.
          example: "de"
        callToAction:
          type: object
          description: Optional call-to-action button displayed on the post
          properties:
            type:
              type: string
              enum: [LEARN_MORE, BOOK, ORDER, SHOP, SIGN_UP, CALL]
              description: "Button action type: LEARN_MORE, BOOK, ORDER, SHOP, SIGN_UP, CALL"
            url:
              type: string
              format: uri
              description: Destination URL for the CTA button (required when callToAction is provided)
          required: [type, url]
      description: Text and single image only (no videos). Optional call-to-action button. Posts appear on GBP, Google Search, and Maps. Use locationId for multi-location posting.

    TikTokPlatformData:
      type: object
      description: Photo carousels up to 35 images. Video titles up to 2200 chars, photo titles truncated to 90 chars. privacyLevel must match creator_info options. Both camelCase and snake_case accepted.
      properties:
        draft:
          type: boolean
          description: When true, sends the post to the TikTok Creator Inbox as a draft instead of publishing immediately.
        privacyLevel:
          type: string
          description: One of the values returned by the TikTok creator info API for the account
        allowComment:
          type: boolean
          description: Allow comments on the post
        allowDuet:
          type: boolean
          description: Allow duets (required for video posts)
        allowStitch:
          type: boolean
          description: Allow stitches (required for video posts)
        commercialContentType:
          type: string
          enum: [none, brand_organic, brand_content]
          description: Type of commercial content disclosure
        brandPartnerPromote:
          type: boolean
          description: Whether the post promotes a brand partner
        isBrandOrganicPost:
          type: boolean
          description: Whether the post is a brand organic post
        contentPreviewConfirmed:
          type: boolean
          description: User has confirmed they previewed the content
        expressConsentGiven:
          type: boolean
          description: User has given express consent for posting
        mediaType:
          type: string
          enum: [video, photo]
          description: Optional override. Defaults based on provided media items.
        videoCoverTimestampMs:
          type: integer
          description: Optional for video posts. Timestamp in milliseconds to select which frame to use as thumbnail (defaults to 1000ms/1 second). Ignored when videoCoverImageUrl is provided.
          minimum: 0
        videoCoverImageUrl:
          type: string
          format: uri
          description: Optional for video posts. URL of a custom thumbnail image (JPG, PNG, or WebP, max 20MB). The image is stitched as a single frame at the start of the video and used as the cover. Overrides videoCoverTimestampMs when provided.
        photoCoverIndex:
          type: integer
          description: Optional for photo carousels. Index of image to use as cover, 0-based (defaults to 0/first image).
          minimum: 0
        autoAddMusic:
          type: boolean
          description: When true, TikTok may add recommended music (photos only)
        videoMadeWithAi:
          type: boolean
          description: Set true to disclose AI-generated content
        description:
          type: string
          maxLength: 4000
          description: Optional long-form description for photo posts (max 4000 chars). Recommended when content exceeds 90 chars, as photo titles are auto-truncated.

    TelegramPlatformData:
      type: object
      properties:
        parseMode:
          type: string
          enum: [HTML, Markdown, MarkdownV2]
          description: Text formatting mode for the message (default is HTML)
        disableWebPagePreview:
          type: boolean
          description: Disable link preview generation for URLs in the message
        disableNotification:
          type: boolean
          description: Send the message silently (users will receive notification without sound)
        protectContent:
          type: boolean
          description: Protect message content from forwarding and saving
      description: Text, images (up to 10), videos (up to 10), and mixed media albums. Captions up to 1024 chars for media, 4096 for text-only.

    SnapchatPlatformData:
      type: object
      properties:
        contentType:
          type: string
          enum: [story, saved_story, spotlight]
          default: story
          description: "Content type: story (ephemeral 24h, default), saved_story (permanent on Public Profile), spotlight (video feed)"
      description: "Requires a Public Profile. Single media item only. Content types: story (ephemeral 24h), saved_story (permanent, title max 45 chars), spotlight (video, max 160 chars)."

    RedditPlatformData:
      type: object
      properties:
        subreddit:
          type: string
          description: Target subreddit name (without "r/" prefix). Overrides the default. Use GET /v1/accounts/{id}/reddit-subreddits to list options.
          example: socialmedia
        title:
          type: string
          maxLength: 300
          description: Post title. Defaults to the first line of content, truncated to 300 characters.
        url:
          type: string
          format: uri
          description: URL for link posts. If provided (and forceSelf is not true), creates a link post instead of a text post.
        forceSelf:
          type: boolean
          description: When true, creates a text/self post even when a URL or media is provided.
        flairId:
          type: string
          description: Flair ID for the post. Required by some subreddits. Use GET /v1/accounts/{id}/reddit-flairs?subreddit=name to list flairs.
          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      description: Posts are either link (with URL/media) or self (text-only). Use forceSelf to override. Subreddit defaults to the account's configured one. Some subreddits require a flair.

    BlueskyPlatformData:
      type: object
      properties:
        threadItems:
          type: array
          description: >
            Complete sequence of posts in a Bluesky thread. The first item becomes the root post,
            subsequent items are chained as replies. When threadItems is provided, the top-level
            content field is used only for display and search purposes, it is NOT published.
            You must include your first post as threadItems[0].
          items:
            type: object
            properties:
              content:
                type: string
              mediaItems:
                type: array
                items:
                  $ref: '#/components/schemas/MediaItem'
      description: |
        Bluesky post settings. Supports text posts with up to 4 images or a single video. threadItems creates a reply chain (Bluesky thread). Images exceeding 1MB are automatically compressed. Alt text supported via mediaItem properties.

    QueueSlot:
      type: object
      properties:
        dayOfWeek:
          type: integer
          description: Day of week (0=Sunday, 6=Saturday)
          minimum: 0
          maximum: 6
        time:
          type: string
          description: Time in HH:mm format (24-hour)
          pattern: '^([0-1][0-9]|2[0-3]):[0-5][0-9]$'
    QueueSchedule:
      type: object
      properties:
        _id:
          type: string
          description: Unique queue identifier
        profileId:
          type: string
          description: Profile ID this queue belongs to
        name:
          type: string
          description: Queue name (e.g., "Morning Posts", "Evening Content")
        timezone:
          type: string
          description: IANA timezone (e.g., America/New_York)
        slots:
          type: array
          items:
            $ref: '#/components/schemas/QueueSlot'
        active:
          type: boolean
          description: Whether the queue is active
        isDefault:
          type: boolean
          description: Whether this is the default queue for the profile (used when no queueId specified)
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Pagination:
      type: object
      properties:
        page: { type: integer }
        limit: { type: integer }
        total: { type: integer }
        pages: { type: integer }
    Profile:
      type: object
      properties:
        _id: { type: string }
        userId: { type: string }
        name: { type: string }
        description: { type: string }
        color: { type: string }
        isDefault: { type: boolean }
        isOverLimit:
          type: boolean
          description: Only present when includeOverLimit=true. Indicates if this profile exceeds the plan limit.
        createdAt: { type: string, format: date-time }
    SocialAccount:
      type: object
      properties:
        _id: { type: string }
        platform: { type: string }
        profileId:
          oneOf:
            - type: string
            - $ref: '#/components/schemas/Profile'
        username: { type: string }
        displayName: { type: string }
        profileUrl:
          type: string
          description: Full profile URL for the connected account on its platform.
        isActive: { type: boolean }
        followersCount:
          type: number
          description: Follower count (only included if user has analytics add-on)
        followersLastUpdated:
          type: string
          format: date-time
          description: Last time follower count was updated (only included if user has analytics add-on)
        adsStatus:
          type: string
          enum: [connected, not_connected, not_available]
          description: |
            Ads connection status for this account.
            - `connected`: Ads are ready to use (same-token platforms like Meta/LinkedIn, or separate ads token is present).
            - `not_connected`: Platform supports ads but requires a separate ads OAuth. Use `GET /v1/connect/{platform}/ads` to connect.
            - `not_available`: Platform does not support ads (e.g., YouTube, Reddit, Bluesky).
        metadata:
          type: object
          description: |
            Platform-specific metadata. Fields vary by platform. For WhatsApp accounts, includes:
            - `qualityRating`: Phone number quality rating from Meta (`GREEN`, `YELLOW`, `RED`, or `UNKNOWN`)
            - `nameStatus`: Display name review status (`APPROVED`, `PENDING_REVIEW`, `DECLINED`, or `NONE`). Messages cannot be sent until the display name is approved by Meta.
            - `messagingLimitTier`: Maximum unique business-initiated conversations per 24h rolling window (`TIER_250`, `TIER_1K`, `TIER_10K`, `TIER_100K`, or `TIER_UNLIMITED`). Scales automatically as quality rating improves.
            - `verifiedName`: Meta-verified business display name
            - `displayPhoneNumber`: Formatted phone number (e.g., "+1 555-123-4567")
            - `wabaId`: WhatsApp Business Account ID
            - `phoneNumberId`: Meta phone number ID
    AccountWithFollowerStats:
      allOf:
        - $ref: '#/components/schemas/SocialAccount'
        - type: object
          properties:
            profilePicture: { type: string }
            currentFollowers: { type: number, description: Current follower count }
            lastUpdated: { type: string, format: date-time }
            growth: { type: number, description: Follower change over period }
            growthPercentage: { type: number, description: Percentage growth }
            dataPoints: { type: number, description: Number of historical snapshots }
            accountStats:
              type: object
              description: |
                Platform-specific account stats from the latest daily snapshot.
                Fields vary by platform. Only present if metadata has been captured.
              properties:
                followingCount: { type: number, description: Number of accounts being followed }
                mediaCount: { type: number, description: Total media posts (Instagram) }
                videoCount: { type: number, description: Total videos (YouTube, TikTok) }
                tweetCount: { type: number, description: Total tweets (X/Twitter) }
                postsCount: { type: number, description: Total posts (Bluesky) }
                pinCount: { type: number, description: Total pins (Pinterest) }
                totalViews: { type: number, description: Total channel views (YouTube) }
                likesCount: { type: number, description: Total likes received (TikTok) }
                monthlyViews: { type: number, description: Monthly profile views (Pinterest) }
                listedCount: { type: number, description: Lists the user appears on (X/Twitter) }
                boardCount: { type: number, description: Total boards (Pinterest) }
    ApiKey:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        keyPreview: { type: string }
        expiresAt: { type: string, format: date-time }
        createdAt: { type: string, format: date-time }
        key:
          type: string
          description: Returned only once, on creation
        scope:
          type: string
          enum: [full, profiles]
          description: "'full' grants access to all profiles, 'profiles' restricts to specific profiles"
          default: full
        profileIds:
          type: array
          items:
            type: object
            properties:
              _id: { type: string }
              name: { type: string }
              color: { type: string }
          description: Profiles this key can access (populated with name and color). Only present when scope is 'profiles'.
        permission:
          type: string
          enum: [read-write, read]
          description: "'read-write' allows all operations, 'read' restricts to GET requests only"
          default: read-write
    UsageStats:
      type: object
      properties:
        planName: { type: string }
        billingPeriod: { type: string, enum: [monthly, yearly] }
        signupDate: { type: string, format: date-time }
        billingAnchorDay: { type: integer, description: "Day of month (1-31) when the billing cycle resets" }
        limits:
          type: object
          properties:
            uploads: { type: integer }
            profiles: { type: integer }
        usage:
          type: object
          properties:
            uploads: { type: integer }
            profiles: { type: integer }
            lastReset: { type: string, format: date-time }
    PostAnalytics:
      type: object
      properties:
        impressions: { type: integer, example: 0 }
        reach: { type: integer, example: 0 }
        likes: { type: integer, example: 0 }
        comments: { type: integer, example: 0 }
        shares: { type: integer, example: 0 }
        saves: { type: integer, example: 0, description: 'Number of saves/bookmarks (Instagram, Pinterest)' }
        clicks: { type: integer, example: 0 }
        views: { type: integer, example: 0 }
        engagementRate: { type: number, example: 0 }
        lastUpdated: { type: string, format: date-time }
    PlatformAnalytics:
      type: object
      properties:
        platform: { type: string }
        status: { type: string, enum: [published, failed] }
        accountId: { type: string }
        accountUsername: { type: string, nullable: true }
        analytics:
          nullable: true
          $ref: '#/components/schemas/PostAnalytics'
        syncStatus: { type: string, enum: [synced, pending, unavailable], description: 'Sync state of analytics for this platform' }
        platformPostUrl: { type: string, format: uri, nullable: true }
        errorMessage: { type: string, nullable: true, description: 'Error details when status is failed' }
    AnalyticsOverview:
      type: object
      properties:
        totalPosts: { type: integer }
        publishedPosts: { type: integer }
        scheduledPosts: { type: integer }
        lastSync: { type: string, format: date-time, nullable: true }
        dataStaleness:
          type: object
          properties:
            staleAccountCount: { type: integer, description: 'Number of accounts with stale analytics data' }
            syncTriggered: { type: boolean, description: 'Whether a background sync was triggered for stale accounts' }
    AnalyticsSinglePostResponse:
      type: object
      properties:
        postId: { type: string }
        latePostId: { type: string, nullable: true, description: 'Original Zernio post ID if scheduled via Zernio' }
        status: { type: string, enum: [published, failed, partial], description: 'Overall post status. "partial" when some platforms published and others failed.' }
        content: { type: string }
        scheduledFor: { type: string, format: date-time }
        publishedAt: { type: string, format: date-time, nullable: true }
        analytics:
          $ref: '#/components/schemas/PostAnalytics'
        platformAnalytics:
          type: array
          items:
            $ref: '#/components/schemas/PlatformAnalytics'
        platform: { type: string }
        platformPostUrl: { type: string, format: uri, nullable: true }
        isExternal: { type: boolean }
        syncStatus: { type: string, enum: [synced, pending, partial, unavailable], description: 'Overall sync state across all platforms' }
        message: { type: string, nullable: true, description: 'Human-readable status message for pending, partial, or failed states' }
        thumbnailUrl: { type: string, format: uri, nullable: true }
        mediaType: { type: string, enum: [image, video, carousel, text], nullable: true }
        mediaItems:
          type: array
          description: All media items for this post. Carousel posts contain one entry per slide.
          items:
            type: object
            properties:
              type: { type: string, enum: [image, video] }
              url: { type: string, format: uri, description: Direct URL to the media }
              thumbnail: { type: string, format: uri, description: Thumbnail URL (same as url for images) }
    AnalyticsListResponse:
      type: object
      properties:
        overview:
          $ref: '#/components/schemas/AnalyticsOverview'
        posts:
          type: array
          items:
            type: object
            properties:
              _id: { type: string }
              latePostId: { type: string, nullable: true, description: 'Original Zernio post ID if scheduled via Zernio' }
              content: { type: string }
              scheduledFor: { type: string, format: date-time }
              publishedAt: { type: string, format: date-time }
              status: { type: string }
              analytics:
                $ref: '#/components/schemas/PostAnalytics'
              platforms:
                type: array
                items:
                  $ref: '#/components/schemas/PlatformAnalytics'
              platform: { type: string }
              platformPostUrl: { type: string, format: uri }
              isExternal: { type: boolean }
              profileId: { type: string, nullable: true }
              thumbnailUrl: { type: string, format: uri }
              mediaType: { type: string, enum: [image, video, gif, document, carousel, text] }
              mediaItems:
                type: array
                description: All media items for this post. Carousel posts contain one entry per slide.
                items:
                  type: object
                  properties:
                    type: { type: string, enum: [image, video] }
                    url: { type: string, format: uri, description: Direct URL to the media }
                    thumbnail: { type: string, format: uri, description: Thumbnail URL (same as url for images) }
        pagination:
          $ref: '#/components/schemas/Pagination'
        accounts:
          type: array
          description: Connected social accounts (followerCount and followersLastUpdated only included if user has analytics add-on)
          items:
            $ref: '#/components/schemas/SocialAccount'
        hasAnalyticsAccess:
          type: boolean
          description: Whether user has analytics add-on access
    # LinkedIn Aggregate Analytics Responses
    LinkedInAggregateAnalyticsTotalResponse:
      type: object
      description: Response for TOTAL aggregation (lifetime totals)
      properties:
        accountId: { type: string }
        platform: { type: string, example: linkedin }
        accountType: { type: string, example: personal }
        username: { type: string }
        aggregation: { type: string, enum: [TOTAL] }
        dateRange:
          type: object
          nullable: true
          properties:
            startDate: { type: string, format: date }
            endDate: { type: string, format: date }
        analytics:
          type: object
          properties:
            impressions: { type: integer, description: Total impressions across all posts }
            reach: { type: integer, description: Unique members reached across all posts }
            reactions: { type: integer, description: Total reactions across all posts }
            comments: { type: integer, description: Total comments across all posts }
            shares: { type: integer, description: Total reshares across all posts }
            engagementRate: { type: number, description: Overall engagement rate as percentage }
        note: { type: string }
        lastUpdated: { type: string, format: date-time }
    LinkedInAggregateAnalyticsDailyResponse:
      type: object
      description: Response for DAILY aggregation (time series breakdown)
      properties:
        accountId: { type: string }
        platform: { type: string, example: linkedin }
        accountType: { type: string, example: personal }
        username: { type: string }
        aggregation: { type: string, enum: [DAILY] }
        dateRange:
          type: object
          nullable: true
          properties:
            startDate: { type: string, format: date }
            endDate: { type: string, format: date }
        analytics:
          type: object
          description: Daily breakdown of each metric as date/count pairs. Reach not available with DAILY aggregation.
          properties:
            impressions:
              type: array
              items:
                type: object
                properties:
                  date: { type: string, format: date }
                  count: { type: integer }
            reactions:
              type: array
              items:
                type: object
                properties:
                  date: { type: string, format: date }
                  count: { type: integer }
            comments:
              type: array
              items:
                type: object
                properties:
                  date: { type: string, format: date }
                  count: { type: integer }
            shares:
              type: array
              items:
                type: object
                properties:
                  date: { type: string, format: date }
                  count: { type: integer }
        skippedMetrics:
          type: array
          description: Metrics that were skipped due to API limitations
          items: { type: string }
        note: { type: string }
        lastUpdated: { type: string, format: date-time }
    # ============================================
    # Response Schemas
    # ============================================
    # Posts Responses
    PostsListResponse:
      type: object
      properties:
        posts:
          type: array
          items:
            $ref: '#/components/schemas/Post'
        pagination:
          $ref: '#/components/schemas/Pagination'
    PostGetResponse:
      type: object
      properties:
        post:
          $ref: '#/components/schemas/Post'
    PostCreateResponse:
      type: object
      properties:
        message:
          type: string
        post:
          $ref: '#/components/schemas/Post'
    PostUpdateResponse:
      type: object
      properties:
        message:
          type: string
        post:
          $ref: '#/components/schemas/Post'
    PostDeleteResponse:
      type: object
      properties:
        message:
          type: string
    PostRetryResponse:
      type: object
      properties:
        message:
          type: string
        post:
          $ref: '#/components/schemas/Post'
    # Profiles Responses
    ProfilesListResponse:
      type: object
      properties:
        profiles:
          type: array
          items:
            $ref: '#/components/schemas/Profile'
    ProfileGetResponse:
      type: object
      properties:
        profile:
          $ref: '#/components/schemas/Profile'
    ProfileCreateResponse:
      type: object
      properties:
        message:
          type: string
        profile:
          $ref: '#/components/schemas/Profile'
    ProfileUpdateResponse:
      type: object
      properties:
        message:
          type: string
        profile:
          $ref: '#/components/schemas/Profile'
    ProfileDeleteResponse:
      type: object
      properties:
        message:
          type: string
    # Accounts Responses
    AccountsListResponse:
      type: object
      properties:
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/SocialAccount'
        hasAnalyticsAccess:
          type: boolean
          description: Whether user has analytics add-on access
    AccountGetResponse:
      type: object
      properties:
        account:
          $ref: '#/components/schemas/SocialAccount'
    FollowerStatsResponse:
      type: object
      properties:
        accounts:
          type: array
          items:
            $ref: '#/components/schemas/AccountWithFollowerStats'
        dateRange:
          type: object
          properties:
            from:
              type: string
              format: date-time
            to:
              type: string
              format: date-time
        aggregation:
          type: string
          enum: [daily, weekly, monthly]
    # Media Responses
    UploadedFile:
      type: object
      properties:
        type:
          type: string
          enum: [image, video, document]
        url:
          type: string
          format: uri
        filename:
          type: string
        size:
          type: integer
        mimeType:
          type: string
    MediaUploadResponse:
      type: object
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/UploadedFile'
    UploadTokenResponse:
      type: object
      properties:
        token:
          type: string
        uploadUrl:
          type: string
          format: uri
        expiresAt:
          type: string
          format: date-time
        status:
          type: string
          enum: [pending, completed, expired]
    UploadTokenStatusResponse:
      type: object
      properties:
        token:
          type: string
        status:
          type: string
          enum: [pending, completed, expired]
        files:
          type: array
          items:
            $ref: '#/components/schemas/UploadedFile'
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
    # Queue Responses
    QueueSlotsResponse:
      type: object
      properties:
        exists:
          type: boolean
        schedule:
          $ref: '#/components/schemas/QueueSchedule'
        nextSlots:
          type: array
          items:
            type: string
            format: date-time
    QueueUpdateResponse:
      type: object
      properties:
        success:
          type: boolean
        schedule:
          $ref: '#/components/schemas/QueueSchedule'
        nextSlots:
          type: array
          items:
            type: string
            format: date-time
        reshuffledCount:
          type: integer
    QueueDeleteResponse:
      type: object
      properties:
        success:
          type: boolean
        deleted:
          type: boolean
    QueuePreviewResponse:
      type: object
      properties:
        profileId:
          type: string
        count:
          type: integer
        slots:
          type: array
          items:
            type: string
            format: date-time
    QueueNextSlotResponse:
      type: object
      properties:
        profileId:
          type: string
        nextSlot:
          type: string
          format: date-time
        timezone:
          type: string
    # Users Responses
    User:
      type: object
      properties:
        _id:
          type: string
        email:
          type: string
        name:
          type: string
        role:
          type: string
        createdAt:
          type: string
          format: date-time
    UsersListResponse:
      type: object
      properties:
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'
    UserGetResponse:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'
    AdMetrics:
      type: object
      properties:
        spend: { type: number }
        impressions: { type: integer }
        reach: { type: integer }
        clicks: { type: integer }
        ctr: { type: number, description: Click-through rate (%) }
        cpc: { type: number, description: Cost per click }
        cpm: { type: number, description: Cost per 1000 impressions }
        engagement: { type: integer }
        lastSyncedAt: { type: string, format: date-time, description: "Present on individual ads only, not on campaign aggregations" }
    Ad:
      type: object
      properties:
        _id: { type: string }
        name: { type: string }
        platform: { type: string, enum: [facebook, instagram, tiktok, linkedin, pinterest, google, twitter] }
        status: { type: string, enum: [active, paused, pending_review, rejected, completed, cancelled, error] }
        adType: { type: string, enum: [boost, standalone] }
        goal: { type: string, enum: [engagement, traffic, awareness, video_views] }
        isExternal: { type: boolean, description: True for ads synced from platform ad managers }
        budget:
          type: object
          nullable: true
          properties:
            amount: { type: number }
            type: { type: string, enum: [daily, lifetime] }
        metrics:
          allOf:
            - { $ref: '#/components/schemas/AdMetrics' }
          nullable: true
        platformAdId: { type: string }
        platformAdAccountId: { type: string }
        platformCampaignId: { type: string }
        platformAdSetId: { type: string }
        campaignName: { type: string }
        adSetName: { type: string }
        creative:
          type: object
          nullable: true
          description: Platform-specific creative data. Fields vary by platform.
          properties:
            thumbnailUrl: { type: string, description: Primary thumbnail/image URL }
            imageUrl: { type: string, description: Alternative image URL }
            mediaUrls:
              type: array
              items: { type: string }
              description: All media URLs for this ad (carousel images, multiple assets). Populated for Meta (carousel child_attachments), Google Ads (responsive display marketing_images), and LinkedIn (multi-image posts).
            body: { type: string, description: Ad copy/text }
            googleHeadline: { type: string, description: Google Ads headline }
            googleDescription: { type: string, description: Google Ads description }
            linkUrl: { type: string, description: Destination URL }
            pinterestImageUrl: { type: string }
            pinterestTitle: { type: string }
            pinterestDescription: { type: string }
        targeting: { type: object }
        schedule:
          type: object
          nullable: true
          properties:
            startDate: { type: string, format: date-time }
            endDate: { type: string, format: date-time }
        rejectionReason: { type: string }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
    AdTreeAdSet:
      type: object
      description: Ad set (or ad group/line item depending on platform) with rolled-up metrics and child ads
      properties:
        platformAdSetId: { type: string }
        adSetName: { type: string }
        status: { type: string, enum: [active, paused, pending_review, rejected, completed, cancelled, error], description: Derived from child ad statuses }
        adCount: { type: integer }
        budget:
          type: object
          nullable: true
          properties:
            amount: { type: number }
            type: { type: string, enum: [daily, lifetime] }
        metrics: { $ref: '#/components/schemas/AdMetrics' }
        ads:
          type: array
          items: { $ref: '#/components/schemas/Ad' }
          description: Individual ads within this ad set (capped at 100). Returns a subset of Ad fields from the aggregation (core fields like _id, name, platform, status, budget, metrics, creative, goal are included; targeting and schedule may be absent).
    AdTreeCampaign:
      type: object
      description: Campaign with nested ad sets and rolled-up metrics
      properties:
        platformCampaignId: { type: string }
        platform: { type: string, enum: [facebook, instagram, tiktok, linkedin, pinterest, google, twitter] }
        campaignName: { type: string }
        status: { type: string, enum: [active, paused, pending_review, rejected, completed, cancelled, error], description: Derived from child ad statuses }
        adCount: { type: integer, description: Total ads across all ad sets }
        adSetCount: { type: integer }
        budget:
          type: object
          nullable: true
          properties:
            amount: { type: number }
            type: { type: string, enum: [daily, lifetime] }
        metrics: { $ref: '#/components/schemas/AdMetrics' }
        platformAdAccountId: { type: string }
        accountId: { type: string }
        profileId: { type: string }
        adSets:
          type: array
          items: { $ref: '#/components/schemas/AdTreeAdSet' }
    AdCampaign:
      type: object
      properties:
        platformCampaignId: { type: string }
        platform: { type: string, enum: [facebook, instagram, tiktok, linkedin, pinterest, google, twitter] }
        campaignName: { type: string }
        status: { type: string, enum: [active, paused, pending_review, rejected, completed, cancelled, error], description: Derived from child ad statuses }
        adCount: { type: integer }
        budget:
          type: object
          nullable: true
          properties:
            amount: { type: number }
            type: { type: string, enum: [daily, lifetime] }
        metrics: { $ref: '#/components/schemas/AdMetrics' }
        platformAdAccountId: { type: string }
        accountId: { type: string }
        profileId: { type: string }
        earliestAd: { type: string, format: date-time }
        latestAd: { type: string, format: date-time }
webhooks:
  post.scheduled:
    post:
      operationId: onPostScheduled
      summary: Post scheduled event
      description: Fired when a post is created and scheduled for publishing.
      tags: [Webhook Events]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookPayloadPost'
      responses:
        '200':
          description: Webhook received successfully
  post.published:
    post:
      operationId: onPostPublished
      summary: Post published event
      description: Fired when a post is successfully published.
      tags: [Webhook Events]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookPayloadPost'
      responses:
        '200':
          description: Webhook received successfully
  post.failed:
    post:
      operationId: onPostFailed
      summary: Post failed event
      description: Fired when a post fails to publish on all target platforms.
      tags: [Webhook Events]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookPayloadPost'
      responses:
        '200':
          description: Webhook received successfully
  post.partial:
    post:
      operationId: onPostPartial
      summary: Post partial event
      description: Fired when a post publishes on some platforms and fails on others.
      tags: [Webhook Events]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookPayloadPost'
      responses:
        '200':
          description: Webhook received successfully
  post.cancelled:
    post:
      operationId: onPostCancelled
      summary: Post cancelled event
      description: Fired when a post publishing job is cancelled.
      tags: [Webhook Events]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookPayloadPost'
      responses:
        '200':
          description: Webhook received successfully
  post.recycled:
    post:
      operationId: onPostRecycled
      summary: Post recycled event
      description: Fired when a post is recycled (cloned and re-scheduled for publishing).
      tags: [Webhook Events]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookPayloadPost'
      responses:
        '200':
          description: Webhook received successfully
  account.connected:
    post:
      operationId: onAccountConnected
      summary: Account connected event
      description: Fired when a social account is successfully connected.
      tags: [Webhook Events]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookPayloadAccountConnected'
      responses:
        '200':
          description: Webhook received successfully
  account.disconnected:
    post:
      operationId: onAccountDisconnected
      summary: Account disconnected event
      description: Fired when a connected social account becomes disconnected.
      tags: [Webhook Events]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookPayloadAccountDisconnected'
      responses:
        '200':
          description: Webhook received successfully
  message.received:
    post:
      operationId: onMessageReceived
      summary: Message received event
      description: Fired when a new inbox message is received.
      tags: [Webhook Events]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookPayloadMessage'
      responses:
        '200':
          description: Webhook received successfully
  message.sent:
    post:
      operationId: onMessageSent
      summary: Message sent event
      description: Fired when a message is sent via the API.
      tags: [Webhook Events]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookPayloadMessageSent'
      responses:
        '200':
          description: Webhook received successfully
  comment.received:
    post:
      operationId: onCommentReceived
      summary: Comment received event
      description: Fired when a new comment is received on a tracked post.
      tags: [Webhook Events]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookPayloadComment'
      responses:
        '200':
          description: Webhook received successfully
  webhook.test:
    post:
      operationId: onWebhookTest
      summary: Webhook test event
      description: Fired when sending a test webhook to verify the endpoint configuration.
      tags: [Webhook Events]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookPayloadTest'
      responses:
        '200':
          description: Webhook received successfully
security:
  - bearerAuth: []
paths:
  # NOTE: Tools download endpoints (/v1/tools/{platform}/download, /transcript, /hashtag-checker) removed from docs but still functional for existing customers

  # ============================================
  # Validate
  # ============================================
  /v1/tools/validate/post-length:
    post:
      operationId: validatePostLength
      tags: [Validate]
      summary: Validate post character count
      description: |
        Check weighted character count per platform and whether the text is within each platform's limit.

        Twitter/X uses weighted counting (URLs = 23 chars via t.co, emojis = 2 chars). All other platforms use plain character length.

        Returns counts and limits for all 15 supported platform variants.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text:
                  type: string
                  description: The post text to check
                  example: "Check out https://zernio.com for scheduling posts!"
      responses:
        "200":
          description: Character counts per platform
          content:
            application/json:
              schema:
                type: object
                properties:
                  text: { type: string }
                  platforms:
                    type: object
                    additionalProperties:
                      type: object
                      properties:
                        count: { type: integer, description: "Character count for this platform" }
                        limit: { type: integer, description: "Maximum allowed characters" }
                        valid: { type: boolean, description: "Whether the text is within the limit" }
                    example:
                      twitter: { count: 51, limit: 280, valid: true }
                      twitterPremium: { count: 51, limit: 25000, valid: true }
                      instagram: { count: 51, limit: 2200, valid: true }
                      bluesky: { count: 51, limit: 300, valid: true }
                      snapchat: { count: 51, limit: 160, valid: true }

  /v1/tools/validate/post:
    post:
      operationId: validatePost
      tags: [Validate]
      summary: Validate post content
      description: |
        Dry-run the full post validation pipeline without publishing. Catches issues like missing media for Instagram/TikTok/YouTube, hashtag limits, invalid thread formats, Facebook Reel requirements, and character limit violations.

        Accepts the same body as `POST /v1/posts`. Does NOT validate accounts, process media, or track usage. This is content-only validation.

        Returns errors for failures and warnings for near-limit content (>90% of character limit).
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [platforms]
              properties:
                content:
                  type: string
                  description: Post text content
                  example: "Check out this video!"
                platforms:
                  type: array
                  description: Target platforms (same format as POST /v1/posts)
                  items:
                    type: object
                    required: [platform]
                    properties:
                      platform:
                        type: string
                        enum: [twitter, instagram, tiktok, youtube, facebook, linkedin, bluesky, threads, reddit, pinterest, telegram, snapchat, googlebusiness]
                      customContent: { type: string }
                      platformSpecificData: { type: object }
                      customMedia:
                        type: array
                        items:
                          type: object
                          properties:
                            url: { type: string }
                            type: { type: string, enum: [image, video] }
                  example:
                    - platform: youtube
                    - platform: twitter
                mediaItems:
                  type: array
                  description: Root media items shared across platforms
                  items:
                    type: object
                    properties:
                      url: { type: string, format: uri }
                      type: { type: string, enum: [image, video] }
      responses:
        "200":
          description: Validation result
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    description: Valid post
                    properties:
                      valid: { type: boolean }
                      message: { type: string, example: "No validation issues found." }
                      warnings:
                        type: array
                        items:
                          type: object
                          properties:
                            platform: { type: string }
                            warning: { type: string }
                  - type: object
                    description: Invalid post
                    properties:
                      valid: { type: boolean }
                      errors:
                        type: array
                        items:
                          type: object
                          properties:
                            platform: { type: string }
                            error: { type: string }
                      warnings:
                        type: array
                        items:
                          type: object
                          properties:
                            platform: { type: string }
                            warning: { type: string }

  /v1/tools/validate/media:
    post:
      operationId: validateMedia
      tags: [Validate]
      summary: Validate media URL
      description: |
        Check if a media URL is accessible and return metadata (content type, file size) plus per-platform size limit comparisons.

        Performs a HEAD request (with GET fallback) to detect content type and size. Rejects private/localhost URLs for SSRF protection.

        Platform limits are sourced from each platform's actual upload constraints.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                  format: uri
                  description: Public media URL to validate
                  example: "https://example.com/image.jpg"
      responses:
        "200":
          description: Media validation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid: { type: boolean }
                  url: { type: string, format: uri }
                  error: { type: string, description: "Error message if valid is false" }
                  contentType: { type: string, example: "image/jpeg" }
                  size: { type: integer, nullable: true, description: "File size in bytes" }
                  sizeFormatted: { type: string, example: "245 KB" }
                  type: { type: string, enum: [image, video, unknown] }
                  platformLimits:
                    type: object
                    description: Per-platform size limit comparison (only present when size and type are known)
                    additionalProperties:
                      type: object
                      properties:
                        limit: { type: integer, description: "Platform size limit in bytes" }
                        limitFormatted: { type: string }
                        withinLimit: { type: boolean }
                    example:
                      instagram: { limit: 8388608, limitFormatted: "8.0 MB", withinLimit: true }
                      twitter: { limit: 5242880, limitFormatted: "5.0 MB", withinLimit: true }
                      bluesky: { limit: 1000000, limitFormatted: "977 KB", withinLimit: true }

  /v1/tools/validate/subreddit:
    get:
      operationId: validateSubreddit
      tags: [Validate]
      summary: Check subreddit existence
      description: |
        Check if a subreddit exists and return basic info (title, subscriber count, NSFW status, post types allowed).

        When accountId is provided, uses authenticated Reddit OAuth API with automatic token refresh (recommended). Falls back to Reddit's public JSON API, which may be unreliable from server IPs. Returns `exists: false` for private, banned, or nonexistent subreddits.
      security:
        - bearerAuth: []
      parameters:
        - name: name
          in: query
          required: true
          description: Subreddit name (with or without "r/" prefix)
          schema:
            type: string
            example: "programming"
        - name: accountId
          in: query
          description: Reddit social account ID for authenticated lookup (recommended for reliable results)
          schema:
            type: string
      responses:
        "200":
          description: Subreddit lookup result
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    description: Subreddit exists
                    properties:
                      exists: { type: boolean }
                      subreddit:
                        type: object
                        properties:
                          name: { type: string, example: "programming" }
                          title: { type: string, example: "programming" }
                          description: { type: string, example: "Computer Programming" }
                          subscribers: { type: integer, example: 6844284 }
                          isNSFW: { type: boolean }
                          type: { type: string, enum: [public, private, restricted], example: "public" }
                          allowImages: { type: boolean }
                          allowVideos: { type: boolean }
                  - type: object
                    description: Subreddit not found
                    properties:
                      exists: { type: boolean }
                      error: { type: string }

  # ============================================
  # Analytics
  # ============================================
  /v1/analytics:
    get:
      operationId: getAnalytics
      tags: [Analytics]
      summary: Get post analytics
      description: |
        Returns analytics for posts. With postId, returns a single post. Without it, returns a paginated list with overview stats.
        Accepts both Zernio Post IDs and External Post IDs (auto-resolved). fromDate defaults to 90 days ago if omitted, max range 366 days.
        Single post lookups may return 202 (sync pending) or 424 (all platforms failed). For follower stats, use /v1/accounts/follower-stats.
      parameters:
        - name: postId
          in: query
          schema: { type: string }
          description: Returns analytics for a single post. Accepts both Zernio Post IDs and External Post IDs. Zernio IDs are auto-resolved to External Post analytics.
        - name: platform
          in: query
          schema: { type: string }
          description: Filter by platform (default "all")
        - name: profileId
          in: query
          schema: { type: string }
          description: Filter by profile ID (default "all")
        - name: accountId
          in: query
          schema: { type: string }
          description: Filter by social account ID
        - name: source
          in: query
          schema: { type: string, enum: [all, late, external], default: all }
          description: "Filter by post source: late (posted via Zernio API), external (synced from platform), all (default)"
        - name: fromDate
          in: query
          schema: { type: string, format: date }
          description: Inclusive lower bound (YYYY-MM-DD). Defaults to 90 days ago if omitted. Max range is 366 days.
        - name: toDate
          in: query
          schema: { type: string, format: date }
          description: Inclusive upper bound (YYYY-MM-DD). Defaults to today if omitted.
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
          description: Page size (default 50)
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
          description: Page number (default 1)
        - name: sortBy
          in: query
          schema: { type: string, enum: [date, engagement, impressions, reach, likes, comments, shares, saves, clicks, views], default: date }
          description: Sort by date, engagement, or a specific metric
        - name: order
          in: query
          schema: { type: string, enum: [asc, desc], default: desc }
          description: Sort order
      responses:
        '200':
          description: Analytics result
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/AnalyticsSinglePostResponse'
                  - $ref: '#/components/schemas/AnalyticsListResponse'
              examples:
                singlePost:
                  summary: Single post analytics (Zernio post with synced analytics)
                  value:
                    postId: "65f1c0a9e2b5af0012ab34cd"
                    latePostId: null
                    status: "published"
                    content: "Check out our new product launch!"
                    scheduledFor: "2024-11-01T10:00:00Z"
                    publishedAt: "2024-11-01T10:00:05Z"
                    analytics:
                      impressions: 15420
                      reach: 12350
                      likes: 342
                      comments: 28
                      shares: 45
                      saves: 0
                      clicks: 189
                      views: 0
                      engagementRate: 2.78
                      lastUpdated: "2024-11-02T08:30:00Z"
                    platformAnalytics:
                      - platform: "twitter"
                        status: "published"
                        accountId: "64e1f0a9e2b5af0012ab34cd"
                        accountUsername: "@acmecorp"
                        analytics:
                          impressions: 15420
                          reach: 12350
                          likes: 342
                          comments: 28
                          shares: 45
                          saves: 0
                          clicks: 189
                          views: 0
                          engagementRate: 2.78
                          lastUpdated: "2024-11-02T08:30:00Z"
                        syncStatus: "synced"
                        platformPostUrl: "https://twitter.com/acmecorp/status/123456789"
                        errorMessage: null
                    platform: "twitter"
                    platformPostUrl: "https://twitter.com/acmecorp/status/123456789"
                    isExternal: false
                    syncStatus: "synced"
                    message: null
                    thumbnailUrl: "https://storage.example.com/image.jpg"
                    mediaType: "image"
                    mediaItems:
                      - type: "image"
                        url: "https://storage.example.com/image.jpg"
                        thumbnail: "https://storage.example.com/image.jpg"
                postList:
                  summary: Paginated analytics list
                  description: |
                    Note: The list endpoint returns External Post IDs. Posts originally
                    scheduled via Zernio will have isExternal: true in this response.
                    Use platformPostUrl to correlate with your original Zernio Post IDs.
                  value:
                    overview:
                      totalPosts: 156
                      publishedPosts: 156
                      scheduledPosts: 0
                      lastSync: "2024-11-02T08:30:00Z"
                      dataStaleness:
                        staleAccountCount: 0
                        syncTriggered: false
                    posts:
                      - _id: "65f1c0a9e2b5af0012ab34cd"
                        latePostId: "65f1c0a9e2b5af0012ab34ab"
                        content: "Check out our new product launch!"
                        scheduledFor: "2024-11-01T10:00:00Z"
                        publishedAt: "2024-11-01T10:00:05Z"
                        status: "published"
                        analytics:
                          impressions: 15420
                          reach: 12350
                          likes: 342
                          comments: 28
                          shares: 45
                          saves: 0
                          clicks: 189
                          views: 0
                          engagementRate: 2.78
                          lastUpdated: "2024-11-02T08:30:00Z"
                        platforms:
                          - platform: "instagram"
                            status: "published"
                            accountId: "64e1f0a9e2b5af0012ab34cd"
                            accountUsername: "@acmecorp"
                            analytics:
                              impressions: 15420
                              reach: 12350
                              likes: 342
                              comments: 28
                              shares: 45
                              saves: 0
                              clicks: 189
                              views: 0
                              engagementRate: 2.78
                              lastUpdated: "2024-11-02T08:30:00Z"
                            syncStatus: "synced"
                            platformPostUrl: "https://www.instagram.com/reel/ABC123xyz/"
                            errorMessage: null
                        platform: "instagram"
                        platformPostUrl: "https://www.instagram.com/reel/ABC123xyz/"
                        isExternal: true
                        profileId: "64e1f0a9e2b5af0012ab34cd"
                        thumbnailUrl: "https://storage.example.com/thumb.jpg"
                        mediaType: "carousel"
                        mediaItems:
                          - type: "image"
                            url: "https://storage.example.com/slide1.jpg"
                            thumbnail: "https://storage.example.com/slide1.jpg"
                          - type: "image"
                            url: "https://storage.example.com/slide2.jpg"
                            thumbnail: "https://storage.example.com/slide2.jpg"
                    pagination:
                      page: 1
                      limit: 50
                      total: 156
                      pages: 4
                    accounts:
                      - _id: "64e1f0..."
                        platform: "twitter"
                        username: "@acmecorp"
                        displayName: "Acme Corp"
                        isActive: true
                    hasAnalyticsAccess: true
        '202':
          description: Analytics are being synced from the platform (single post lookup only). The response body matches AnalyticsSinglePostResponse with syncStatus "pending" and a message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsSinglePostResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: Invalid query parameters }
                  details: { type: object, description: 'Detailed validation errors' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402':
          description: Analytics add-on required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: Analytics add-on required }
                  code: { type: string, example: analytics_addon_required }
        '404': { $ref: '#/components/responses/NotFound' }
        '424':
          description: Post failed to publish on all platforms. Analytics are unavailable. (single post lookup only)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsSinglePostResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/analytics/youtube/daily-views:
    get:
      operationId: getYouTubeDailyViews
      tags: [Analytics]
      summary: Get YouTube daily views
      description: |
        Returns daily view counts for a YouTube video including views, watch time, and subscriber changes.
        Requires yt-analytics.readonly scope (re-authorization may be needed). Data has a 2-3 day delay. Max 90 days, defaults to last 30 days.
      parameters:
        - name: videoId
          in: query
          required: true
          schema: { type: string }
          description: The YouTube video ID (e.g., "dQw4w9WgXcQ")
        - name: accountId
          in: query
          required: true
          schema: { type: string }
          description: The Zernio account ID for the YouTube account
        - name: startDate
          in: query
          schema: { type: string, format: date }
          description: Start date (YYYY-MM-DD). Defaults to 30 days ago.
        - name: endDate
          in: query
          schema: { type: string, format: date }
          description: End date (YYYY-MM-DD). Defaults to 3 days ago (YouTube data latency).
      responses:
        '200':
          description: Daily views breakdown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/YouTubeDailyViewsResponse'
              examples:
                success:
                  summary: Successful response with daily views
                  value:
                    success: true
                    videoId: "dQw4w9WgXcQ"
                    dateRange:
                      startDate: "2025-01-01"
                      endDate: "2025-01-12"
                    totalViews: 12345
                    dailyViews:
                      - date: "2025-01-12"
                        views: 1234
                        estimatedMinutesWatched: 567.5
                        averageViewDuration: 45.2
                        subscribersGained: 10
                        subscribersLost: 2
                        likes: 89
                        comments: 12
                        shares: 5
                      - date: "2025-01-11"
                        views: 987
                        estimatedMinutesWatched: 432.1
                        averageViewDuration: 43.8
                        subscribersGained: 8
                        subscribersLost: 1
                        likes: 67
                        comments: 8
                        shares: 3
                    lastSyncedAt: "2025-01-15T12:00:00Z"
                    scopeStatus:
                      hasAnalyticsScope: true
        '400':
          description: Bad request (missing or invalid parameters)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
              examples:
                missingVideoId:
                  value:
                    error: "videoId is required"
                invalidDate:
                  value:
                    error: "Invalid startDate format. Use YYYY-MM-DD."
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402':
          description: Analytics add-on required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Analytics add-on required" }
                  code: { type: string, example: "analytics_addon_required" }
        '403':
          description: Access denied to this account
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Access denied to this account" }
        '412':
          description: Missing YouTube Analytics scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/YouTubeScopeMissingResponse'
              examples:
                scopeMissing:
                  summary: YouTube Analytics scope not granted
                  value:
                    success: false
                    error: "To access daily video analytics, please reconnect your YouTube account to grant the required permissions."
                    code: "youtube_analytics_scope_missing"
                    scopeStatus:
                      hasAnalyticsScope: false
                      requiresReauthorization: true
                      reauthorizeUrl: "https://accounts.google.com/o/oauth2/auth?client_id=..."
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: false }
                  error: { type: string }

  /v1/analytics/instagram/account-insights:
    get:
      operationId: getInstagramAccountInsights
      tags: [Analytics]
      summary: Get Instagram account-level insights
      description: |
        Returns account-level Instagram insights such as reach, views, accounts engaged, and total interactions.
        These metrics reflect the entire account's performance across all content surfaces (feed, stories, explore, profile),
        and are fundamentally different from post-level metrics. Data may be delayed up to 48 hours.
        Max 90 days, defaults to last 30 days. Requires the Analytics add-on.
      parameters:
        - name: accountId
          in: query
          required: true
          schema: { type: string }
          description: The Zernio SocialAccount ID for the Instagram account
        - name: metrics
          in: query
          schema: { type: string }
          description: |
            Comma-separated list of metrics. Defaults to "reach,views,accounts_engaged,total_interactions".
            Valid metrics: reach, views, accounts_engaged, total_interactions, comments, likes, saves, shares,
            replies, reposts, follows_and_unfollows, profile_links_taps.
            Note: only "reach" supports metricType=time_series. All other metrics are total_value only.
        - name: since
          in: query
          schema: { type: string, format: date }
          description: Start date (YYYY-MM-DD). Defaults to 30 days ago.
        - name: until
          in: query
          schema: { type: string, format: date }
          description: End date (YYYY-MM-DD). Defaults to today.
        - name: metricType
          in: query
          schema:
            type: string
            enum: [time_series, total_value]
            default: total_value
          description: |
            "total_value" (default) returns aggregated totals and supports breakdowns.
            "time_series" returns daily values but only works with the "reach" metric.
        - name: breakdown
          in: query
          schema: { type: string }
          description: |
            Breakdown dimension (only valid with metricType=total_value).
            Valid values depend on the metric: media_product_type, follow_type, follower_type, contact_button_type.
      responses:
        '200':
          description: Account insights data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstagramAccountInsightsResponse'
              examples:
                timeSeries:
                  summary: Time series response with daily values
                  value:
                    success: true
                    accountId: "64e1a2b3c4d5e6f7a8b9c0d1"
                    platform: "instagram"
                    dateRange:
                      since: "2026-03-01"
                      until: "2026-03-22"
                    metricType: "time_series"
                    metrics:
                      reach:
                        total: 12500
                        values:
                          - date: "2026-03-01"
                            value: 420
                          - date: "2026-03-02"
                            value: 385
                      views:
                        total: 45000
                        values:
                          - date: "2026-03-01"
                            value: 1520
                          - date: "2026-03-02"
                            value: 1380
                    dataDelay: "Data may be delayed up to 48 hours"
                totalValueWithBreakdown:
                  summary: Total value response with media type breakdown
                  value:
                    success: true
                    accountId: "64e1a2b3c4d5e6f7a8b9c0d1"
                    platform: "instagram"
                    dateRange:
                      since: "2026-03-01"
                      until: "2026-03-22"
                    metricType: "total_value"
                    breakdown: "media_product_type"
                    metrics:
                      reach:
                        total: 12500
                        breakdowns:
                          - dimension: "FEED"
                            value: 5000
                          - dimension: "REELS"
                            value: 7500
                    dataDelay: "Data may be delayed up to 48 hours"
        '400':
          description: Bad request (invalid parameters)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
              examples:
                invalidMetric:
                  value:
                    error: "Invalid metrics: impressions"
                    validMetrics: ["accounts_engaged", "comments", "follows_and_unfollows", "likes", "profile_links_taps", "reach", "replies", "reposts", "saves", "shares", "total_interactions", "views"]
                breakdownWithTimeSeries:
                  value:
                    error: "Breakdowns are only supported with metricType=total_value"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402':
          description: Analytics add-on required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Analytics add-on required" }
                  code: { type: string, example: "analytics_addon_required" }
        '403':
          description: Access denied to this account
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Access denied to this account" }
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Account not found" }

  /v1/analytics/instagram/demographics:
    get:
      operationId: getInstagramDemographics
      tags: [Analytics]
      summary: Get Instagram audience demographics
      description: |
        Returns audience demographic insights for an Instagram account, broken down by age, city, country, and/or gender.
        Requires at least 100 followers. Returns top 45 entries per dimension.
        Data may be delayed up to 48 hours. Requires the Analytics add-on.
      parameters:
        - name: accountId
          in: query
          required: true
          schema: { type: string }
          description: The Zernio SocialAccount ID for the Instagram account
        - name: metric
          in: query
          schema:
            type: string
            enum: [follower_demographics, engaged_audience_demographics]
            default: follower_demographics
          description: |
            "follower_demographics" for follower audience data, or "engaged_audience_demographics" for engaged viewers.
        - name: breakdown
          in: query
          schema: { type: string }
          description: |
            Comma-separated list of demographic dimensions: age, city, country, gender.
            Defaults to all four if omitted.
        - name: timeframe
          in: query
          schema:
            type: string
            enum: [this_week, this_month]
            default: this_month
          description: |
            Time period for demographic data. Defaults to "this_month".
      responses:
        '200':
          description: Demographic insights data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstagramDemographicsResponse'
              examples:
                allBreakdowns:
                  summary: All four demographic breakdowns
                  value:
                    success: true
                    accountId: "64e1a2b3c4d5e6f7a8b9c0d1"
                    platform: "instagram"
                    metric: "follower_demographics"
                    timeframe: "last_30_days"
                    demographics:
                      age:
                        - dimension: "25-34"
                          value: 4500
                        - dimension: "18-24"
                          value: 3200
                      gender:
                        - dimension: "M"
                          value: 3000
                        - dimension: "F"
                          value: 4800
                      city:
                        - dimension: "New York, New York"
                          value: 800
                        - dimension: "Los Angeles, California"
                          value: 650
                      country:
                        - dimension: "US"
                          value: 5000
                        - dimension: "GB"
                          value: 1200
                    note: "Demographics show top 45 entries per dimension. Requires 100+ followers."
        '400':
          description: Bad request (invalid parameters)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
              examples:
                invalidBreakdown:
                  value:
                    error: "Invalid breakdowns: location"
                    validBreakdowns: ["age", "city", "country", "gender"]
                insufficientFollowers:
                  value:
                    success: false
                    error: "Demographic insights require at least 100 followers."
                    code: "instagram_insufficient_followers"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402':
          description: Analytics add-on required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Analytics add-on required" }
                  code: { type: string, example: "analytics_addon_required" }
        '403':
          description: Access denied to this account
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Access denied to this account" }
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Account not found" }

  /v1/analytics/youtube/demographics:
    get:
      operationId: getYouTubeDemographics
      tags: [Analytics]
      summary: Get YouTube audience demographics
      description: |
        Returns audience demographic insights for a YouTube channel, broken down by age, gender, and/or country.
        Age and gender values are viewer percentages (0-100). Country values are view counts.
        Data is based on signed-in viewers only, with a 2-3 day delay. Requires the Analytics add-on.
      parameters:
        - name: accountId
          in: query
          required: true
          schema: { type: string }
          description: The Zernio SocialAccount ID for the YouTube account
        - name: breakdown
          in: query
          schema: { type: string }
          description: |
            Comma-separated list of demographic dimensions: age, gender, country.
            Defaults to all three if omitted.
        - name: startDate
          in: query
          schema: { type: string, format: date }
          description: |
            Start date in YYYY-MM-DD format. Defaults to 90 days ago.
        - name: endDate
          in: query
          schema: { type: string, format: date }
          description: |
            End date in YYYY-MM-DD format. Defaults to 3 days ago (YouTube data latency).
      responses:
        '200':
          description: Demographic insights data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/YouTubeDemographicsResponse'
              examples:
                allBreakdowns:
                  summary: All three demographic breakdowns
                  value:
                    success: true
                    accountId: "64e1a2b3c4d5e6f7a8b9c0d1"
                    platform: "youtube"
                    demographics:
                      age:
                        - dimension: "25-34"
                          value: 28.5
                        - dimension: "18-24"
                          value: 22.1
                      gender:
                        - dimension: "male"
                          value: 62.3
                        - dimension: "female"
                          value: 35.8
                      country:
                        - dimension: "US"
                          value: 12000
                        - dimension: "GB"
                          value: 3500
                    dateRange:
                      startDate: "2026-01-01"
                      endDate: "2026-03-31"
                    note: "Age/gender values are viewer percentages (0-100). Country values are view counts. Data based on signed-in viewers only, with 2-3 day delay."
        '400':
          description: Bad request (invalid parameters or not a YouTube account)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402':
          description: Analytics add-on required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Analytics add-on required" }
                  code: { type: string, example: "analytics_addon_required" }
        '403':
          description: Access denied to this account
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Access denied to this account" }
        '404':
          description: Account not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Account not found" }
        '412':
          description: YouTube Analytics scope not granted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: false }
                  error: { type: string }
                  code: { type: string, example: "youtube_analytics_scope_missing" }
                  scopeStatus:
                    type: object
                    properties:
                      hasAnalyticsScope: { type: boolean, example: false }
                      requiresReauthorization: { type: boolean, example: true }
                      reauthorizeUrl: { type: string }

  /v1/analytics/daily-metrics:
    get:
      operationId: getDailyMetrics
      tags: [Analytics]
      summary: Get daily aggregated metrics
      description: |
        Returns daily aggregated analytics metrics and a per-platform breakdown.
        Each day includes post count, platform distribution, and summed metrics (impressions, reach, likes, comments, shares, saves, clicks, views).
        Defaults to the last 180 days. Requires the Analytics add-on.
      parameters:
        - name: platform
          in: query
          schema: { type: string }
          description: Filter by platform (e.g. "instagram", "tiktok"). Omit for all platforms.
        - name: profileId
          in: query
          schema: { type: string }
          description: Filter by profile ID. Omit for all profiles.
        - name: accountId
          in: query
          schema: { type: string }
          description: Filter by social account ID
        - name: fromDate
          in: query
          schema: { type: string, format: date-time }
          description: Inclusive start date (ISO 8601). Defaults to 180 days ago.
        - name: toDate
          in: query
          schema: { type: string, format: date-time }
          description: Inclusive end date (ISO 8601). Defaults to now.
        - name: source
          in: query
          schema:
            type: string
            enum: [all, late, external]
            default: all
          description: Filter by post origin. "late" for posts published via Zernio, "external" for posts imported from platforms.
      responses:
        '200':
          description: Daily metrics and platform breakdown
          content:
            application/json:
              schema:
                type: object
                properties:
                  dailyData:
                    type: array
                    items:
                      type: object
                      properties:
                        date: { type: string, example: "2025-12-01" }
                        postCount: { type: integer, example: 3 }
                        platforms:
                          type: object
                          additionalProperties: { type: integer }
                          example: { instagram: 2, twitter: 1 }
                        metrics:
                          type: object
                          properties:
                            impressions: { type: integer }
                            reach: { type: integer }
                            likes: { type: integer }
                            comments: { type: integer }
                            shares: { type: integer }
                            saves: { type: integer }
                            clicks: { type: integer }
                            views: { type: integer }
                  platformBreakdown:
                    type: array
                    items:
                      type: object
                      properties:
                        platform: { type: string, example: "instagram" }
                        postCount: { type: integer, example: 142 }
                        impressions: { type: integer }
                        reach: { type: integer }
                        likes: { type: integer }
                        comments: { type: integer }
                        shares: { type: integer }
                        saves: { type: integer }
                        clicks: { type: integer }
                        views: { type: integer }
              examples:
                success:
                  value:
                    dailyData:
                      - date: "2025-12-01"
                        postCount: 3
                        platforms: { instagram: 2, twitter: 1 }
                        metrics:
                          impressions: 4520
                          reach: 3200
                          likes: 312
                          comments: 45
                          shares: 28
                          saves: 67
                          clicks: 89
                          views: 1560
                    platformBreakdown:
                      - platform: "instagram"
                        postCount: 142
                        impressions: 89400
                        reach: 62100
                        likes: 8930
                        comments: 1204
                        shares: 567
                        saves: 2103
                        clicks: 3402
                        views: 45200
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402':
          description: Analytics add-on required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Analytics add-on required" }
                  code: { type: string, example: "analytics_addon_required" }

  /v1/analytics/best-time:
    get:
      operationId: getBestTimeToPost
      tags: [Analytics]
      summary: Get best times to post
      description: |
        Returns the best times to post based on historical engagement data.
        Groups all published posts by day of week and hour (UTC), calculating average engagement per slot.
        Use this to auto-schedule posts at optimal times. Requires the Analytics add-on.
      parameters:
        - name: platform
          in: query
          schema: { type: string }
          description: Filter by platform (e.g. "instagram", "tiktok"). Omit for all platforms.
        - name: profileId
          in: query
          schema: { type: string }
          description: Filter by profile ID. Omit for all profiles.
        - name: source
          in: query
          schema:
            type: string
            enum: [all, late, external]
            default: all
          description: Filter by post origin. "late" for posts published via Zernio, "external" for posts imported from platforms.
      responses:
        '200':
          description: Best time slots
          content:
            application/json:
              schema:
                type: object
                properties:
                  slots:
                    type: array
                    items:
                      type: object
                      properties:
                        day_of_week: { type: integer, description: "0=Monday, 6=Sunday", minimum: 0, maximum: 6 }
                        hour: { type: integer, description: "Hour in UTC (0-23)", minimum: 0, maximum: 23 }
                        avg_engagement: { type: number, description: "Average engagement (likes + comments + shares + saves)" }
                        post_count: { type: integer, description: "Number of posts in this slot" }
              examples:
                success:
                  value:
                    slots:
                      - day_of_week: 2
                        hour: 18
                        avg_engagement: 510.3
                        post_count: 15
                      - day_of_week: 0
                        hour: 9
                        avg_engagement: 342.5
                        post_count: 12
                      - day_of_week: 4
                        hour: 12
                        avg_engagement: 289.1
                        post_count: 8
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Analytics add-on required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Analytics add-on required" }
                  requiresAddon: { type: boolean, example: true }

  /v1/analytics/content-decay:
    get:
      operationId: getContentDecay
      tags: [Analytics]
      summary: Get content performance decay
      description: |
        Returns how engagement accumulates over time after a post is published.
        Each bucket shows what percentage of the post's total engagement had been reached by that time window.
        Useful for understanding content lifespan (e.g. "posts reach 78% of total engagement within 24 hours").
        Requires the Analytics add-on.
      parameters:
        - name: platform
          in: query
          schema: { type: string }
          description: Filter by platform (e.g. "instagram", "tiktok"). Omit for all platforms.
        - name: profileId
          in: query
          schema: { type: string }
          description: Filter by profile ID. Omit for all profiles.
        - name: source
          in: query
          schema:
            type: string
            enum: [all, late, external]
            default: all
          description: Filter by post origin. "late" for posts published via Zernio, "external" for posts imported from platforms.
      responses:
        '200':
          description: Content decay buckets
          content:
            application/json:
              schema:
                type: object
                properties:
                  buckets:
                    type: array
                    items:
                      type: object
                      properties:
                        bucket_order: { type: integer, description: "Sort order (0 = earliest, 6 = latest)" }
                        bucket_label: { type: string, description: "Human-readable label" }
                        avg_pct_of_final: { type: number, description: "Average % of final engagement reached (0-100)" }
                        post_count: { type: integer, description: "Number of posts with data in this bucket" }
              examples:
                success:
                  value:
                    buckets:
                      - bucket_order: 0
                        bucket_label: "0-6h"
                        avg_pct_of_final: 45.2
                        post_count: 89
                      - bucket_order: 1
                        bucket_label: "6-12h"
                        avg_pct_of_final: 18.7
                        post_count: 89
                      - bucket_order: 2
                        bucket_label: "12-24h"
                        avg_pct_of_final: 14.1
                        post_count: 85
                      - bucket_order: 3
                        bucket_label: "1-2d"
                        avg_pct_of_final: 9.3
                        post_count: 82
                      - bucket_order: 4
                        bucket_label: "2-7d"
                        avg_pct_of_final: 8.1
                        post_count: 78
                      - bucket_order: 5
                        bucket_label: "7-30d"
                        avg_pct_of_final: 3.8
                        post_count: 64
                      - bucket_order: 6
                        bucket_label: "30d+"
                        avg_pct_of_final: 0.8
                        post_count: 41
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Analytics add-on required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Analytics add-on required" }
                  requiresAddon: { type: boolean, example: true }

  /v1/analytics/posting-frequency:
    get:
      operationId: getPostingFrequency
      tags: [Analytics]
      summary: Get posting frequency vs engagement
      description: |
        Returns the correlation between posting frequency (posts per week) and engagement rate, broken down by platform.
        Helps find the optimal posting cadence for each platform. Each row represents a specific (platform, posts_per_week) combination
        with the average engagement rate observed across all weeks matching that frequency.
        Requires the Analytics add-on.
      parameters:
        - name: platform
          in: query
          schema: { type: string }
          description: Filter by platform (e.g. "instagram", "tiktok"). Omit for all platforms.
        - name: profileId
          in: query
          schema: { type: string }
          description: Filter by profile ID. Omit for all profiles.
        - name: source
          in: query
          schema:
            type: string
            enum: [all, late, external]
            default: all
          description: Filter by post origin. "late" for posts published via Zernio, "external" for posts imported from platforms.
      responses:
        '200':
          description: Posting frequency data
          content:
            application/json:
              schema:
                type: object
                properties:
                  frequency:
                    type: array
                    items:
                      type: object
                      properties:
                        platform: { type: string, example: "instagram" }
                        posts_per_week: { type: integer, description: "Number of posts published that week" }
                        avg_engagement_rate: { type: number, description: "Average engagement rate as percentage (0-100)" }
                        avg_engagement: { type: number, description: "Average raw engagement (likes+comments+shares+saves)" }
                        weeks_count: { type: integer, description: "Number of calendar weeks observed at this frequency" }
              examples:
                success:
                  value:
                    frequency:
                      - platform: "instagram"
                        posts_per_week: 2
                        avg_engagement_rate: 44.4
                        avg_engagement: 512
                        weeks_count: 18
                      - platform: "instagram"
                        posts_per_week: 4
                        avg_engagement_rate: 5.9
                        avg_engagement: 203
                        weeks_count: 6
                      - platform: "facebook"
                        posts_per_week: 3
                        avg_engagement_rate: 12.5
                        avg_engagement: 87
                        weeks_count: 10
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Analytics add-on required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Analytics add-on required" }
                  requiresAddon: { type: boolean, example: true }

  /v1/analytics/post-timeline:
    get:
      operationId: getPostTimeline
      tags: [Analytics]
      summary: Get post analytics timeline
      description: |
        Returns a daily timeline of analytics metrics for a specific post, showing how impressions, likes,
        and other metrics evolved day-by-day since publishing. Each row represents one day of data per platform.
        For multi-platform Zernio posts, returns separate rows for each platform. Requires the Analytics add-on.
      parameters:
        - name: postId
          in: query
          required: true
          schema: { type: string }
          description: |
            The post to fetch timeline for. Accepts an ExternalPost ID, a platformPostId, or a Zernio Post ID.
        - name: fromDate
          in: query
          schema: { type: string, format: date-time }
          description: Start of date range (ISO 8601). Defaults to 90 days ago.
        - name: toDate
          in: query
          schema: { type: string, format: date-time }
          description: End of date range (ISO 8601). Defaults to now.
      responses:
        '200':
          description: Daily analytics timeline
          content:
            application/json:
              schema:
                type: object
                properties:
                  postId:
                    type: string
                    description: The postId that was requested
                  timeline:
                    type: array
                    items:
                      type: object
                      properties:
                        date: { type: string, format: date, description: "Date in YYYY-MM-DD format" }
                        platform: { type: string, description: "Platform name (e.g. instagram, tiktok)" }
                        platformPostId: { type: string, description: "Platform-specific post ID" }
                        impressions: { type: integer, description: "Total impressions on this date" }
                        reach: { type: integer, description: "Total reach on this date" }
                        likes: { type: integer, description: "Total likes on this date" }
                        comments: { type: integer, description: "Total comments on this date" }
                        shares: { type: integer, description: "Total shares on this date" }
                        saves: { type: integer, description: "Total saves on this date" }
                        clicks: { type: integer, description: "Total clicks on this date" }
                        views: { type: integer, description: "Total views on this date" }
              examples:
                single_platform:
                  summary: Single-platform post timeline
                  value:
                    postId: "6507a1b2c3d4e5f6a7b8c9d0"
                    timeline:
                      - date: "2025-01-15"
                        platform: "instagram"
                        platformPostId: "17902345678901234"
                        impressions: 1200
                        reach: 980
                        likes: 45
                        comments: 3
                        shares: 12
                        saves: 8
                        clicks: 25
                        views: 0
                      - date: "2025-01-16"
                        platform: "instagram"
                        platformPostId: "17902345678901234"
                        impressions: 2400
                        reach: 1850
                        likes: 92
                        comments: 7
                        shares: 21
                        saves: 15
                        clicks: 48
                        views: 0
        '400':
          description: Missing required postId parameter
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Missing required parameter: postId" }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402':
          description: Analytics add-on required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Analytics add-on required" }
                  code: { type: string, example: "analytics_addon_required" }
        '403':
          description: Forbidden (post belongs to another user or API key scope violation)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Forbidden" }
        '404':
          description: Post not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Post not found" }

  /v1/analytics/googlebusiness/performance:
    get:
      operationId: getGoogleBusinessPerformance
      tags: [Analytics]
      summary: Get Google Business Profile performance metrics
      description: |
        Returns daily performance metrics for a Google Business Profile location.
        Metrics include impressions (Maps/Search, desktop/mobile), website clicks,
        call clicks, direction requests, conversations, bookings, and food orders.
        Data may be delayed 2-3 days. Max 18 months of historical data.
        Requires the Analytics add-on.
      parameters:
        - name: accountId
          in: query
          required: true
          schema: { type: string }
          description: The Zernio SocialAccount ID for the Google Business Profile account.
        - name: metrics
          in: query
          schema: { type: string }
          description: |
            Comma-separated metric names. Defaults to all available metrics.
            Valid values: BUSINESS_IMPRESSIONS_DESKTOP_MAPS, BUSINESS_IMPRESSIONS_DESKTOP_SEARCH,
            BUSINESS_IMPRESSIONS_MOBILE_MAPS, BUSINESS_IMPRESSIONS_MOBILE_SEARCH,
            BUSINESS_CONVERSATIONS, BUSINESS_DIRECTION_REQUESTS, CALL_CLICKS, WEBSITE_CLICKS,
            BUSINESS_BOOKINGS, BUSINESS_FOOD_ORDERS, BUSINESS_FOOD_MENU_CLICKS
        - name: startDate
          in: query
          schema: { type: string, format: date }
          description: Start date (YYYY-MM-DD). Defaults to 30 days ago. Max 18 months back.
        - name: endDate
          in: query
          schema: { type: string, format: date }
          description: End date (YYYY-MM-DD). Defaults to today.
      responses:
        '200':
          description: Performance metrics with daily time series
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: true }
                  accountId: { type: string }
                  platform: { type: string, example: "googlebusiness" }
                  dateRange:
                    type: object
                    properties:
                      startDate: { type: string, format: date, example: "2026-03-01" }
                      endDate: { type: string, format: date, example: "2026-03-31" }
                  metrics:
                    type: object
                    description: Each key is a metric name containing total and daily values.
                    additionalProperties:
                      type: object
                      properties:
                        total: { type: integer, description: "Sum of all daily values in the range" }
                        values:
                          type: array
                          items:
                            type: object
                            properties:
                              date: { type: string, format: date }
                              value: { type: integer }
                  dataDelay: { type: string, example: "Data may be delayed 2-3 days" }
              examples:
                performance_data:
                  summary: Performance metrics for a location
                  value:
                    success: true
                    accountId: "69300690f43160a0bc999e07"
                    platform: "googlebusiness"
                    dateRange:
                      startDate: "2026-03-01"
                      endDate: "2026-03-31"
                    metrics:
                      WEBSITE_CLICKS:
                        total: 42
                        values:
                          - date: "2026-03-01"
                            value: 3
                          - date: "2026-03-02"
                            value: 1
                      CALL_CLICKS:
                        total: 7
                        values:
                          - date: "2026-03-01"
                            value: 1
                      BUSINESS_IMPRESSIONS_MOBILE_SEARCH:
                        total: 156
                        values:
                          - date: "2026-03-01"
                            value: 8
                    dataDelay: "Data may be delayed 2-3 days"
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Invalid metrics: INVALID_METRIC" }
                  validMetrics:
                    type: array
                    items: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402':
          description: Analytics add-on required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Analytics add-on required" }
                  code: { type: string, example: "analytics_addon_required" }
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Access denied to this account" }

  /v1/analytics/googlebusiness/search-keywords:
    get:
      operationId: getGoogleBusinessSearchKeywords
      tags: [Analytics]
      summary: Get Google Business Profile search keywords
      description: |
        Returns search keywords that triggered impressions for a Google Business Profile location.
        Data is aggregated monthly. Keywords below a minimum impression threshold set by Google are excluded.
        Max 18 months of historical data. Requires the Analytics add-on.
      parameters:
        - name: accountId
          in: query
          required: true
          schema: { type: string }
          description: The Zernio SocialAccount ID for the Google Business Profile account.
        - name: startMonth
          in: query
          schema: { type: string, pattern: "^\\d{4}-\\d{2}$" }
          description: Start month (YYYY-MM). Defaults to 3 months ago.
        - name: endMonth
          in: query
          schema: { type: string, pattern: "^\\d{4}-\\d{2}$" }
          description: End month (YYYY-MM). Defaults to current month.
      responses:
        '200':
          description: Search keywords with impression counts
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: true }
                  accountId: { type: string }
                  platform: { type: string, example: "googlebusiness" }
                  monthRange:
                    type: object
                    properties:
                      startMonth: { type: string, example: "2026-01" }
                      endMonth: { type: string, example: "2026-03" }
                  keywords:
                    type: array
                    items:
                      type: object
                      properties:
                        keyword: { type: string, example: "restaurant near me" }
                        impressions: { type: integer, example: 245 }
                  note: { type: string, example: "Keywords below a minimum impression threshold are excluded by Google" }
              examples:
                keywords_data:
                  summary: Search keywords for a location
                  value:
                    success: true
                    accountId: "69300690f43160a0bc999e07"
                    platform: "googlebusiness"
                    monthRange:
                      startMonth: "2026-01"
                      endMonth: "2026-03"
                    keywords:
                      - keyword: "restaurant near me"
                        impressions: 245
                      - keyword: "best tapas barcelona"
                        impressions: 89
                      - keyword: "arbichat"
                        impressions: 34
                    note: "Keywords below a minimum impression threshold are excluded by Google"
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Invalid startMonth format. Use YYYY-MM." }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402':
          description: Analytics add-on required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Analytics add-on required" }
                  code: { type: string, example: "analytics_addon_required" }
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "Access denied to this account" }

  /v1/account-groups:
    get:
      operationId: listAccountGroups
      tags: [Account Groups]
      summary: List groups
      description: Returns all account groups for the authenticated user, including group names and associated account IDs.
      responses:
        '200':
          description: Groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  groups:
                    type: array
                    items:
                      type: object
                      properties:
                        _id: { type: string }
                        name: { type: string }
                        accountIds:
                          type: array
                          items: { type: string }
              examples:
                example:
                  value:
                    groups:
                      - _id: "6507a1b2c3d4e5f6a7b8c9d0"
                        name: "Marketing Accounts"
                        accountIds:
                          - "64e1f0a9e2b5af0012ab34cd"
                          - "64e1f0a9e2b5af0012ab34ce"
                      - _id: "6507a1b2c3d4e5f6a7b8c9d1"
                        name: "Personal Brand"
                        accountIds:
                          - "64e1f0a9e2b5af0012ab34cf"
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      operationId: createAccountGroup
      tags: [Account Groups]
      summary: Create group
      description: Creates a new account group with a name and a list of social account IDs.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, accountIds]
              properties:
                name: { type: string }
                accountIds:
                  type: array
                  items: { type: string }
            example:
              name: "Marketing Accounts"
              accountIds:
                - "64e1f0a9e2b5af0012ab34cd"
                - "64e1f0a9e2b5af0012ab34ce"
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  group:
                    type: object
                    properties:
                      _id: { type: string }
                      name: { type: string }
                      accountIds:
                        type: array
                        items: { type: string }
              example:
                message: "Account group created successfully"
                group:
                  _id: "6507a1b2c3d4e5f6a7b8c9d0"
                  name: "Marketing Accounts"
                  accountIds:
                    - "64e1f0a9e2b5af0012ab34cd"
                    - "64e1f0a9e2b5af0012ab34ce"
        '400': { description: Invalid request }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '409': { description: Group name already exists }
  /v1/account-groups/{groupId}:
    put:
      operationId: updateAccountGroup
      tags: [Account Groups]
      summary: Update group
      description: Updates the name or account list of an existing group. You can rename the group, change its accounts, or both.
      parameters:
        - name: groupId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                accountIds:
                  type: array
                  items: { type: string }
            example:
              name: "Updated Marketing Accounts"
              accountIds:
                - "64e1f0a9e2b5af0012ab34cd"
                - "64e1f0a9e2b5af0012ab34ce"
                - "64e1f0a9e2b5af0012ab34cf"
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  group:
                    type: object
              example:
                message: "Account group updated successfully"
                group:
                  _id: "6507a1b2c3d4e5f6a7b8c9d0"
                  name: "Updated Marketing Accounts"
                  accountIds:
                    - "64e1f0a9e2b5af0012ab34cd"
                    - "64e1f0a9e2b5af0012ab34ce"
                    - "64e1f0a9e2b5af0012ab34cf"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { description: Group name already exists }
    delete:
      operationId: deleteAccountGroup
      tags: [Account Groups]
      summary: Delete group
      description: Permanently deletes an account group. The accounts themselves are not affected.
      parameters:
        - name: groupId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
              example:
                message: "Account group deleted successfully"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/media/presign:
    post:
      operationId: getMediaPresignedUrl
      tags: [Media]
      summary: Get presigned upload URL
      description: Get a presigned URL to upload files directly to cloud storage (up to 5GB). Returns an uploadUrl and publicUrl. PUT your file to the uploadUrl, then use the publicUrl in your posts.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [filename, contentType]
              properties:
                filename:
                  type: string
                  description: Name of the file to upload
                  example: "my-video.mp4"
                contentType:
                  type: string
                  description: MIME type of the file
                  enum:
                    - image/jpeg
                    - image/jpg
                    - image/png
                    - image/webp
                    - image/gif
                    - video/mp4
                    - video/mpeg
                    - video/quicktime
                    - video/avi
                    - video/x-msvideo
                    - video/webm
                    - video/x-m4v
                    - application/pdf
                  example: "video/mp4"
                size:
                  type: integer
                  description: Optional file size in bytes for pre-validation (max 5GB)
                  example: 15234567
      responses:
        '200':
          description: Presigned URL generated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  uploadUrl:
                    type: string
                    format: uri
                    description: Presigned URL to PUT your file to (expires in 1 hour)
                  publicUrl:
                    type: string
                    format: uri
                    description: Public URL where the file will be accessible after upload
                  key:
                    type: string
                    description: Storage key/path of the file
                  type:
                    type: string
                    enum: [image, video, document]
                    description: Detected file type based on content type
              example:
                uploadUrl: "<presigned-upload-url>"
                publicUrl: "https://media.zernio.com/temp/1234567890_abc123_my-video.mp4"
                key: "temp/1234567890_abc123_my-video.mp4"
                type: "video"
        '400':
          description: Invalid request (missing filename, contentType, or unsupported content type)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
              examples:
                missing_filename:
                  value: { error: "filename and contentType are required" }
                invalid_type:
                  value: { error: "Content type not allowed: text/plain" }
                file_too_large:
                  value: { error: "File too large. Maximum size is 5GB." }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /v1/reddit/search:
    get:
      operationId: searchReddit
      tags: [Reddit Search]
      summary: Search posts
      description: Search Reddit posts using a connected account. Optionally scope to a specific subreddit.
      parameters:
        - name: accountId
          in: query
          required: true
          schema: { type: string }
        - name: subreddit
          in: query
          schema: { type: string }
        - name: q
          in: query
          required: true
          schema: { type: string }
        - name: restrict_sr
          in: query
          schema: { type: string, enum: ['0','1'] }
        - name: sort
          in: query
          schema: { type: string, enum: [relevance, hot, top, new, comments], default: new }
        - name: limit
          in: query
          schema: { type: integer, default: 25, maximum: 100 }
        - name: after
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/RedditPost'
                  after: { type: string, nullable: true }
                  before: { type: string, nullable: true }
              example:
                items:
                  - id: "1abc234"
                    fullname: "t3_1abc234"
                    title: "How to grow on social media in 2025"
                    selftext: "Here are my tips..."
                    author: "marketingpro"
                    subreddit: "socialmedia"
                    url: "https://www.reddit.com/r/socialmedia/comments/1abc234/"
                    permalink: "https://www.reddit.com/r/socialmedia/comments/1abc234/how_to_grow/"
                    score: 156
                    numComments: 42
                    createdUtc: 1730000000
                    over18: false
                    stickied: false
                    flairText: null
                    isGallery: false
                after: "t3_1abc234"
                before: null
        '400': { description: Missing params }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }
  /v1/reddit/feed:
    get:
      operationId: getRedditFeed
      tags: [Reddit Search]
      summary: Get subreddit feed
      description: Fetch posts from a subreddit feed. Supports sorting, time filtering, and cursor-based pagination.
      parameters:
        - name: accountId
          in: query
          required: true
          schema: { type: string }
        - name: subreddit
          in: query
          schema: { type: string }
        - name: sort
          in: query
          schema: { type: string, enum: [hot, new, top, rising], default: hot }
        - name: limit
          in: query
          schema: { type: integer, default: 25, maximum: 100 }
        - name: after
          in: query
          schema: { type: string }
        - name: t
          in: query
          schema: { type: string, enum: [hour, day, week, month, year, all] }
      responses:
        '200':
          description: Feed items
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/RedditPost'
                  after: { type: string, nullable: true }
                  before: { type: string, nullable: true }
              example:
                items:
                  - id: "1xyz789"
                    fullname: "t3_1xyz789"
                    title: "Top marketing trends this week"
                    author: "trendwatcher"
                    subreddit: "marketing"
                    url: "https://www.reddit.com/r/marketing/comments/1xyz789/"
                    permalink: "https://www.reddit.com/r/marketing/comments/1xyz789/top_marketing_trends/"
                    score: 892
                    numComments: 134
                    createdUtc: 1730100000
                    over18: false
                    stickied: false
                    flairText: null
                    isGallery: false
                  - id: "1def456"
                    fullname: "t3_1def456"
                    title: "Check out my grow setup"
                    author: "growthexpert"
                    subreddit: "gardening"
                    url: "https://www.reddit.com/gallery/1def456"
                    permalink: "https://www.reddit.com/r/gardening/comments/1def456/check_out_my_grow_setup/"
                    score: 567
                    numComments: 89
                    createdUtc: 1730050000
                    over18: false
                    stickied: false
                    flairText: null
                    isGallery: true
                    galleryImages:
                      - "https://i.redd.it/abc123.jpg"
                      - "https://i.redd.it/def456.jpg"
                after: "t3_1def456"
                before: null
        '400': { description: Missing params }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }
  /v1/usage-stats:
    get:
      operationId: getUsageStats
      tags: [Usage]
      summary: Get plan and usage stats
      description: Returns the current plan name, billing period, plan limits, and usage counts.
      responses:
        '200':
          description: Usage stats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageStats'
              example:
                planName: "Pro"
                billingPeriod: "monthly"
                signupDate: "2024-01-15T10:30:00Z"
                billingAnchorDay: 15
                limits:
                  uploads: 500
                  profiles: 10
                usage:
                  uploads: 127
                  profiles: 3
                  lastReset: "2024-11-01T00:00:00Z"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/posts:
    get:
      operationId: listPosts
      tags: [Posts]
      summary: List posts
      description: Returns a paginated list of posts. Published posts include platformPostUrl with the public URL on each platform.
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: status
          in: query
          schema: { type: string, enum: [draft, scheduled, published, failed] }
        - name: platform
          in: query
          schema: { type: string, example: twitter }
        - name: profileId
          in: query
          schema: { type: string }
        - name: createdBy
          in: query
          schema: { type: string }
        - name: dateFrom
          in: query
          schema: { type: string, format: date }
        - name: dateTo
          in: query
          schema: { type: string, format: date }
        - name: includeHidden
          in: query
          schema: { type: boolean, default: false }
        - name: search
          in: query
          schema: { type: string }
          description: Search posts by text content.
        - name: sortBy
          in: query
          schema:
            type: string
            enum: [scheduled-desc, scheduled-asc, created-desc, created-asc, status, platform]
            default: scheduled-desc
          description: Sort order for results.
      responses:
        '200':
          description: Paginated posts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostsListResponse'
              examples:
                scheduledPost:
                  summary: Scheduled post (pending publish)
                  value:
                    posts:
                      - _id: "65f1c0a9e2b5af0012ab34cd"
                        title: "Launch post"
                        content: "We just launched!"
                        status: "scheduled"
                        scheduledFor: "2024-11-01T10:00:00Z"
                        timezone: "UTC"
                        platforms:
                          - platform: "twitter"
                            accountId:
                              _id: "64e1f0..."
                              platform: "twitter"
                              username: "@acme"
                              displayName: "Acme Corp"
                              isActive: true
                            status: "pending"
                        tags: ["launch"]
                        createdAt: "2024-10-01T12:00:00Z"
                        updatedAt: "2024-10-01T12:00:00Z"
                    pagination:
                      page: 1
                      limit: 10
                      total: 1
                      pages: 1
                publishedPost:
                  summary: Published post with platformPostUrl
                  value:
                    posts:
                      - _id: "65f1c0a9e2b5af0012ab34cd"
                        title: "Launch post"
                        content: "We just launched!"
                        status: "published"
                        scheduledFor: "2024-11-01T10:00:00Z"
                        publishedAt: "2024-11-01T10:00:05Z"
                        timezone: "UTC"
                        platforms:
                          - platform: "twitter"
                            accountId:
                              _id: "64e1f0a9e2b5af0012ab34de"
                              platform: "twitter"
                              username: "@acmecorp"
                              displayName: "Acme Corporation"
                              isActive: true
                            status: "published"
                            publishedAt: "2024-11-01T10:00:05Z"
                            platformPostId: "1852634789012345678"
                            platformPostUrl: "https://twitter.com/acmecorp/status/1852634789012345678"
                          - platform: "linkedin"
                            accountId:
                              _id: "64e1f0a9e2b5af0012ab34ef"
                              platform: "linkedin"
                              username: "acme-corporation"
                              displayName: "Acme Corporation"
                              isActive: true
                            status: "published"
                            publishedAt: "2024-11-01T10:00:06Z"
                            platformPostId: "urn:li:share:7123456789012345678"
                            platformPostUrl: "https://www.linkedin.com/feed/update/urn:li:share:7123456789012345678"
                        tags: ["launch"]
                        createdAt: "2024-10-01T12:00:00Z"
                        updatedAt: "2024-11-01T10:00:06Z"
                    pagination:
                      page: 1
                      limit: 10
                      total: 1
                      pages: 1
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      operationId: createPost
      tags: [Posts]
      summary: Create post
      description: |
        Create and optionally publish a post. Immediate posts (publishNow: true) include platformPostUrl in the response.
        Content is optional when media is attached or all platforms have customContent. See each platform's schema for media constraints.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title: { type: string }
                content:
                  type: string
                  description: Post caption/text. Optional when media is attached or all platforms have customContent. Required for text-only posts.
                mediaItems:
                  type: array
                  items:
                    type: object
                    properties:
                      type: { type: string, enum: [image, video, gif, document] }
                      url: { type: string, format: uri }
                platforms:
                  type: array
                  description: Target platforms and accounts for this post. Required for non-draft posts (returns 400 if empty). Drafts can omit platforms.
                  items:
                    type: object
                    properties:
                      platform: { type: string, example: twitter }
                      accountId: { type: string }
                      customContent:
                        type: string
                        description: Platform-specific text override. When set, this content is used instead of the top-level post content for this platform. Useful for tailoring captions per platform (e.g. keeping tweets under 280 characters).
                      customMedia:
                        type: array
                        items:
                          type: object
                          properties:
                            type: { type: string, enum: [image, video, gif, document] }
                            url: { type: string, format: uri }
                      scheduledFor:
                        type: string
                        format: date-time
                        description: Optional per-platform scheduled time override. When omitted, the top-level scheduledFor is used.
                      platformSpecificData:
                        oneOf:
                          - $ref: '#/components/schemas/TwitterPlatformData'
                          - $ref: '#/components/schemas/ThreadsPlatformData'
                          - $ref: '#/components/schemas/FacebookPlatformData'
                          - $ref: '#/components/schemas/InstagramPlatformData'
                          - $ref: '#/components/schemas/LinkedInPlatformData'
                          - $ref: '#/components/schemas/PinterestPlatformData'
                          - $ref: '#/components/schemas/YouTubePlatformData'
                          - $ref: '#/components/schemas/GoogleBusinessPlatformData'
                          - $ref: '#/components/schemas/TikTokPlatformData'
                          - $ref: '#/components/schemas/TelegramPlatformData'
                          - $ref: '#/components/schemas/SnapchatPlatformData'
                          - $ref: '#/components/schemas/RedditPlatformData'
                          - $ref: '#/components/schemas/BlueskyPlatformData'
                scheduledFor: { type: string, format: date-time }
                publishNow: { type: boolean, default: false }
                isDraft:
                  type: boolean
                  default: false
                  description: When true, saves the post as a draft. When none of scheduledFor, publishNow, or queuedFromProfile are provided, the post defaults to draft automatically.
                timezone: { type: string, default: UTC }
                tags:
                  type: array
                  description: "Tags/keywords. YouTube constraints: each tag max 100 chars, combined max 500 chars, duplicates auto-removed."
                  items: { type: string }
                hashtags:
                  type: array
                  items: { type: string }
                mentions:
                  type: array
                  description: "Stored for reference only. This field does NOT automatically create @mentions when publishing. For LinkedIn @mentions, use the /v1/accounts/{accountId}/linkedin-mentions endpoint to resolve profile URLs to URNs, then embed the returned mentionFormat directly in the post content field."
                  items: { type: string }
                crosspostingEnabled: { type: boolean, default: true }
                metadata: { type: object, additionalProperties: true }
                tiktokSettings:
                  $ref: '#/components/schemas/TikTokPlatformData'
                  description: Root-level TikTok settings applied to all TikTok platforms. Merged into each platform's platformSpecificData, with platform-specific settings taking precedence.
                facebookSettings:
                  $ref: '#/components/schemas/FacebookPlatformData'
                  description: Root-level Facebook settings applied to all Facebook platforms. Merged into each platform's platformSpecificData, with platform-specific settings taking precedence.
                recycling:
                  $ref: '#/components/schemas/RecyclingConfig'
                queuedFromProfile:
                  type: string
                  description: Profile ID to schedule via queue. When provided without scheduledFor, the post is auto-assigned to the next available slot. Do not call /v1/queue/next-slot and use that time in scheduledFor, as that bypasses queue locking.
                queueId:
                  type: string
                  description: |
                    Specific queue ID to use when scheduling via queue.
                    Only used when queuedFromProfile is also provided.
                    If omitted, uses the profile's default queue.
            examples:
              facebookDraft:
                summary: Facebook draft post (visible in Publishing Tools)
                value:
                  content: "Draft post for review before publishing"
                  platforms:
                    - platform: facebook
                      accountId: "64e1f0a9e2b5af0012ab34cd"
                  publishNow: true
                  facebookSettings:
                    draft: true
              recyclingPost:
                summary: Post with weekly recycling and content variations
                value:
                  content: "Check out our evergreen guide!"
                  platforms:
                    - platform: twitter
                      accountId: "64e1f0a9e2b5af0012ab34cd"
                  scheduledFor: "2025-06-01T10:00:00Z"
                  recycling:
                    gap: 2
                    gapFreq: week
                    expireCount: 6
                    contentVariations:
                      - "Check out our evergreen guide!"
                      - "Don't miss our essential guide!"
                      - "Our most popular guide, updated!"
              tiktokPhotoCarousel:
                summary: TikTok photo carousel with draft mode
                value:
                  content: "Check out these photos!"
                  mediaItems:
                    - type: image
                      url: "https://example.com/photo1.jpg"
                    - type: image
                      url: "https://example.com/photo2.jpg"
                  platforms:
                    - platform: tiktok
                      accountId: "64e1f0a9e2b5af0012ab34cd"
                  tiktokSettings:
                    draft: true
                    privacyLevel: "PUBLIC_TO_EVERYONE"
                    allowComment: true
                    contentPreviewConfirmed: true
                    expressConsentGiven: true
              tiktokVideo:
                summary: TikTok video post (direct publish)
                value:
                  content: "New video is live!"
                  mediaItems:
                    - type: video
                      url: "https://example.com/video.mp4"
                  platforms:
                    - platform: tiktok
                      accountId: "64e1f0a9e2b5af0012ab34cd"
                  tiktokSettings:
                    privacyLevel: "PUBLIC_TO_EVERYONE"
                    allowComment: true
                    allowDuet: true
                    allowStitch: true
                    commercialContentType: "none"
                    contentPreviewConfirmed: true
                    expressConsentGiven: true
              multiPlatform:
                summary: Multi-platform post (Twitter + LinkedIn)
                value:
                  content: "We just launched our new product!"
                  mediaItems:
                    - type: image
                      url: "https://example.com/launch.jpg"
                  platforms:
                    - platform: twitter
                      accountId: "64e1f0a9e2b5af0012ab34cd"
                    - platform: linkedin
                      accountId: "64e1f0a9e2b5af0012ab34ef"
                  scheduledFor: "2024-11-01T10:00:00Z"
                  timezone: "America/New_York"
      responses:
        '201':
          description: Post created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostCreateResponse'
              examples:
                scheduled:
                  summary: Scheduled post (URLs populated after publish time)
                  value:
                    post:
                      _id: "65f1c0a9e2b5af0012ab34cd"
                      title: "Launch post"
                      content: "We just launched!"
                      status: "scheduled"
                      scheduledFor: "2024-11-01T10:00:00Z"
                      timezone: "UTC"
                      platforms:
                        - platform: "twitter"
                          accountId:
                            _id: "64e1f0..."
                            platform: "twitter"
                            username: "@acme"
                            displayName: "Acme Corp"
                            isActive: true
                          status: "pending"
                    message: "Post scheduled successfully"
                immediatePublish:
                  summary: Immediate post with publishNow=true (URLs included)
                  value:
                    post:
                      _id: "65f1c0a9e2b5af0012ab34cd"
                      title: "Launch post"
                      content: "We just launched!"
                      status: "published"
                      publishedAt: "2024-11-01T10:00:05Z"
                      timezone: "UTC"
                      platforms:
                        - platform: "twitter"
                          accountId:
                            _id: "64e1f0a9e2b5af0012ab34de"
                            platform: "twitter"
                            username: "@acmecorp"
                            displayName: "Acme Corporation"
                            isActive: true
                          status: "published"
                          publishedAt: "2024-11-01T10:00:05Z"
                          platformPostId: "1852634789012345678"
                          platformPostUrl: "https://twitter.com/acmecorp/status/1852634789012345678"
                        - platform: "linkedin"
                          accountId:
                            _id: "64e1f0a9e2b5af0012ab34ef"
                            platform: "linkedin"
                            username: "acme-corporation"
                            displayName: "Acme Corporation"
                            isActive: true
                          status: "published"
                          publishedAt: "2024-11-01T10:00:06Z"
                          platformPostId: "urn:li:share:7123456789012345678"
                          platformPostUrl: "https://www.linkedin.com/feed/update/urn:li:share:7123456789012345678"
                    message: "Post published successfully"
                queueScheduled:
                  summary: Post scheduled via queue (using queuedFromProfile)
                  value:
                    post:
                      _id: "65f1c0a9e2b5af0012ab34cd"
                      content: "Scheduled via queue!"
                      status: "scheduled"
                      scheduledFor: "2024-11-01T09:00:00Z"
                      timezone: "America/New_York"
                      queuedFromProfile: "64f0a1b2c3d4e5f6a7b8c9d0"
                      queueId: "64f0a1b2c3d4e5f6a7b8c9d1"
                      platforms:
                        - platform: "linkedin"
                          accountId:
                            _id: "64e1f0..."
                            platform: "linkedin"
                            username: "acme-corp"
                            displayName: "Acme Corp"
                            isActive: true
                          status: "pending"
                    message: "Post scheduled successfully"
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
        '409':
          description: Duplicate content detected
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: "This exact content was already posted to this account within the last 24 hours." }
                  details:
                    type: object
                    properties:
                      accountId: { type: string }
                      platform: { type: string }
                      existingPostId: { type: string }
        '429':
          description: "Rate limit exceeded. Possible causes: API rate limit, velocity limit (15 posts/hour per account), account cooldown, or daily platform limits."
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  details:
                    type: object
                    description: Additional context about the rate limit
          headers:
            Retry-After:
              description: Seconds until the rate limit resets (for API rate limits)
              schema: { type: integer }
            X-RateLimit-Limit:
              description: The rate limit ceiling
              schema: { type: integer }
            X-RateLimit-Remaining:
              description: Requests remaining in current window
              schema: { type: integer }
  /v1/posts/{postId}:
    get:
      operationId: getPost
      tags: [Posts]
      summary: Get post
      description: |
        Fetch a single post by ID. For published posts, this returns platformPostUrl for each platform.
      parameters:
        - name: postId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Post
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostGetResponse'
              examples:
                scheduledPost:
                  summary: Scheduled post (pending)
                  value:
                    post:
                      _id: "65f1c0a9e2b5af0012ab34cd"
                      title: "Launch post"
                      content: "We just launched!"
                      status: "scheduled"
                      scheduledFor: "2024-11-01T10:00:00Z"
                      platforms:
                        - platform: "twitter"
                          accountId:
                            _id: "64e1f0..."
                            platform: "twitter"
                            username: "@acme"
                            displayName: "Acme Corp"
                            isActive: true
                          status: "pending"
                publishedPost:
                  summary: Published post with platformPostUrl
                  value:
                    post:
                      _id: "65f1c0a9e2b5af0012ab34cd"
                      title: "Launch post"
                      content: "We just launched!"
                      status: "published"
                      publishedAt: "2024-11-01T10:00:05Z"
                      platforms:
                        - platform: "twitter"
                          accountId:
                            _id: "64e1f0a9e2b5af0012ab34de"
                            platform: "twitter"
                            username: "@acmecorp"
                            displayName: "Acme Corporation"
                            isActive: true
                          status: "published"
                          publishedAt: "2024-11-01T10:00:05Z"
                          platformPostId: "1852634789012345678"
                          platformPostUrl: "https://twitter.com/acmecorp/status/1852634789012345678"
                        - platform: "linkedin"
                          accountId:
                            _id: "64e1f0a9e2b5af0012ab34ef"
                            platform: "linkedin"
                            username: "acme-corporation"
                            displayName: "Acme Corporation"
                            isActive: true
                          status: "published"
                          publishedAt: "2024-11-01T10:00:06Z"
                          platformPostId: "urn:li:share:7123456789012345678"
                          platformPostUrl: "https://www.linkedin.com/feed/update/urn:li:share:7123456789012345678"
                failedPost:
                  summary: Failed post with error details
                  value:
                    post:
                      _id: "65f1c0a9e2b5af0012ab34cd"
                      content: "This post failed to publish"
                      status: "failed"
                      platforms:
                        - platform: "instagram"
                          accountId:
                            _id: "64e1f0a9e2b5af0012ab34de"
                            platform: "instagram"
                            username: "acmecorp"
                            isActive: false
                          status: "failed"
                          errorMessage: "Instagram access token has expired. Please reconnect your account."
                          errorCategory: "auth_expired"
                          errorSource: "user"
                partialPost:
                  summary: Partial success (some platforms failed)
                  value:
                    post:
                      _id: "65f1c0a9e2b5af0012ab34cd"
                      content: "Launch announcement!"
                      status: "partial"
                      platforms:
                        - platform: "twitter"
                          accountId:
                            _id: "64e1f0a9e2b5af0012ab34de"
                            platform: "twitter"
                            username: "@acmecorp"
                            isActive: true
                          status: "published"
                          publishedAt: "2024-11-01T10:00:05Z"
                          platformPostId: "1852634789012345678"
                          platformPostUrl: "https://twitter.com/acmecorp/status/1852634789012345678"
                        - platform: "threads"
                          accountId:
                            _id: "64e1f0a9e2b5af0012ab34ef"
                            platform: "threads"
                            username: "acmecorp"
                            isActive: true
                          status: "failed"
                          errorMessage: "Post text exceeds the 500 character limit for Threads."
                          errorCategory: "user_content"
                          errorSource: "user"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Forbidden
        '404': { $ref: '#/components/responses/NotFound' }
    put:
      operationId: updatePost
      tags: [Posts]
      summary: Update post
      description: |
        Update an existing post. Only draft, scheduled, failed, and partial posts can be edited.
        Published, publishing, and cancelled posts cannot be modified.
      parameters:
        - name: postId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content: { type: string }
                scheduledFor: { type: string, format: date-time }
                tiktokSettings:
                  $ref: '#/components/schemas/TikTokPlatformData'
                  description: Root-level TikTok settings applied to all TikTok platforms. Merged into each platform's platformSpecificData, with platform-specific settings taking precedence.
                facebookSettings:
                  $ref: '#/components/schemas/FacebookPlatformData'
                  description: Root-level Facebook settings applied to all Facebook platforms. Merged into each platform's platformSpecificData, with platform-specific settings taking precedence.
                recycling:
                  $ref: '#/components/schemas/RecyclingConfig'
              additionalProperties: true
            example:
              content: "Updated content for our launch post!"
              scheduledFor: "2024-11-02T14:00:00Z"
      responses:
        '200':
          description: Post updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostUpdateResponse'
              example:
                message: "Post updated successfully"
                post:
                  _id: "65f1c0a9e2b5af0012ab34cd"
                  content: "Updated content for our launch post!"
                  status: "scheduled"
                  scheduledFor: "2024-11-02T14:00:00Z"
        '207':
          description: Partial publish success
        '400':
          description: Invalid request
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Forbidden
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: deletePost
      tags: [Posts]
      summary: Delete post
      description: Delete a draft or scheduled post from Zernio. Published posts cannot be deleted; use the Unpublish endpoint instead. Upload quota is automatically refunded.
      parameters:
        - name: postId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostDeleteResponse'
              example:
                message: "Post deleted successfully"
        '400':
          description: Cannot delete published posts
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Forbidden
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/posts/bulk-upload:
    post:
      operationId: bulkUploadPosts
      tags: [Posts]
      summary: Bulk upload from CSV
      description: Create multiple posts by uploading a CSV file. Use dryRun=true to validate without creating posts.
      parameters:
        - name: dryRun
          in: query
          schema: { type: boolean, default: false }
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Bulk upload results
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  totalRows: { type: integer }
                  created: { type: integer }
                  failed: { type: integer }
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        row: { type: integer }
                        error: { type: string }
                  posts:
                    type: array
                    items: { $ref: '#/components/schemas/Post' }
              example:
                success: true
                totalRows: 10
                created: 8
                failed: 2
                errors:
                  - row: 3
                    error: "Invalid date format"
                  - row: 7
                    error: "Account not found"
                posts:
                  - _id: "65f1c0a9e2b5af0012ab34cd"
                    content: "First bulk post"
                    status: "scheduled"
                    scheduledFor: "2024-11-01T10:00:00Z"
        '207':
          description: Partial success
        '400':
          description: Invalid CSV or validation errors
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429':
          description: |
            Rate limit exceeded. Possible causes: API rate limit (requests per minute) or account cooldown (one or more accounts for platforms specified in the CSV are temporarily rate-limited).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  details:
                    type: object
  /v1/posts/{postId}/retry:
    post:
      operationId: retryPost
      tags: [Posts]
      summary: Retry failed post
      description: Immediately retries publishing a failed post. Returns the updated post with its new status.
      parameters:
        - name: postId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Retry successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostRetryResponse'
              example:
                message: "Post published successfully"
                post:
                  _id: "65f1c0a9e2b5af0012ab34cd"
                  content: "Check out our new product!"
                  status: "published"
                  publishedAt: "2024-11-01T10:00:05Z"
                  platforms:
                    - platform: "twitter"
                      accountId:
                        _id: "64e1f0..."
                        platform: "twitter"
                        username: "@acme"
                        displayName: "Acme Corp"
                        isActive: true
                      status: "published"
                      platformPostId: "1234567890"
                      platformPostUrl: "https://twitter.com/acme/status/1234567890"
        '207':
          description: Partial success
        '400':
          description: Invalid state
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Forbidden
        '404': { $ref: '#/components/responses/NotFound' }
        '409':
          description: Post is currently publishing
        '429':
          description: |
            Rate limit exceeded. Possible causes: API rate limit (requests per minute), velocity limit (15 posts/hour per account), or account cooldown (temporarily rate-limited due to repeated errors).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  details:
                    type: object
  /v1/posts/{postId}/unpublish:
    post:
      operationId: unpublishPost
      tags: [Posts]
      summary: Unpublish post
      description: |
        Deletes a published post from the specified platform. The post record in Zernio is kept but its status is updated to cancelled.
        Not supported on Instagram, TikTok, or Snapchat. Threaded posts delete all items. YouTube deletion is permanent.
      parameters:
        - name: postId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [platform]
              properties:
                platform:
                  type: string
                  description: The platform to delete the post from
                  enum:
                    - threads
                    - facebook
                    - twitter
                    - linkedin
                    - youtube
                    - pinterest
                    - reddit
                    - bluesky
                    - googlebusiness
                    - telegram
            example:
              platform: "threads"
      responses:
        '200':
          description: Post deleted from platform
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
              example:
                success: true
                message: "Post deleted from threads successfully"
        '400':
          description: "Invalid request: platform not supported for deletion, post not on that platform, not published, no platform post ID, or no access token."
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Forbidden
        '404': { $ref: '#/components/responses/NotFound' }
        '500':
          description: Platform API deletion failed
  /v1/posts/{postId}/edit:
    post:
      operationId: editPost
      tags: [Posts]
      summary: Edit published post
      description: |
        Edit a published post on a social media platform. Currently only supported for X (Twitter).

        **Requirements:**
        - Connected X account must have an active X Premium subscription
        - Must be within 1 hour of original publish time
        - Maximum 5 edits per tweet (enforced by X)
        - Text-only edits (media changes are not supported)

        The post record in Zernio is updated with the new content and edit history.
      parameters:
        - name: postId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [platform, content]
              properties:
                platform:
                  type: string
                  description: The platform to edit the post on. Currently only twitter is supported.
                  enum: [twitter]
                content:
                  type: string
                  description: The new tweet text content
            example:
              platform: "twitter"
              content: "Updated tweet text with corrected information"
      responses:
        '200':
          description: Post edited successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  id: { type: string, description: New tweet ID assigned by X after edit }
                  url: { type: string, format: uri, description: URL of the edited tweet }
                  message: { type: string }
              example:
                success: true
                id: "1234567890123456790"
                url: "https://twitter.com/i/web/status/1234567890123456790"
                message: "Tweet edited successfully"
        '400':
          description: "Invalid request: platform not supported, post not published, edit window expired, not Premium, or missing content."
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Forbidden
        '404': { $ref: '#/components/responses/NotFound' }
        '500':
          description: Platform API edit failed
  /v1/posts/{postId}/update-metadata:
    post:
      operationId: updatePostMetadata
      tags: [Posts]
      summary: Update post metadata
      description: |
        Updates metadata of a published video on the specified platform without re-uploading.
        Currently only supported for YouTube. At least one updatable field is required.

        **Two modes:**

        1. **Post-based** (video published through Zernio): pass the Zernio postId in the URL and `platform` in the body.
        2. **Direct video ID** (video uploaded outside Zernio, e.g. directly to YouTube): use `_` as the postId,
           and pass `videoId` + `accountId` + `platform` in the body. The accountId is the Zernio social account ID
           for the connected YouTube channel.
      parameters:
        - name: postId
          in: path
          required: true
          schema: { type: string }
          description: Zernio post ID, or "_" when using direct video ID mode
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [platform]
              properties:
                platform:
                  type: string
                  description: The platform to update metadata on
                  enum:
                    - youtube
                videoId:
                  type: string
                  description: YouTube video ID (required for direct mode, ignored for post-based mode)
                accountId:
                  type: string
                  description: Zernio social account ID (required for direct mode, ignored for post-based mode)
                title:
                  type: string
                  maxLength: 100
                  description: New video title (max 100 characters for YouTube)
                description:
                  type: string
                  description: New video description
                tags:
                  type: array
                  items:
                    type: string
                    maxLength: 100
                  description: Array of keyword tags (max 500 characters combined for YouTube)
                categoryId:
                  type: string
                  description: YouTube video category ID
                privacyStatus:
                  type: string
                  enum: [public, private, unlisted]
                  description: Video privacy setting
                thumbnailUrl:
                  type: string
                  format: uri
                  description: "Public URL of a custom thumbnail image (JPEG, PNG, or GIF, max 2 MB, recommended 1280x720). Works on any video you own, including existing videos not published through Zernio. The channel must be verified (phone verification) to set custom thumbnails."
                madeForKids:
                  type: boolean
                  description: "COPPA compliance flag. Set true for child-directed content (restricts comments, notifications, ad targeting)."
                containsSyntheticMedia:
                  type: boolean
                  description: "AI-generated content disclosure. Set true if the video contains synthetic content that could be mistaken for real. YouTube may add a label."
                playlistId:
                  type: string
                  description: "YouTube playlist ID to add the video to (e.g. 'PLxxxxxxxxxxxxx'). Use GET /v1/accounts/{id}/youtube-playlists to list available playlists. Only playlists owned by the channel are supported."
            examples:
              post-based:
                summary: Update a video published through Zernio
                value:
                  platform: "youtube"
                  title: "Updated Video Title"
                  description: "New SEO-optimized description"
                  tags: ["seo", "marketing", "tutorial"]
              direct-video-id:
                summary: Update a video uploaded directly to YouTube
                value:
                  platform: "youtube"
                  videoId: "dQw4w9WgXcQ"
                  accountId: "68fb37418bbca9c10cbfef26"
                  title: "Updated Title with SEO Keywords"
                  tags: ["seo", "youtube", "optimization"]
              update-thumbnail:
                summary: Update thumbnail on an existing video
                value:
                  platform: "youtube"
                  videoId: "dQw4w9WgXcQ"
                  accountId: "68fb37418bbca9c10cbfef26"
                  thumbnailUrl: "https://example.com/my-thumbnail.jpg"
      responses:
        '200':
          description: Metadata updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
                  videoId: { type: string, description: Only present in direct video ID mode }
                  updatedFields:
                    type: array
                    items: { type: string }
              example:
                success: true
                message: "YouTube video metadata updated successfully"
                updatedFields: ["title", "description", "tags"]
        '400':
          description: "Invalid request: unsupported platform, post not published, missing fields, or validation error."
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Forbidden
        '404': { $ref: '#/components/responses/NotFound' }
        '500':
          description: Platform API update failed
  /v1/users:
    get:
      operationId: listUsers
      tags: [Users]
      summary: List users
      description: Returns all users in the workspace including roles and profile access. Also returns the currentUserId of the caller.
      responses:
        '200':
          description: Users
          content:
            application/json:
              schema:
                type: object
                properties:
                  currentUserId: { type: string }
                  users:
                    type: array
                    items:
                      type: object
                      properties:
                        _id: { type: string }
                        name: { type: string }
                        email: { type: string }
                        role: { type: string }
                        isRoot: { type: boolean }
                        profileAccess:
                          type: array
                          items: { type: string }
                        createdAt: { type: string, format: date-time }
              example:
                currentUserId: "6507a1b2c3d4e5f6a7b8c9d0"
                users:
                  - _id: "6507a1b2c3d4e5f6a7b8c9d0"
                    name: "John Doe"
                    email: "john@example.com"
                    role: "owner"
                    isRoot: true
                    profileAccess: ["all"]
                    createdAt: "2024-01-15T10:30:00Z"
                  - _id: "6507a1b2c3d4e5f6a7b8c9d1"
                    name: "Jane Smith"
                    email: "jane@example.com"
                    role: "member"
                    isRoot: false
                    profileAccess:
                      - "64f0a1b2c3d4e5f6a7b8c9d0"
                      - "64f0a1b2c3d4e5f6a7b8c9d1"
                    createdAt: "2024-03-20T14:45:00Z"
        '401': { $ref: '#/components/responses/Unauthorized' }
  /v1/users/{userId}:
    get:
      operationId: getUser
      tags: [Users]
      summary: Get user
      description: Returns a single user's details by ID, including name, email, and role.
      parameters:
        - name: userId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: User
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    type: object
                    properties:
                      _id: { type: string }
                      name: { type: string }
                      email: { type: string }
                      role: { type: string }
                      isRoot: { type: boolean }
                      profileAccess:
                        type: array
                        items: { type: string }
              example:
                user:
                  _id: "6507a1b2c3d4e5f6a7b8c9d0"
                  name: "John Doe"
                  email: "john@example.com"
                  role: "owner"
                  isRoot: true
                  profileAccess: ["all"]
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Forbidden
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/profiles:
    get:
      operationId: listProfiles
      tags: [Profiles]
      summary: List profiles
      description: Returns profiles sorted by creation date. Use includeOverLimit=true to include profiles that exceed the plan limit.
      parameters:
        - name: includeOverLimit
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: "When true, includes over-limit profiles (marked with isOverLimit: true)."
      responses:
        '200':
          description: Profiles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfilesListResponse'
              examples:
                example:
                  value:
                    profiles:
                      - _id: "64f0..."
                        name: "Personal Brand"
                        color: "#ffeda0"
                        isDefault: true
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      operationId: createProfile
      tags: [Profiles]
      summary: Create profile
      description: Creates a new profile with a name, optional description, and color.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
                description: { type: string }
                color: { type: string, example: '#ffeda0' }
            example:
              name: "Marketing Team"
              description: "Profile for marketing campaigns"
              color: "#4CAF50"
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProfileCreateResponse'
              example:
                message: "Profile created successfully"
                profile:
                  _id: "64f0a1b2c3d4e5f6a7b8c9d0"
                  userId: "6507a1b2c3d4e5f6a7b8c9d0"
                  name: "Marketing Team"
                  description: "Profile for marketing campaigns"
                  color: "#4CAF50"
                  isDefault: false
                  createdAt: "2024-11-01T10:00:00Z"
        '400': { description: Invalid request }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { description: Profile limit exceeded }
  /v1/profiles/{profileId}:
    get:
      operationId: getProfile
      tags: [Profiles]
      summary: Get profile
      description: Returns a single profile by ID, including its name, color, and default status.
      parameters:
        - name: profileId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Profile
          content:
            application/json:
              schema:
                type: object
                properties:
                  profile: { $ref: '#/components/schemas/Profile' }
              example:
                profile:
                  _id: "64f0a1b2c3d4e5f6a7b8c9d0"
                  userId: "6507a1b2c3d4e5f6a7b8c9d0"
                  name: "Marketing Team"
                  description: "Profile for marketing campaigns"
                  color: "#4CAF50"
                  isDefault: false
                  createdAt: "2024-11-01T10:00:00Z"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    put:
      operationId: updateProfile
      tags: [Profiles]
      summary: Update profile
      description: Updates a profile's name, description, color, or default status.
      parameters:
        - name: profileId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                description: { type: string }
                color: { type: string }
                isDefault: { type: boolean }
            example:
              name: "Marketing Team (Updated)"
              color: "#2196F3"
              isDefault: true
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  profile: { $ref: '#/components/schemas/Profile' }
              example:
                message: "Profile updated successfully"
                profile:
                  _id: "64f0a1b2c3d4e5f6a7b8c9d0"
                  userId: "6507a1b2c3d4e5f6a7b8c9d0"
                  name: "Marketing Team (Updated)"
                  description: "Profile for marketing campaigns"
                  color: "#2196F3"
                  isDefault: true
                  createdAt: "2024-11-01T10:00:00Z"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: deleteProfile
      tags: [Profiles]
      summary: Delete profile
      description: Permanently deletes a profile by ID.
      parameters:
        - name: profileId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
              example:
                message: "Profile deleted successfully"
        '400': { description: Has connected accounts }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { description: Forbidden }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/accounts:
    get:
      operationId: listAccounts
      tags: [Accounts]
      summary: List accounts
      description: |
        Returns connected social accounts. Only includes accounts within the plan limit by default. Follower data requires analytics add-on.
        Supports optional server-side pagination via page/limit params. When omitted, returns all accounts (backward-compatible).
      parameters:
        - name: profileId
          in: query
          schema: { type: string }
          description: Filter accounts by profile ID
        - name: platform
          in: query
          schema: { type: string }
          description: Filter accounts by platform (e.g. "instagram", "twitter").
        - name: includeOverLimit
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: When true, includes accounts from over-limit profiles.
        - name: page
          in: query
          schema: { type: integer, minimum: 1 }
          description: Page number (1-based). When provided with limit, enables server-side pagination. Omit for all accounts.
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100 }
          description: Page size. Required alongside page for pagination.
      responses:
        '200':
          description: Accounts (with optional pagination)
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    type: array
                    items: { $ref: '#/components/schemas/SocialAccount' }
                  hasAnalyticsAccess:
                    type: boolean
                    description: Whether user has analytics add-on access
                  pagination:
                    description: Only present when page/limit params are provided
                    $ref: '#/components/schemas/Pagination'
              examples:
                example:
                  value:
                    accounts:
                      - _id: "64e1..."
                        platform: "twitter"
                        profileId:
                          _id: "64f0..."
                          name: "My Brand"
                          slug: "my-brand"
                        username: "@acme"
                        displayName: "Acme"
                        profileUrl: "https://x.com/acme"
                        isActive: true
                    hasAnalyticsAccess: false
        '401': { $ref: '#/components/responses/Unauthorized' }
  /v1/accounts/follower-stats:
    get:
      operationId: getFollowerStats
      tags: [Accounts, Analytics]
      summary: Get follower stats
      description: |
        Returns follower count history and growth metrics for connected social accounts.
        Requires analytics add-on subscription. Follower counts are refreshed once per day.
      parameters:
        - name: accountIds
          in: query
          schema: { type: string }
          description: Comma-separated list of account IDs (optional, defaults to all user's accounts)
        - name: profileId
          in: query
          schema: { type: string }
          description: Filter by profile ID
        - name: fromDate
          in: query
          schema: { type: string, format: date }
          description: Start date in YYYY-MM-DD format (defaults to 30 days ago)
        - name: toDate
          in: query
          schema: { type: string, format: date }
          description: End date in YYYY-MM-DD format (defaults to today)
        - name: granularity
          in: query
          schema: { type: string, enum: [daily, weekly, monthly], default: daily }
          description: Data aggregation level
      responses:
        '200':
          description: Follower stats
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccountWithFollowerStats'
                  stats:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: object
                        properties:
                          date: { type: string, format: date }
                          followers: { type: number }
                  dateRange:
                    type: object
                    properties:
                      from: { type: string, format: date-time }
                      to: { type: string, format: date-time }
                  granularity: { type: string }
              examples:
                example:
                  value:
                    accounts:
                      - _id: "64e1..."
                        platform: "twitter"
                        username: "@acme"
                        currentFollowers: 1250
                        growth: 50
                        growthPercentage: 4.17
                        dataPoints: 30
                    stats:
                      "64e1...":
                        - date: "2024-01-01"
                          followers: 1200
                        - date: "2024-01-02"
                          followers: 1250
                    dateRange:
                      from: "2024-01-01T00:00:00.000Z"
                      to: "2024-01-31T23:59:59.999Z"
                    granularity: "daily"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Analytics add-on required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string, example: Analytics add-on required }
                  message: { type: string, example: Follower stats tracking requires the Analytics add-on. Please upgrade to access this feature. }
                  requiresAddon: { type: boolean, example: true }
  /v1/accounts/{accountId}:
    put:
      operationId: updateAccount
      tags: [Accounts]
      summary: Update account
      description: Updates a connected social account's display name or username override.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username: { type: string }
                displayName: { type: string }
            example:
              displayName: "Acme Corporation Official"
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  username: { type: string }
                  displayName: { type: string }
              example:
                message: "Account updated successfully"
                username: "@acmecorp"
                displayName: "Acme Corporation Official"
        '400': { description: Invalid request }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: deleteAccount
      tags: [Accounts]
      summary: Disconnect account
      description: Disconnects and removes a connected social account.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Disconnected
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
              example:
                message: "Account disconnected successfully"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/accounts/{accountId}/disconnect-ads:
    post:
      operationId: disconnectAds
      tags: [Accounts]
      summary: Disconnect ads from an account
      description: |
        Disconnects ads from a social account without removing the posting connection.

        **Same-token platforms** (metaads, linkedinads, pinterestads): Sets an `adsOptOut` flag. The posting account and OAuth token are preserved. Reconnecting ads clears the flag.

        **Separate-token platforms** (tiktokads, xads): Clears the ads-specific metadata (marketing API tokens). The posting account stays intact.

        **Standalone platforms** (googleads): Do not use this endpoint. Use `DELETE /v1/accounts/{accountId}` instead, since Google Ads accounts are standalone.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
          description: The SocialAccount ID (parent posting account for same-token/separate-token platforms)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [adsPlatform]
              properties:
                adsPlatform:
                  type: string
                  enum: [metaads, linkedinads, pinterestads, tiktokads, xads]
                  description: The ads platform to disconnect
            example:
              adsPlatform: "tiktokads"
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Ads disconnected
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
              example:
                message: "tiktokads disconnected successfully"
        '400': { description: Invalid ads platform }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/accounts/health:
    get:
      operationId: getAllAccountsHealth
      tags: [Accounts]
      summary: Check accounts health
      description: Returns health status of all connected accounts including token validity, permissions, and issues needing attention.
      parameters:
        - name: profileId
          in: query
          description: Filter by profile ID
          schema: { type: string }
        - name: platform
          in: query
          description: Filter by platform
          schema:
            type: string
            enum: [facebook, instagram, linkedin, twitter, tiktok, youtube, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat]
        - name: status
          in: query
          description: Filter by health status
          schema:
            type: string
            enum: [healthy, warning, error]
      responses:
        '200':
          description: Account health summary
          content:
            application/json:
              schema:
                type: object
                properties:
                  summary:
                    type: object
                    properties:
                      total: { type: integer, description: Total number of accounts }
                      healthy: { type: integer, description: Number of healthy accounts }
                      warning: { type: integer, description: Number of accounts with warnings }
                      error: { type: integer, description: Number of accounts with errors }
                      needsReconnect: { type: integer, description: Number of accounts needing reconnection }
                  accounts:
                    type: array
                    items:
                      type: object
                      properties:
                        accountId: { type: string }
                        platform: { type: string }
                        username: { type: string }
                        displayName: { type: string }
                        profileId: { type: string }
                        status: { type: string, enum: [healthy, warning, error] }
                        canPost: { type: boolean }
                        canFetchAnalytics: { type: boolean }
                        tokenValid: { type: boolean }
                        tokenExpiresAt: { type: string, format: date-time }
                        needsReconnect: { type: boolean }
                        issues: { type: array, items: { type: string } }
              example:
                summary:
                  total: 5
                  healthy: 3
                  warning: 1
                  error: 1
                  needsReconnect: 1
                accounts:
                  - accountId: "abc123"
                    platform: "instagram"
                    username: "myaccount"
                    status: "healthy"
                    canPost: true
                    canFetchAnalytics: true
                    tokenValid: true
                    tokenExpiresAt: "2025-06-15T00:00:00Z"
                    needsReconnect: false
                    issues: []
                  - accountId: "def456"
                    platform: "twitter"
                    username: "mytwitter"
                    status: "error"
                    canPost: false
                    canFetchAnalytics: false
                    tokenValid: false
                    needsReconnect: true
                    issues: ["Token expired"]
        '401': { $ref: '#/components/responses/Unauthorized' }
  /v1/accounts/{accountId}/health:
    get:
      operationId: getAccountHealth
      tags: [Accounts]
      summary: Check account health
      description: Returns detailed health info for a specific account including token status, permissions, and recommendations.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
          description: The account ID to check
      responses:
        '200':
          description: Account health details
          content:
            application/json:
              schema:
                type: object
                properties:
                  accountId: { type: string }
                  platform: { type: string }
                  username: { type: string }
                  displayName: { type: string }
                  status:
                    type: string
                    enum: [healthy, warning, error]
                    description: Overall health status
                  tokenStatus:
                    type: object
                    properties:
                      valid: { type: boolean, description: Whether the token is valid }
                      expiresAt: { type: string, format: date-time }
                      expiresIn: { type: string, description: Human-readable time until expiry }
                      needsRefresh: { type: boolean, description: Whether token expires within 24 hours }
                  permissions:
                    type: object
                    properties:
                      posting:
                        type: array
                        items:
                          type: object
                          properties:
                            scope: { type: string }
                            granted: { type: boolean }
                            required: { type: boolean }
                      analytics:
                        type: array
                        items:
                          type: object
                          properties:
                            scope: { type: string }
                            granted: { type: boolean }
                            required: { type: boolean }
                      optional:
                        type: array
                        items:
                          type: object
                          properties:
                            scope: { type: string }
                            granted: { type: boolean }
                            required: { type: boolean }
                      canPost: { type: boolean }
                      canFetchAnalytics: { type: boolean }
                      missingRequired: { type: array, items: { type: string } }
                  issues:
                    type: array
                    items: { type: string }
                    description: List of issues found
                  recommendations:
                    type: array
                    items: { type: string }
                    description: Actionable recommendations to fix issues
              example:
                accountId: "abc123"
                platform: "instagram"
                username: "myaccount"
                displayName: "My Account"
                status: "healthy"
                tokenStatus:
                  valid: true
                  expiresAt: "2025-06-15T00:00:00Z"
                  expiresIn: "180 days"
                  needsRefresh: false
                permissions:
                  posting:
                    - scope: "instagram_basic"
                      granted: true
                      required: true
                    - scope: "instagram_content_publish"
                      granted: true
                      required: true
                  analytics:
                    - scope: "instagram_manage_insights"
                      granted: true
                      required: false
                  optional: []
                  canPost: true
                  canFetchAnalytics: true
                  missingRequired: []
                issues: []
                recommendations: []
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /v1/accounts/{accountId}/tiktok/creator-info:
    get:
      operationId: getTikTokCreatorInfo
      tags: [Accounts]
      summary: Get TikTok creator info
      description: Returns TikTok creator details, available privacy levels, posting limits, and commercial content options for a specific TikTok account. Only works with TikTok accounts.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
          description: The TikTok account ID
        - name: mediaType
          in: query
          required: false
          schema:
            type: string
            enum: [video, photo]
            default: video
          description: The media type to get creator info for (affects available interaction settings)
      responses:
        '200':
          description: TikTok creator info and posting options
          content:
            application/json:
              schema:
                type: object
                properties:
                  creator:
                    type: object
                    properties:
                      nickname: { type: string, description: Creator display name }
                      avatarUrl: { type: string, description: Creator avatar URL }
                      isVerified: { type: boolean, description: Whether the creator is verified }
                      canPostMore: { type: boolean, description: Whether the creator can publish more posts right now }
                  privacyLevels:
                    type: array
                    description: Available privacy level options for this creator
                    items:
                      type: object
                      properties:
                        value: { type: string, description: "Privacy level value to use when creating posts (e.g. PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY)" }
                        label: { type: string, description: Human-readable label }
                  postingLimits:
                    type: object
                    properties:
                      maxVideoDurationSec: { type: integer, description: Maximum video duration in seconds }
                      interactionSettings:
                        type: object
                        description: Available interaction toggles (comment, duet, stitch) and their defaults
                  commercialContentTypes:
                    type: array
                    description: Available commercial content disclosure options
                    items:
                      type: object
                      properties:
                        value: { type: string }
                        label: { type: string }
                        requires:
                          type: array
                          items: { type: string }
              example:
                creator:
                  nickname: "myaccount"
                  avatarUrl: "https://example.com/avatar.jpg"
                  isVerified: false
                  canPostMore: true
                privacyLevels:
                  - value: "PUBLIC_TO_EVERYONE"
                    label: "Public To Everyone"
                  - value: "MUTUAL_FOLLOW_FRIENDS"
                    label: "Mutual Follow Friends"
                  - value: "SELF_ONLY"
                    label: "Self Only"
                postingLimits:
                  maxVideoDurationSec: 600
                  interactionSettings:
                    comment: true
                    duet: true
                    stitch: true
                commercialContentTypes:
                  - value: "none"
                    label: "No Commercial Content"
                  - value: "brand_organic"
                    label: "Your Brand"
                    requires: ["is_brand_organic_post"]
        '400':
          description: Account is not a TikTok account
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
              example:
                error: "This endpoint is only available for TikTok accounts"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429':
          description: Creator has reached TikTok daily posting limit
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
              example:
                error: "TikTok creator has reached the daily posting limit. Please try again later."
  /v1/api-keys:
    get:
      operationId: listApiKeys
      tags: [API Keys]
      summary: List keys
      description: Returns all API keys for the authenticated user. Keys are returned with a preview only, not the full key value.
      responses:
        '200':
          description: API keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  apiKeys:
                    type: array
                    items: { $ref: '#/components/schemas/ApiKey' }
              example:
                apiKeys:
                  - id: "6507a1b2c3d4e5f6a7b8c9d0"
                    name: "Production API Key"
                    keyPreview: "sk_12345678...abcdef01"
                    expiresAt: "2025-12-31T23:59:59Z"
                    createdAt: "2024-01-15T10:30:00Z"
                    scope: "full"
                    profileIds: []
                    permission: "read-write"
                  - id: "6507a1b2c3d4e5f6a7b8c9d1"
                    name: "Analytics Read-Only"
                    keyPreview: "sk_87654321...12345678"
                    expiresAt: null
                    createdAt: "2024-03-20T14:45:00Z"
                    scope: "profiles"
                    profileIds:
                      - _id: "6507a1b2c3d4e5f6a7b8c9d0"
                        name: "Main Brand"
                        color: "#ffeda0"
                    permission: "read"
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      operationId: createApiKey
      tags: [API Keys]
      summary: Create key
      description: Creates a new API key with an optional expiry. The full key value is only returned once in the response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
                expiresIn:
                  type: integer
                  description: Days until expiry
                scope:
                  type: string
                  enum: [full, profiles]
                  description: "'full' grants access to all profiles (default), 'profiles' restricts to specific profiles"
                  default: full
                profileIds:
                  type: array
                  items: { type: string }
                  description: Profile IDs this key can access. Required when scope is 'profiles'.
                permission:
                  type: string
                  enum: [read-write, read]
                  description: "'read-write' allows all operations (default), 'read' restricts to GET requests only"
                  default: read-write
            example:
              name: "Analytics Read-Only Key"
              scope: "profiles"
              profileIds: ["6507a1b2c3d4e5f6a7b8c9d0"]
              permission: "read"
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  apiKey: { $ref: '#/components/schemas/ApiKey' }
              example:
                message: "API key created successfully"
                apiKey:
                  id: "6507a1b2c3d4e5f6a7b8c9d0"
                  name: "Analytics Read-Only Key"
                  keyPreview: "sk_12345678...90abcdef"
                  key: "sk_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
                  expiresAt: null
                  createdAt: "2024-01-15T10:30:00Z"
                  scope: "profiles"
                  profileIds:
                    - _id: "6507a1b2c3d4e5f6a7b8c9d0"
                      name: "Main Brand"
                      color: "#ffeda0"
                  permission: "read"
        '400': { description: Invalid request (missing name, invalid scope/permission, or missing profileIds when scope is 'profiles') }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /v1/api-keys/{keyId}:
    delete:
      operationId: deleteApiKey
      tags: [API Keys]
      summary: Delete key
      description: Permanently revokes and deletes an API key.
      parameters:
        - name: keyId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
              example:
                message: "API key deleted successfully"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/invite/tokens:
    post:
      operationId: createInviteToken
      tags: [Invites]
      summary: Create invite token
      description: |
        Generate a secure invite link to grant team members access to your profiles.
        Invites expire after 7 days and are single-use.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [scope]
              properties:
                scope:
                  type: string
                  enum: [all, profiles]
                  description: "'all' grants access to all profiles, 'profiles' restricts to specific profiles"
                profileIds:
                  type: array
                  items: { type: string }
                  description: Required if scope is 'profiles'. Array of profile IDs to grant access to.
            example:
              scope: "profiles"
              profileIds:
                - "64f0a1b2c3d4e5f6a7b8c9d0"
                - "64f0a1b2c3d4e5f6a7b8c9d1"
      responses:
        '201':
          description: Invite token created
          content:
            application/json:
              schema:
                type: object
                properties:
                  token: { type: string }
                  scope: { type: string }
                  invitedProfileIds:
                    type: array
                    items: { type: string }
                  expiresAt: { type: string, format: date-time }
                  inviteUrl: { type: string, format: uri }
              example:
                token: "inv_abc123def456ghi789"
                scope: "profiles"
                invitedProfileIds:
                  - "64f0a1b2c3d4e5f6a7b8c9d0"
                  - "64f0a1b2c3d4e5f6a7b8c9d1"
                expiresAt: "2024-11-08T10:30:00Z"
                inviteUrl: "https://zernio.com/invite/inv_abc123def456ghi789"
        '400': { description: Invalid request }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { description: One or more profiles not found or not owned }

  /v1/connect/{platform}:
    get:
      operationId: getConnectUrl
      tags: [Connect]
      summary: Get OAuth connect URL
      description: |
        Initiate an OAuth connection flow. Returns an authUrl to redirect the user to.
        Standard flow: Zernio hosts the selection UI, then redirects to your redirect_url. Headless mode (headless=true): user is redirected to your redirect_url with OAuth data for custom UI. Use the platform-specific selection endpoints to complete.
      parameters:
        - name: platform
          in: path
          required: true
          schema:
            type: string
            enum: [facebook, instagram, linkedin, twitter, tiktok, youtube, threads, reddit, pinterest, bluesky, googlebusiness, telegram, snapchat]
          description: Social media platform to connect
        - name: profileId
          in: query
          required: true
          schema: { type: string }
          description: Your Zernio profile ID (get from /v1/profiles)
        - name: redirect_url
          in: query
          schema: { type: string, format: uri }
          description: Your custom redirect URL after connection completes. Standard mode appends ?connected={platform}&profileId=X&accountId=Y&username=Z. Headless mode appends OAuth data params for platforms requiring selection (e.g. LinkedIn orgs, Facebook pages). If no selection is needed, the account is created directly and the redirect includes accountId.
        - name: headless
          in: query
          schema: { type: boolean, default: false }
          description: When true, the user is redirected to your redirect_url with raw OAuth data (code, state) instead of Zernio's default account selection UI. Use this to build a custom connect experience.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: OAuth authorization URL to redirect user to
          content:
            application/json:
              schema:
                type: object
                properties:
                  authUrl: 
                    type: string
                    format: uri
                    description: URL to redirect your user to for OAuth authorization
                  state: 
                    type: string
                    description: State parameter for security (handled automatically)
              example:
                authUrl: "https://www.facebook.com/v21.0/dialog/oauth?client_id=..."
                state: "user123-profile456-1234567890-https://yourdomain.com/callback"
        '400':
          description: "Missing/invalid parameters (e.g., invalid profileId format)"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: "No access to profile, or BYOK required for AppSumo Twitter"
        '404':
          description: Profile not found
    post:
      operationId: handleOAuthCallback
      tags: [Connect]
      summary: Complete OAuth callback
      description: Exchange the OAuth authorization code for tokens and connect the account to the specified profile.
      parameters:
        - name: platform
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code, state, profileId]
              properties:
                code: { type: string }
                state: { type: string }
                profileId: { type: string }
      responses:
        '200': { description: Account connected }
        '400': { description: Invalid params }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { description: BYOK required for AppSumo Twitter }
        '500': { description: Failed to connect account }

  /v1/connect/{platform}/ads:
    get:
      operationId: connectAds
      tags: [Connect]
      summary: Connect ads for a platform
      description: |
        Unified ads connection endpoint. Handles all platforms through a single route:

        **Same-token platforms** (facebook, instagram, linkedin, pinterest): If a posting account already exists, returns `alreadyConnected: true` immediately (no extra OAuth needed). If not, starts the normal OAuth flow, and the resulting account supports both posting and ads.

        **Separate-token platforms** (tiktok, twitter): Requires an existing posting account (`accountId` param). If ads are already connected, returns `alreadyConnected: true`. Otherwise, starts the platform-specific marketing API OAuth flow.

        **Ads-only platforms** (googleads): If a Google Ads account exists, returns `alreadyConnected: true`. Otherwise, starts the Google Ads OAuth flow.

        Use the `adsStatus` field from `GET /v1/accounts` to check which accounts need ads connection.
      parameters:
        - name: platform
          in: path
          required: true
          schema:
            type: string
            enum: [facebook, instagram, linkedin, tiktok, twitter, pinterest, googleads]
          description: Platform to connect ads for. Only platforms with ads support are accepted.
        - name: profileId
          in: query
          required: true
          schema: { type: string }
          description: Your Zernio profile ID
        - name: accountId
          in: query
          schema: { type: string }
          description: Existing SocialAccount ID. Required for separate-token platforms (tiktok, twitter). Ignored for same-token and ads-only platforms.
        - name: redirect_url
          in: query
          schema: { type: string, format: uri }
          description: Custom redirect URL after OAuth completes (same-token platforms only)
        - name: headless
          in: query
          schema: { type: boolean, default: false }
          description: Enable headless mode (same-token platforms only)
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Either an OAuth URL to redirect to, or confirmation that ads are already connected
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    description: Ads already connected (no OAuth needed)
                    properties:
                      alreadyConnected: { type: boolean, example: true }
                      accountId: { type: string }
                      platform: { type: string }
                      username: { type: string }
                      displayName: { type: string }
                  - type: object
                    description: OAuth URL to redirect user to
                    properties:
                      authUrl: { type: string, format: uri }
                      state: { type: string }
              examples:
                alreadyConnected:
                  summary: Same-token platform (Meta) with existing account
                  value:
                    alreadyConnected: true
                    accountId: "664a1b2c3d4e5f6789012345"
                    platform: "instagram"
                    username: "@mybrand"
                    displayName: "My Brand"
                oauthRequired:
                  summary: Separate-token platform (TikTok) needing ads OAuth
                  value:
                    authUrl: "https://business-api.tiktok.com/portal/auth?app_id=..."
                    state: "user123-profile456-account789-1234567890"
        '400':
          description: "Platform doesn't support ads, or missing accountId for separate-token platform"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: "Ads add-on required, or no access to profile"
        '404':
          description: "Profile or posting account not found"

  /v1/connect/facebook/select-page:
    get:
      operationId: listFacebookPages
      tags: [Connect]
      summary: List Facebook pages
      description: Returns the list of Facebook Pages the user can manage after OAuth. Extract tempToken and userProfile from the OAuth redirect params and pass them here. Use the X-Connect-Token header if connecting via API key.
      parameters:
        - name: profileId
          in: query
          required: true
          schema: { type: string }
          description: Profile ID from your connection flow
        - name: tempToken
          in: query
          required: true
          schema: { type: string }
          description: Temporary Facebook access token from the OAuth callback redirect
      security:
        - bearerAuth: []
        - connectToken: []
      responses:
        '200':
          description: List of Facebook Pages available for connection
          content:
            application/json:
              schema:
                type: object
                properties:
                  pages:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, description: Facebook Page ID }
                        name: { type: string, description: Page name }
                        username: { type: string, description: Page username/handle (may be null) }
                        access_token: { type: string, description: Page-specific access token }
                        category: { type: string, description: Page category }
                        tasks: { type: array, items: { type: string }, description: User permissions for this page }
              example:
                pages:
                  - id: "123456789"
                    name: "My Brand Page"
                    username: "mybrand"
                    access_token: "EAAxxxxx..."
                    category: "Brand"
                    tasks: ["MANAGE", "CREATE_CONTENT"]
        '400': { description: Missing required parameters (profileId or tempToken) }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '500': 
          description: Failed to fetch pages (e.g., invalid token, insufficient permissions)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
    post:
      operationId: selectFacebookPage
      tags: [Connect]
      summary: Select Facebook page
      description: Complete the headless flow by saving the user's selected Facebook page. Pass the userProfile from the OAuth redirect and use X-Connect-Token if connecting via API key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [profileId, pageId, tempToken]
              properties:
                profileId: 
                  type: string
                  description: Profile ID from your connection flow
                pageId: 
                  type: string
                  description: The Facebook Page ID selected by the user
                tempToken: 
                  type: string
                  description: Temporary Facebook access token from OAuth
                userProfile: 
                  type: object
                  description: Decoded user profile object from the OAuth callback
                  properties:
                    id: { type: string }
                    name: { type: string }
                    profilePicture: { type: string }
                redirect_url: 
                  type: string
                  format: uri
                  description: Optional custom redirect URL to return to after selection
            example:
              profileId: "507f1f77bcf86cd799439011"
              pageId: "123456789"
              tempToken: "EAAxxxxx..."
              userProfile:
                id: "987654321"
                name: "John Doe"
                profilePicture: "https://..."
              redirect_url: "https://yourdomain.com/integrations/callback"
      security:
        - bearerAuth: []
        - connectToken: []
      responses:
        '200': 
          description: Facebook Page connected successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  redirect_url: 
                    type: string
                    description: Redirect URL if custom redirect_url was provided
                  account:
                    type: object
                    properties:
                      accountId:
                        type: string
                        description: ID of the created SocialAccount
                      platform: { type: string, enum: [facebook] }
                      username: { type: string }
                      displayName: { type: string }
                      profilePicture: { type: string }
                      isActive: { type: boolean }
                      selectedPageName: { type: string }
              example:
                message: "Facebook page connected successfully"
                redirect_url: "https://yourdomain.com/integrations/callback?connected=facebook&profileId=507f1f77bcf86cd799439011&username=My+Brand+Page"
                account:
                  accountId: "64e1f0a9e2b5af0012ab34cd"
                  platform: "facebook"
                  username: "mybrand"
                  displayName: "My Brand Page"
                  profilePicture: "https://..."
                  isActive: true
                  selectedPageName: "My Brand Page"
        '400':
          description: "Missing required fields (profileId, pageId, or tempToken)"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: User does not have access to the specified profile
        '404':
          description: Selected page not found in available pages
        '500':
          description: Failed to save Facebook connection

  /v1/connect/googlebusiness/locations:
    get:
      operationId: listGoogleBusinessLocations
      tags: [Connect]
      summary: List GBP locations
      description: >
        For headless flows. Returns the list of GBP locations the user can manage.
        Use pendingDataToken (from the OAuth callback redirect) to list locations
        without consuming the token, so it remains available for select-location.
        Use X-Connect-Token header if connecting via API key.
      parameters:
        - name: profileId
          in: query
          required: false
          schema: { type: string }
          description: Profile ID from your connection flow. Required for auth validation when provided.
        - name: pendingDataToken
          in: query
          required: false
          schema: { type: string }
          description: Token from the OAuth callback redirect. Preferred over tempToken because it preserves server-side token storage. One of pendingDataToken or tempToken is required.
        - name: tempToken
          in: query
          required: false
          schema: { type: string }
          description: Legacy. Direct Google access token. Use pendingDataToken instead when available.
      security:
        - bearerAuth: []
        - connectToken: []
      responses:
        '200':
          description: List of Google Business locations available for connection
          content:
            application/json:
              schema:
                type: object
                properties:
                  locations:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, description: Location ID }
                        name: { type: string, description: Business name }
                        accountId: { type: string, description: Google Business Account ID }
                        accountName: { type: string, description: Account name }
                        address: { type: string, description: Business address }
                        category: { type: string, description: Business category }
              example:
                locations:
                  - id: "9281089117903930794"
                    name: "My Coffee Shop"
                    accountId: "accounts/113303573364907650416"
                    accountName: "My Business Account"
                    address: "123 Main St, City, Country"
                    category: "Coffee shop"
        '400': { description: Missing required parameters (profileId or tempToken) }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '500': 
          description: Failed to fetch locations (e.g., invalid token, insufficient permissions)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }

  /v1/connect/googlebusiness/select-location:
    post:
      operationId: selectGoogleBusinessLocation
      tags: [Connect]
      summary: Select GBP location
      description: >
        Complete the headless GBP flow by saving the user's selected location.
        The pendingDataToken is returned in your redirect URL after OAuth completes
        (step=select_location). Tokens and profile data are stored server-side,
        so only the pendingDataToken is needed here. Use X-Connect-Token header
        if connecting via API key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [profileId, locationId, pendingDataToken]
              properties:
                profileId:
                  type: string
                  description: Profile ID from your connection flow
                locationId:
                  type: string
                  description: The Google Business location ID selected by the user
                pendingDataToken:
                  type: string
                  description: Token from the OAuth callback redirect (pendingDataToken query param). Tokens and profile data are retrieved server-side from this token.
                redirect_url:
                  type: string
                  format: uri
                  description: Optional custom redirect URL to return to after selection
            example:
              profileId: "507f1f77bcf86cd799439011"
              locationId: "9281089117903930794"
              pendingDataToken: "a1b2c3d4e5f6..."
              redirect_url: "https://yourdomain.com/integrations/callback"
      security:
        - bearerAuth: []
        - connectToken: []
      responses:
        '200': 
          description: Google Business location connected successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  redirect_url: 
                    type: string
                    description: Redirect URL if custom redirect_url was provided
                  account:
                    type: object
                    properties:
                      accountId:
                        type: string
                        description: ID of the created SocialAccount
                      platform: { type: string, enum: [googlebusiness] }
                      username: { type: string }
                      displayName: { type: string }
                      isActive: { type: boolean }
                      selectedLocationName: { type: string }
                      selectedLocationId: { type: string }
              example:
                message: "Google Business location connected successfully"
                redirect_url: "https://yourdomain.com/integrations/callback?connected=googlebusiness&profileId=507f1f77bcf86cd799439011&username=My+Coffee+Shop"
                account:
                  accountId: "64e1f0a9e2b5af0012ab34cd"
                  platform: "googlebusiness"
                  username: "My Coffee Shop"
                  displayName: "My Coffee Shop"
                  isActive: true
                  selectedLocationName: "My Coffee Shop"
                  selectedLocationId: "9281089117903930794"
        '400':
          description: "Missing required fields (profileId, locationId, or tempToken)"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: User does not have access to the specified profile
        '404':
          description: Selected location not found in available locations
        '500':
          description: Failed to save Google Business connection

  /v1/accounts/{accountId}/gmb-reviews:
    get:
      operationId: getGoogleBusinessReviews
      tags: [GMB Reviews]
      summary: Get reviews
      description: Returns reviews for a GBP account including ratings, comments, and owner replies. Use nextPageToken for pagination.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
          description: The Zernio account ID (from /v1/accounts)
        - name: locationId
          in: query
          schema: { type: string }
          description: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
        - name: pageSize
          in: query
          schema: { type: integer, minimum: 1, maximum: 50, default: 50 }
          description: Number of reviews to fetch per page (max 50)
        - name: pageToken
          in: query
          schema: { type: string }
          description: Pagination token from previous response
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Reviews fetched successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  accountId: { type: string }
                  locationId: { type: string }
                  reviews:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, description: Review ID }
                        name: { type: string, description: Full resource name }
                        reviewer:
                          type: object
                          properties:
                            displayName: { type: string }
                            profilePhotoUrl: { type: string, nullable: true }
                            isAnonymous: { type: boolean }
                        rating: { type: integer, minimum: 1, maximum: 5, description: Numeric star rating }
                        starRating: { type: string, enum: [ONE, TWO, THREE, FOUR, FIVE], description: Google's string rating }
                        comment: { type: string, description: Review text }
                        createTime: { type: string, format: date-time }
                        updateTime: { type: string, format: date-time }
                        reviewReply:
                          type: object
                          nullable: true
                          properties:
                            comment: { type: string, description: Business owner reply }
                            updateTime: { type: string, format: date-time }
                  averageRating: { type: number, description: Overall average rating }
                  totalReviewCount: { type: integer, description: Total number of reviews }
                  nextPageToken: { type: string, nullable: true, description: Token for next page }
              example:
                success: true
                accountId: "64e1f0a9e2b5af0012ab34cd"
                locationId: "9281089117903930794"
                reviews:
                  - id: "AIe9_BGx1234567890"
                    name: "accounts/123456789/locations/9281089117903930794/reviews/AIe9_BGx1234567890"
                    reviewer:
                      displayName: "John Smith"
                      profilePhotoUrl: "https://lh3.googleusercontent.com/a/..."
                      isAnonymous: false
                    rating: 5
                    starRating: "FIVE"
                    comment: "Great service and friendly staff! Highly recommend."
                    createTime: "2024-01-15T10:30:00Z"
                    updateTime: "2024-01-15T10:30:00Z"
                    reviewReply:
                      comment: "Thank you for your kind words! We appreciate your support."
                      updateTime: "2024-01-16T08:00:00Z"
                  - id: "AIe9_BGx0987654321"
                    name: "accounts/123456789/locations/9281089117903930794/reviews/AIe9_BGx0987654321"
                    reviewer:
                      displayName: "Anonymous"
                      profilePhotoUrl: null
                      isAnonymous: true
                    rating: 4
                    starRating: "FOUR"
                    comment: "Good experience overall."
                    createTime: "2024-01-10T14:20:00Z"
                    updateTime: "2024-01-10T14:20:00Z"
                    reviewReply: null
                averageRating: 4.5
                totalReviewCount: 125
                nextPageToken: "CiAKHAoUMTIzNDU2Nzg5"
        '400':
          description: Invalid request - not a Google Business account or missing location
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
              example:
                error: "This endpoint is only available for Google Business Profile accounts"
        '401':
          description: Unauthorized or token invalid
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
              example:
                error: "Access token invalid. Please reconnect your Google Business Profile account."
                code: "token_invalid"
        '403':
          description: Permission denied for this location
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
              example:
                error: "You do not have permission to access reviews for this location."
        '404': { $ref: '#/components/responses/NotFound' }
        '500':
          description: Failed to fetch reviews
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }

  /v1/accounts/{accountId}/gmb-food-menus:
    get:
      operationId: getGoogleBusinessFoodMenus
      tags: [GMB Food Menus]
      summary: Get food menus
      description: Returns food menus for a GBP location including sections, items, pricing, and dietary info. Only for locations with food menu support.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
          description: The Zernio account ID (from /v1/accounts)
        - name: locationId
          in: query
          schema: { type: string }
          description: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Food menus fetched successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  accountId: { type: string }
                  locationId: { type: string }
                  name: { type: string, description: Resource name of the food menus }
                  menus:
                    type: array
                    items:
                      $ref: '#/components/schemas/FoodMenu'
              example:
                success: true
                accountId: "64e1f0a9e2b5af0012ab34cd"
                locationId: "9281089117903930794"
                name: "accounts/123456789/locations/9281089117903930794/foodMenus"
                menus:
                  - labels:
                      - displayName: "Lunch Menu"
                        description: "Available 11am-3pm"
                        languageCode: "en"
                    sections:
                      - labels:
                          - displayName: "Appetizers"
                        items:
                          - labels:
                              - displayName: "Caesar Salad"
                                description: "Romaine, parmesan, croutons"
                            attributes:
                              price:
                                currencyCode: "USD"
                                units: "12"
                              dietaryRestriction: ["VEGETARIAN"]
        '400':
          description: Invalid request - not a Google Business account or missing location
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
              example:
                error: "This endpoint is only available for Google Business Profile accounts"
        '401':
          description: Unauthorized or token invalid
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
              example:
                error: "Access token invalid. Please reconnect your Google Business Profile account."
                code: "token_invalid"
        '403':
          description: Permission denied for this location
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
              example:
                error: "You do not have permission to access food menus for this location."
        '404': { $ref: '#/components/responses/NotFound' }
        '500':
          description: Failed to fetch food menus
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
    put:
      operationId: updateGoogleBusinessFoodMenus
      tags: [GMB Food Menus]
      summary: Update food menus
      description: Updates food menus for a GBP location. Send the full menus array. Use updateMask for partial updates.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
          description: The Zernio account ID (from /v1/accounts)
        - name: locationId
          in: query
          schema: { type: string }
          description: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [menus]
              properties:
                menus:
                  type: array
                  items:
                    $ref: '#/components/schemas/FoodMenu'
                  description: Array of food menus to set
                updateMask:
                  type: string
                  description: Field mask for partial updates (e.g. "menus")
            example:
              menus:
                - labels:
                    - displayName: "Dinner Menu"
                      languageCode: "en"
                  sections:
                    - labels:
                        - displayName: "Mains"
                      items:
                        - labels:
                            - displayName: "Grilled Salmon"
                              description: "With seasonal vegetables"
                          attributes:
                            price:
                              currencyCode: "USD"
                              units: "24"
                            allergen: ["FISH"]
              updateMask: "menus"
      responses:
        '200':
          description: Food menus updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  accountId: { type: string }
                  locationId: { type: string }
                  name: { type: string }
                  menus:
                    type: array
                    items:
                      $ref: '#/components/schemas/FoodMenu'
        '400':
          description: Invalid request
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
              example:
                error: "Request body must include a \"menus\" array"
        '401':
          description: Unauthorized or token expired
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '403':
          description: Permission denied for this location
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '404': { $ref: '#/components/responses/NotFound' }
        '500':
          description: Failed to update food menus
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }

  /v1/accounts/{accountId}/gmb-location-details:
    get:
      operationId: getGoogleBusinessLocationDetails
      tags: [GMB Location Details]
      summary: Get location details
      description: Returns detailed GBP location info (hours, description, phone, website, categories, services). Use readMask to request specific fields.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
          description: The Zernio account ID (from /v1/accounts)
        - name: locationId
          in: query
          schema: { type: string }
          description: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
        - name: readMask
          in: query
          required: false
          schema: { type: string }
          description: "Comma-separated fields to return. Available: name, title, phoneNumbers, categories, storefrontAddress, websiteUri, regularHours, specialHours, serviceArea, serviceItems, profile, openInfo, metadata, moreHours."
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Location details fetched successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  accountId: { type: string }
                  locationId: { type: string }
                  title: { type: string, description: Business name }
                  regularHours:
                    type: object
                    properties:
                      periods:
                        type: array
                        items:
                          type: object
                          properties:
                            openDay: { type: string, enum: [MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY] }
                            openTime: { type: string, description: "Opening time in HH:MM format" }
                            closeDay: { type: string }
                            closeTime: { type: string }
                  specialHours:
                    type: object
                    properties:
                      specialHourPeriods:
                        type: array
                        items:
                          type: object
                          properties:
                            startDate: { type: object, properties: { year: { type: integer }, month: { type: integer }, day: { type: integer } } }
                            endDate: { type: object, properties: { year: { type: integer }, month: { type: integer }, day: { type: integer } } }
                            openTime: { type: string }
                            closeTime: { type: string }
                            closed: { type: boolean }
                  profile:
                    type: object
                    properties:
                      description: { type: string, description: Business description }
                  websiteUri: { type: string }
                  phoneNumbers:
                    type: object
                    properties:
                      primaryPhone: { type: string }
                      additionalPhones: { type: array, items: { type: string } }
                  categories:
                    type: object
                    description: "Business categories (returned when readMask includes 'categories')"
                    properties:
                      primaryCategory:
                        type: object
                        properties:
                          name: { type: string, description: "Category resource name" }
                          displayName: { type: string, description: "Human-readable category name" }
                      additionalCategories:
                        type: array
                        items:
                          type: object
                          properties:
                            name: { type: string }
                            displayName: { type: string }
                  serviceItems:
                    type: array
                    description: "Services offered (returned when readMask includes 'serviceItems')"
                    items:
                      type: object
                      properties:
                        structuredServiceItem:
                          type: object
                          properties:
                            serviceTypeId: { type: string }
                            description: { type: string }
                        freeFormServiceItem:
                          type: object
                          properties:
                            category: { type: string }
                            label:
                              type: object
                              properties:
                                displayName: { type: string }
                                languageCode: { type: string }
                        price:
                          type: object
                          properties:
                            currencyCode: { type: string }
                            units: { type: string }
                            nanos: { type: integer }
              example:
                success: true
                accountId: "64e1f0a9e2b5af0012ab34cd"
                locationId: "9281089117903930794"
                title: "Joe's Pizza"
                regularHours:
                  periods:
                    - openDay: "MONDAY"
                      openTime: "11:00"
                      closeDay: "MONDAY"
                      closeTime: "22:00"
                    - openDay: "TUESDAY"
                      openTime: "11:00"
                      closeDay: "TUESDAY"
                      closeTime: "22:00"
                specialHours:
                  specialHourPeriods:
                    - startDate: { year: 2026, month: 12, day: 25 }
                      closed: true
                profile:
                  description: "Authentic New York style pizza since 1985"
                websiteUri: "https://joespizza.com"
                categories:
                  primaryCategory:
                    name: "categories/gcid:pizza_restaurant"
                    displayName: "Pizza restaurant"
                  additionalCategories:
                    - name: "categories/gcid:italian_restaurant"
                      displayName: "Italian restaurant"
        '400':
          description: Invalid request
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '401':
          description: Unauthorized or token expired
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '404': { $ref: '#/components/responses/NotFound' }
    put:
      operationId: updateGoogleBusinessLocationDetails
      tags: [GMB Location Details]
      summary: Update location details
      description: |
        Updates GBP location details. The updateMask field is required and specifies which fields to update.
        This endpoint proxies Google's Business Information API locations.patch, so any valid updateMask field is supported.
        Common fields: regularHours, specialHours, profile.description, websiteUri, phoneNumbers, categories, serviceItems.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
          description: The Zernio account ID (from /v1/accounts)
        - name: locationId
          in: query
          schema: { type: string }
          description: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [updateMask]
              properties:
                updateMask:
                  type: string
                  description: "Required. Comma-separated fields to update (e.g. 'regularHours', 'specialHours', 'profile.description', 'categories', 'serviceItems'). Any valid Google Business Information API updateMask field is supported."
                regularHours:
                  type: object
                  properties:
                    periods:
                      type: array
                      items:
                        type: object
                        properties:
                          openDay: { type: string }
                          openTime: { type: string }
                          closeDay: { type: string }
                          closeTime: { type: string }
                specialHours:
                  type: object
                  properties:
                    specialHourPeriods:
                      type: array
                      items:
                        type: object
                        properties:
                          startDate: { type: object, properties: { year: { type: integer }, month: { type: integer }, day: { type: integer } } }
                          endDate: { type: object, properties: { year: { type: integer }, month: { type: integer }, day: { type: integer } } }
                          openTime: { type: string }
                          closeTime: { type: string }
                          closed: { type: boolean }
                profile:
                  type: object
                  properties:
                    description: { type: string }
                websiteUri: { type: string }
                phoneNumbers:
                  type: object
                  properties:
                    primaryPhone: { type: string }
                    additionalPhones: { type: array, items: { type: string } }
                categories:
                  type: object
                  description: "Primary and additional business categories. Use updateMask='categories' to update."
                  properties:
                    primaryCategory:
                      type: object
                      properties:
                        name:
                          type: string
                          description: "Category resource name (e.g. 'categories/gcid:laundromat'). Use Google's Categories API to look up valid IDs."
                    additionalCategories:
                      type: array
                      items:
                        type: object
                        properties:
                          name:
                            type: string
                            description: "Category resource name (e.g. 'categories/gcid:dry_cleaner')"
                serviceItems:
                  type: array
                  description: "Services offered by the business. Use updateMask='serviceItems' to update."
                  items:
                    type: object
                    properties:
                      structuredServiceItem:
                        type: object
                        description: "A predefined service from Google's service type catalog"
                        properties:
                          serviceTypeId:
                            type: string
                            description: "Service type ID from Google's catalog (e.g. 'job_type_id:plumbing_drain_repair')"
                          description:
                            type: string
                            description: "Optional description of the service"
                      freeFormServiceItem:
                        type: object
                        description: "A custom service not in Google's catalog"
                        properties:
                          category:
                            type: string
                            description: "Category resource name this service belongs to (e.g. 'categories/gcid:laundromat')"
                          label:
                            type: object
                            properties:
                              displayName:
                                type: string
                                description: "Service name as displayed to users"
                              languageCode:
                                type: string
                                description: "Language code (e.g. 'en')"
                      price:
                        type: object
                        description: "Optional price for the service"
                        properties:
                          currencyCode: { type: string, description: "ISO 4217 currency code (e.g. 'USD')" }
                          units: { type: string, description: "Whole units of the amount" }
                          nanos: { type: integer, description: "Nano units (10^-9) of the amount" }
            examples:
              updateHours:
                summary: Update business hours
                value:
                  updateMask: "regularHours,specialHours"
                  regularHours:
                    periods:
                      - openDay: "MONDAY"
                        openTime: "09:00"
                        closeDay: "MONDAY"
                        closeTime: "17:00"
                      - openDay: "SATURDAY"
                        openTime: "10:00"
                        closeDay: "SATURDAY"
                        closeTime: "14:00"
                  specialHours:
                    specialHourPeriods:
                      - startDate: { year: 2026, month: 12, day: 25 }
                        closed: true
                      - startDate: { year: 2026, month: 12, day: 31 }
                        openTime: "09:00"
                        closeTime: "15:00"
              updateCategories:
                summary: Update business categories
                value:
                  updateMask: "categories"
                  categories:
                    primaryCategory:
                      name: "categories/gcid:laundromat"
                    additionalCategories:
                      - name: "categories/gcid:dry_cleaner"
                      - name: "categories/gcid:laundry_service"
              updateServices:
                summary: Update service items
                value:
                  updateMask: "serviceItems"
                  serviceItems:
                    - structuredServiceItem:
                        serviceTypeId: "job_type_id:plumbing_drain_repair"
                        description: "Full drain cleaning and repair service"
                    - freeFormServiceItem:
                        category: "categories/gcid:laundromat"
                        label:
                          displayName: "Wash & Fold Service"
                          languageCode: "en"
                      price:
                        currencyCode: "USD"
                        units: "25"
      responses:
        '200':
          description: Location updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  accountId: { type: string }
                  locationId: { type: string }
        '400':
          description: Invalid request or missing updateMask
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '401':
          description: Unauthorized or token expired
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/accounts/{accountId}/gmb-media:
    get:
      operationId: listGoogleBusinessMedia
      tags: [GMB Media]
      summary: List media
      description: |
        Lists media items (photos) for a Google Business Profile location.
        Returns photo URLs, descriptions, categories, and metadata.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
        - name: locationId
          in: query
          schema: { type: string }
          description: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
        - name: pageSize
          in: query
          schema: { type: integer, maximum: 100, default: 100 }
          description: Number of items to return (max 100)
        - name: pageToken
          in: query
          schema: { type: string }
          description: Pagination token from previous response
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Media items fetched successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  accountId: { type: string }
                  locationId: { type: string }
                  mediaItems:
                    type: array
                    items:
                      type: object
                      properties:
                        name: { type: string, description: Resource name }
                        mediaFormat: { type: string, enum: [PHOTO, VIDEO] }
                        sourceUrl: { type: string }
                        googleUrl: { type: string, description: Google-hosted URL }
                        thumbnailUrl: { type: string }
                        description: { type: string }
                        createTime: { type: string, format: date-time }
                        locationAssociation:
                          type: object
                          properties:
                            category: { type: string }
                  nextPageToken: { type: string }
                  totalMediaItemsCount: { type: integer }
        '400':
          description: Invalid request
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
    post:
      operationId: createGoogleBusinessMedia
      tags: [GMB Media]
      summary: Upload photo
      description: |
        Creates a media item (photo) for a location from a publicly accessible URL.

        Categories determine where the photo appears: COVER, PROFILE, LOGO, EXTERIOR, INTERIOR, FOOD_AND_DRINK, MENU, PRODUCT, TEAMS, ADDITIONAL.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
        - name: locationId
          in: query
          schema: { type: string }
          description: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [sourceUrl]
              properties:
                sourceUrl: { type: string, description: Publicly accessible image URL }
                mediaFormat: { type: string, enum: [PHOTO, VIDEO], default: PHOTO }
                description: { type: string, description: Photo description }
                category:
                  type: string
                  enum: [COVER, PROFILE, LOGO, EXTERIOR, INTERIOR, FOOD_AND_DRINK, MENU, PRODUCT, TEAMS, ADDITIONAL]
                  description: Where the photo appears on the listing
            example:
              sourceUrl: "https://example.com/photos/restaurant-interior.jpg"
              description: "Dining area with outdoor seating"
              category: "INTERIOR"
      responses:
        '200':
          description: Media created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  name: { type: string }
                  mediaFormat: { type: string }
                  googleUrl: { type: string }
        '400':
          description: Invalid request or unsupported media format
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
    delete:
      operationId: deleteGoogleBusinessMedia
      tags: [GMB Media]
      summary: Delete photo
      description: Deletes a photo or media item from a GBP location.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
        - name: locationId
          in: query
          schema: { type: string }
          description: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
        - name: mediaId
          in: query
          required: true
          schema: { type: string }
          description: The media item ID to delete
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Media deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  deleted: { type: boolean }
                  mediaId: { type: string }
        '400':
          description: Invalid request
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }

  /v1/accounts/{accountId}/gmb-attributes:
    get:
      operationId: getGoogleBusinessAttributes
      tags: [GMB Attributes]
      summary: Get attributes
      description: Returns GBP location attributes (amenities, services, accessibility, payment types). Available attributes vary by business category.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
        - name: locationId
          in: query
          schema: { type: string }
          description: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Attributes fetched successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  accountId: { type: string }
                  locationId: { type: string }
                  attributes:
                    type: array
                    items:
                      type: object
                      properties:
                        name: { type: string, description: "Attribute identifier (e.g. has_delivery)" }
                        valueType: { type: string, description: "Value type (BOOL, ENUM, URL, REPEATED_ENUM)" }
                        values: { type: array, items: {} }
                        repeatedEnumValue:
                          type: object
                          properties:
                            setValues: { type: array, items: { type: string } }
                            unsetValues: { type: array, items: { type: string } }
              example:
                success: true
                attributes:
                  - name: "has_delivery"
                    valueType: "BOOL"
                    values: [true]
                  - name: "has_takeout"
                    valueType: "BOOL"
                    values: [true]
                  - name: "has_outdoor_seating"
                    valueType: "BOOL"
                    values: [true]
                  - name: "pay_credit_card_types_accepted"
                    valueType: "REPEATED_ENUM"
                    repeatedEnumValue:
                      setValues: ["visa", "mastercard", "amex"]
        '400':
          description: Invalid request
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
    put:
      operationId: updateGoogleBusinessAttributes
      tags: [GMB Attributes]
      summary: Update attributes
      description: |
        Updates location attributes (amenities, services, etc.).

        The attributeMask specifies which attributes to update (comma-separated).
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
        - name: locationId
          in: query
          schema: { type: string }
          description: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [attributes, attributeMask]
              properties:
                attributes:
                  type: array
                  items:
                    type: object
                    properties:
                      name: { type: string }
                      values: { type: array, items: {} }
                      repeatedEnumValue:
                        type: object
                        properties:
                          setValues: { type: array, items: { type: string } }
                          unsetValues: { type: array, items: { type: string } }
                attributeMask:
                  type: string
                  description: "Comma-separated attribute names to update (e.g. 'has_delivery,has_takeout')"
            example:
              attributes:
                - name: "has_delivery"
                  values: [true]
                - name: "has_takeout"
                  values: [true]
                - name: "has_outdoor_seating"
                  values: [false]
              attributeMask: "has_delivery,has_takeout,has_outdoor_seating"
      responses:
        '200':
          description: Attributes updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  accountId: { type: string }
                  locationId: { type: string }
                  attributes: { type: array, items: { type: object } }
        '400':
          description: Invalid request
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }

  /v1/accounts/{accountId}/gmb-place-actions:
    get:
      operationId: listGoogleBusinessPlaceActions
      tags: [GMB Place Actions]
      summary: List action links
      description: |
        Lists place action links for a Google Business Profile location.

        Place actions are the booking, ordering, and reservation buttons that appear on your listing.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
        - name: locationId
          in: query
          schema: { type: string }
          description: Override which location to query. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
        - name: pageSize
          in: query
          schema: { type: integer, maximum: 100, default: 100 }
        - name: pageToken
          in: query
          schema: { type: string }
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Place actions fetched successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  accountId: { type: string }
                  locationId: { type: string }
                  placeActionLinks:
                    type: array
                    items:
                      type: object
                      properties:
                        name: { type: string, description: Resource name }
                        uri: { type: string, description: Action URL }
                        placeActionType: { type: string }
                        createTime: { type: string, format: date-time }
                        updateTime: { type: string, format: date-time }
                  nextPageToken: { type: string }
              example:
                success: true
                placeActionLinks:
                  - name: "locations/123/placeActionLinks/456"
                    uri: "https://order.ubereats.com/joespizza"
                    placeActionType: "FOOD_ORDERING"
                  - name: "locations/123/placeActionLinks/789"
                    uri: "https://www.opentable.com/joespizza"
                    placeActionType: "DINING_RESERVATION"
        '400':
          description: Invalid request
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
    post:
      operationId: createGoogleBusinessPlaceAction
      tags: [GMB Place Actions]
      summary: Create action link
      description: |
        Creates a place action link for a location.

        Available action types: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
        - name: locationId
          in: query
          schema: { type: string }
          description: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [uri, placeActionType]
              properties:
                uri: { type: string, description: The action URL }
                placeActionType:
                  type: string
                  enum: [APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE]
                  description: Type of action
            example:
              uri: "https://order.ubereats.com/joespizza"
              placeActionType: "FOOD_ORDERING"
      responses:
        '200':
          description: Place action created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  name: { type: string, description: Resource name of the created link }
                  uri: { type: string }
                  placeActionType: { type: string }
        '400':
          description: Invalid request
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
    delete:
      operationId: deleteGoogleBusinessPlaceAction
      tags: [GMB Place Actions]
      summary: Delete action link
      description: Deletes a place action link (e.g. booking or ordering URL) from a GBP location.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
        - name: locationId
          in: query
          schema: { type: string }
          description: Override which location to target. If omitted, uses the account's selected location. Use GET /gmb-locations to list valid IDs.
        - name: name
          in: query
          required: true
          schema: { type: string }
          description: "The resource name of the place action link (e.g. locations/123/placeActionLinks/456)"
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Place action deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  deleted: { type: boolean }
                  name: { type: string }
        '400':
          description: Invalid request
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }

  /v1/connect/pending-data:
    get:
      operationId: getPendingOAuthData
      tags: [Connect]
      summary: Get pending OAuth data
      description: Fetch pending OAuth data for headless mode using the pendingDataToken from the redirect URL. One-time use, expires after 10 minutes. No authentication required.
      parameters:
        - name: token
          in: query
          required: true
          schema: { type: string }
          description: The pending data token from the OAuth redirect URL (pendingDataToken parameter)
      responses:
        '200':
          description: OAuth data fetched successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  platform:
                    type: string
                    description: The platform (e.g., "linkedin")
                  profileId:
                    type: string
                    description: The Zernio profile ID
                  tempToken:
                    type: string
                    description: Temporary access token for the platform
                  refreshToken:
                    type: string
                    description: Refresh token (if available)
                  expiresIn:
                    type: number
                    description: Token expiry in seconds
                  userProfile:
                    type: object
                    description: User profile data (id, username, displayName, profilePicture)
                  selectionType:
                    type: string
                    enum: [organizations, pages, boards, locations, profiles]
                    description: Type of selection data
                  organizations:
                    type: array
                    description: LinkedIn organizations (when selectionType is "organizations")
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        urn: { type: string }
                        name: { type: string }
                        vanityName: { type: string }
              example:
                platform: "linkedin"
                profileId: "abc123"
                tempToken: "AQV..."
                refreshToken: "AQW..."
                expiresIn: 5183999
                userProfile:
                  id: "ABC123"
                  username: "John Doe"
                  displayName: "John Doe"
                  profilePicture: "https://..."
                selectionType: "organizations"
                organizations:
                  - id: "12345"
                    urn: "urn:li:organization:12345"
                    name: "Acme Corp"
                    vanityName: "acme-corp"
                  - id: "67890"
                    urn: "urn:li:organization:67890"
                    name: "Example Inc"
                    vanityName: "example-inc"
        '400':
          description: Missing token parameter
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }
        '404':
          description: Token not found or expired
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ErrorResponse' }

  /v1/connect/linkedin/organizations:
    get:
      operationId: listLinkedInOrganizations
      tags: [Connect]
      summary: List LinkedIn orgs
      description: Fetch full LinkedIn organization details (logos, vanity names, websites) for custom UI. No authentication required, just the tempToken from OAuth.
      parameters:
        - name: tempToken
          in: query
          required: true
          schema: { type: string }
          description: The temporary LinkedIn access token from the OAuth redirect
        - name: orgIds
          in: query
          required: true
          schema: { type: string }
          description: Comma-separated list of organization IDs to fetch details for (max 100)
          example: "12345678,87654321,11111111"
      responses:
        '200':
          description: Organization details fetched successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  organizations:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, description: Organization ID }
                        logoUrl: { type: string, format: uri, description: Logo URL (may be absent if no logo) }
                        vanityName: { type: string, description: Organization's vanity name/slug }
                        website: { type: string, format: uri, description: Organization's website URL }
                        industry: { type: string, description: Organization's primary industry }
                        description: { type: string, description: Organization's description }
              example:
                organizations:
                  - id: "12345678"
                    logoUrl: "https://media.licdn.com/dms/image/v2/..."
                    vanityName: "acme-corp"
                    website: "https://acme.com"
                    industry: "Technology"
                    description: "Leading provider of innovative solutions"
                  - id: "87654321"
                    logoUrl: "https://media.licdn.com/dms/image/v2/..."
                    vanityName: "example-inc"
                    website: "https://example.com"
                  - id: "11111111"
        '400':
          description: Missing required parameters or too many organization IDs
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
              example:
                error: "Missing tempToken parameter"
        '500':
          description: Failed to fetch organization details

  /v1/connect/linkedin/select-organization:
    post:
      operationId: selectLinkedInOrganization
      tags: [Connect]
      summary: Select LinkedIn org
      description: Complete the LinkedIn connection flow. Set accountType to "personal" or "organization" to connect as a company page. Use X-Connect-Token if connecting via API key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [profileId, tempToken, userProfile, accountType]
              properties:
                profileId: { type: string }
                tempToken: { type: string }
                userProfile: { type: object }
                accountType: { type: string, enum: [personal, organization] }
                selectedOrganization: { type: object }
                redirect_url: { type: string, format: uri }
            examples:
              personalAccount:
                summary: Connect as personal LinkedIn profile
                description: For personal accounts, set accountType to "personal" and omit selectedOrganization
                value:
                  profileId: "64f0a1b2c3d4e5f6a7b8c9d0"
                  tempToken: "AQX..."
                  userProfile:
                    id: "abc123"
                    username: "johndoe"
                    displayName: "John Doe"
                    profilePicture: "https://media.licdn.com/dms/image/v2/..."
                  accountType: "personal"
              organizationAccount:
                summary: Connect as org/company page
                description: For organization pages, include the selectedOrganization object
                value:
                  profileId: "64f0a1b2c3d4e5f6a7b8c9d0"
                  tempToken: "AQX..."
                  userProfile:
                    id: "abc123"
                    username: "johndoe"
                    displayName: "John Doe"
                    profilePicture: "https://media.licdn.com/dms/image/v2/..."
                  accountType: "organization"
                  selectedOrganization:
                    id: "12345678"
                    urn: "urn:li:organization:12345678"
                    name: "Acme Corporation"
                  redirect_url: "https://yourapp.com/callback"
      responses:
        '200':
          description: LinkedIn account connected
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  redirect_url:
                    type: string
                    description: The redirect URL with connection params appended (only if redirect_url was provided in request)
                  account:
                    type: object
                    properties:
                      accountId:
                        type: string
                        description: ID of the created SocialAccount
                      platform: { type: string, enum: [linkedin] }
                      username: { type: string }
                      displayName: { type: string }
                      profilePicture: { type: string }
                      isActive: { type: boolean }
                      accountType: { type: string, enum: [personal, organization] }
                  bulkRefresh:
                    type: object
                    properties:
                      updatedCount: { type: integer }
                      errors: { type: integer }
              examples:
                personalAccountResponse:
                  summary: Personal account connected
                  value:
                    message: "LinkedIn account connected successfully"
                    account:
                      accountId: "64e1f0a9e2b5af0012ab34cd"
                      platform: "linkedin"
                      username: "johndoe"
                      displayName: "John Doe"
                      profilePicture: "https://media.licdn.com/..."
                      isActive: true
                      accountType: "personal"
                organizationWithRedirect:
                  summary: Org account with redirect URL
                  value:
                    message: "LinkedIn account connected successfully"
                    redirect_url: "https://yourapp.com/callback?connected=linkedin&profileId=507f1f77bcf86cd799439011&accountId=64e1f0a9e2b5af0012ab34cd&username=Acme+Corporation"
                    account:
                      accountId: "64e1f0a9e2b5af0012ab34cd"
                      platform: "linkedin"
                      username: "acme-corp"
                      displayName: "Acme Corporation"
                      profilePicture: "https://media.licdn.com/..."
                      isActive: true
                      accountType: "organization"
                    bulkRefresh:
                      updatedCount: 5
                      errors: 0
        '400': { description: Missing required fields }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '500': { description: Failed to connect LinkedIn account }

  /v1/connect/pinterest/select-board:
    get:
      operationId: listPinterestBoardsForSelection
      tags: [Connect]
      summary: List Pinterest boards
      description: For headless flows. Returns Pinterest boards the user can post to. Use X-Connect-Token from the redirect URL.
      parameters:
        - name: X-Connect-Token
          in: header
          required: true
          schema: { type: string }
          description: Short-lived connect token from the OAuth redirect
        - name: profileId
          in: query
          required: true
          schema: { type: string }
          description: Your Zernio profile ID
        - name: tempToken
          in: query
          required: true
          schema: { type: string }
          description: Temporary Pinterest access token from the OAuth callback redirect
      responses:
        '200':
          description: List of Pinterest Boards available for connection
          content:
            application/json:
              schema:
                type: object
                properties:
                  boards:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, description: Pinterest Board ID }
                        name: { type: string, description: Board name }
                        description: { type: string, description: Board description }
                        privacy: { type: string, description: Board privacy setting }
              example:
                boards:
                  - id: "123456789012345678"
                    name: "Marketing Ideas"
                    description: "Collection of marketing inspiration"
                    privacy: "PUBLIC"
                  - id: "234567890123456789"
                    name: "Product Photos"
                    description: "Product photography"
                    privacy: "PUBLIC"
        '400': { description: Missing required parameters }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { description: No access to profile }
        '500': { description: Failed to fetch boards }
    post:
      operationId: selectPinterestBoard
      tags: [Connect]
      summary: Select Pinterest board
      description: |
        Complete the Pinterest connection flow. After OAuth, use this endpoint to save the selected board and complete the account connection. Use the X-Connect-Token header if you initiated the connection via API key.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [profileId, boardId, tempToken]
              properties:
                profileId:
                  type: string
                  description: Your Zernio profile ID
                boardId:
                  type: string
                  description: The Pinterest Board ID selected by the user
                boardName:
                  type: string
                  description: The board name (for display purposes)
                tempToken:
                  type: string
                  description: Temporary Pinterest access token from OAuth
                userProfile:
                  type: object
                  description: User profile data from OAuth redirect
                refreshToken:
                  type: string
                  description: Pinterest refresh token (if available)
                expiresIn:
                  type: integer
                  description: Token expiration time in seconds
                redirect_url:
                  type: string
                  format: uri
                  description: Custom redirect URL after connection completes
            example:
              profileId: "64f0a1b2c3d4e5f6a7b8c9d0"
              boardId: "123456789012345678"
              boardName: "Marketing Ideas"
              tempToken: "pina_..."
              userProfile:
                id: "user123"
                username: "mybrand"
                displayName: "My Brand"
                profilePicture: "https://i.pinimg.com/..."
              redirect_url: "https://yourapp.com/callback"
      responses:
        '200':
          description: Pinterest Board connected successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  redirect_url: { type: string, description: Redirect URL with connection params (if provided) }
                  account:
                    type: object
                    properties:
                      accountId:
                        type: string
                        description: ID of the created SocialAccount
                      platform: { type: string, enum: [pinterest] }
                      username: { type: string }
                      displayName: { type: string }
                      profilePicture: { type: string }
                      isActive: { type: boolean }
                      defaultBoardName: { type: string }
              example:
                message: "Pinterest connected successfully with default board"
                redirect_url: "https://yourdomain.com/integrations/callback?connected=pinterest&profileId=507f1f77bcf86cd799439011&board=Marketing+Ideas"
                account:
                  accountId: "64e1f0a9e2b5af0012ab34cd"
                  platform: "pinterest"
                  username: "mybrand"
                  displayName: "My Brand"
                  profilePicture: "https://i.pinimg.com/..."
                  isActive: true
                  defaultBoardName: "Marketing Ideas"
        '400':
          description: Missing required fields
          content:
            application/json:
              example:
                error: "Missing required fields"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: No access to profile or profile limit exceeded
          content:
            application/json:
              examples:
                forbidden:
                  value: { error: "Forbidden" }
                limitExceeded:
                  value:
                    error: "Cannot connect to this profile. It exceeds your Pro plan limit of 5 profiles."
                    code: "PROFILE_LIMIT_EXCEEDED"
        '500':
          description: Failed to save Pinterest connection

  /v1/connect/snapchat/select-profile:
    get:
      operationId: listSnapchatProfiles
      tags: [Connect]
      summary: List Snapchat profiles
      description: For headless flows. Returns Snapchat Public Profiles the user can post to. Use X-Connect-Token from the redirect URL.
      parameters:
        - name: X-Connect-Token
          in: header
          required: true
          schema: { type: string }
          description: Short-lived connect token from the OAuth redirect
        - name: profileId
          in: query
          required: true
          schema: { type: string }
          description: Your Zernio profile ID
        - name: tempToken
          in: query
          required: true
          schema: { type: string }
          description: Temporary Snapchat access token from the OAuth callback redirect
      responses:
        '200':
          description: List of Snapchat Public Profiles available for connection
          content:
            application/json:
              schema:
                type: object
                properties:
                  publicProfiles:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, description: Snapchat Public Profile ID }
                        display_name: { type: string, description: Public profile display name }
                        username: { type: string, description: Public profile username/handle }
                        profile_image_url: { type: string, description: Profile image URL }
                        subscriber_count: { type: integer, description: Number of subscribers }
              example:
                publicProfiles:
                  - id: "abc123-def456"
                    display_name: "My Brand"
                    username: "mybrand"
                    profile_image_url: "https://cf-st.sc-cdn.net/..."
                    subscriber_count: 15000
                  - id: "xyz789-uvw012"
                    display_name: "Side Project"
                    username: "sideproject"
                    profile_image_url: "https://cf-st.sc-cdn.net/..."
                    subscriber_count: 5000
        '400': { description: Missing required parameters (profileId or tempToken) }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { description: No access to profile }
        '500': { description: Failed to fetch public profiles }
    post:
      operationId: selectSnapchatProfile
      tags: [Connect]
      summary: Select Snapchat profile
      description: Complete the Snapchat connection flow by saving the selected Public Profile. Snapchat requires a Public Profile to publish content. Use X-Connect-Token if connecting via API key.
      parameters:
        - name: X-Connect-Token
          in: header
          required: false
          schema: { type: string }
          description: Short-lived connect token from the OAuth redirect (for API users)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [profileId, selectedPublicProfile, tempToken, userProfile]
              properties:
                profileId:
                  type: string
                  description: Your Zernio profile ID
                selectedPublicProfile:
                  type: object
                  description: The selected Snapchat Public Profile
                  required: [id, display_name]
                  properties:
                    id:
                      type: string
                      description: Snapchat Public Profile ID
                    display_name:
                      type: string
                      description: Display name of the public profile
                    username:
                      type: string
                      description: Username/handle
                    profile_image_url:
                      type: string
                      description: Profile image URL
                    subscriber_count:
                      type: integer
                      description: Number of subscribers
                tempToken:
                  type: string
                  description: Temporary Snapchat access token from OAuth
                userProfile:
                  type: object
                  description: User profile data from OAuth redirect
                refreshToken:
                  type: string
                  description: Snapchat refresh token (if available)
                expiresIn:
                  type: integer
                  description: Token expiration time in seconds
                redirect_url:
                  type: string
                  format: uri
                  description: Custom redirect URL after connection completes
            example:
              profileId: "64f0a1b2c3d4e5f6a7b8c9d0"
              selectedPublicProfile:
                id: "abc123-def456"
                display_name: "My Brand"
                username: "mybrand"
                profile_image_url: "https://cf-st.sc-cdn.net/..."
                subscriber_count: 15000
              tempToken: "eyJ..."
              userProfile:
                id: "user123"
                username: "mybrand"
                displayName: "My Brand"
                profilePicture: "https://cf-st.sc-cdn.net/..."
              redirect_url: "https://yourapp.com/callback"
      responses:
        '200':
          description: Snapchat Public Profile connected successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  redirect_url: { type: string, description: Redirect URL with connection params (if provided in request) }
                  account:
                    type: object
                    properties:
                      accountId:
                        type: string
                        description: ID of the created SocialAccount
                      platform: { type: string, enum: [snapchat] }
                      username: { type: string }
                      displayName: { type: string }
                      profilePicture: { type: string }
                      isActive: { type: boolean }
                      publicProfileName: { type: string }
              example:
                message: "Snapchat connected successfully with public profile"
                redirect_url: "https://yourdomain.com/integrations/callback?connected=snapchat&profileId=507f1f77bcf86cd799439011&publicProfile=My+Brand"
                account:
                  accountId: "64e1f0a9e2b5af0012ab34cd"
                  platform: "snapchat"
                  username: "mybrand"
                  displayName: "My Brand"
                  profilePicture: "https://cf-st.sc-cdn.net/..."
                  isActive: true
                  publicProfileName: "My Brand"
        '400':
          description: Missing required fields
          content:
            application/json:
              example:
                error: "Missing required fields"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: No access to profile or profile limit exceeded
          content:
            application/json:
              examples:
                forbidden:
                  value: { error: "Forbidden" }
                limitExceeded:
                  value:
                    error: "Cannot connect to this profile. It exceeds your Pro plan limit of 5 profiles."
                    code: "PROFILE_LIMIT_EXCEEDED"
        '500':
          description: Failed to connect Snapchat account

  /v1/connect/bluesky/credentials:
    post:
      operationId: connectBlueskyCredentials
      tags: [Connect]
      summary: Connect Bluesky account
      description: |
        Connect a Bluesky account using identifier (handle or email) and an app password.
        To get your userId for the state parameter, call GET /v1/users which includes a currentUserId field.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [identifier, appPassword, state]
              properties:
                identifier:
                  type: string
                  description: Your Bluesky handle (e.g. user.bsky.social) or email address
                appPassword:
                  type: string
                  description: App password generated from Bluesky Settings > App Passwords
                state:
                  type: string
                  description: Required state formatted as {userId}-{profileId}. Get userId from GET /v1/users and profileId from GET /v1/profiles.
                  example: "6507a1b2c3d4e5f6a7b8c9d0-6507a1b2c3d4e5f6a7b8c9d1"
                redirectUri:
                  type: string
                  format: uri
                  description: Optional URL to redirect to after successful connection
            example:
              identifier: "yourhandle.bsky.social"
              appPassword: "xxxx-xxxx-xxxx-xxxx"
              state: "6507a1b2c3d4e5f6a7b8c9d0-6507a1b2c3d4e5f6a7b8c9d1"
              redirectUri: "https://yourapp.com/connected"
      responses:
        '200':
          description: Bluesky connected successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  account: { $ref: '#/components/schemas/SocialAccount' }
              example:
                message: "Bluesky connected successfully"
                account:
                  platform: "bluesky"
                  username: "yourhandle.bsky.social"
                  displayName: "Your Name"
                  isActive: true
                redirectUrl: "https://zernio.com/dashboard/profiles/64f0.../accounts"
        '400': { description: Invalid request - missing fields or invalid state format }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '500': { description: Internal error }

  /v1/connect/whatsapp/credentials:
    post:
      operationId: connectWhatsAppCredentials
      tags: [Connect]
      summary: Connect WhatsApp via credentials
      description: |
        Connect a WhatsApp Business Account by providing Meta credentials directly.
        This is the headless alternative to the Embedded Signup browser flow.

        To get the required credentials:
        1. Go to Meta Business Suite (business.facebook.com)
        2. Create or select a WhatsApp Business Account
        3. In Business Settings > System Users, create a System User
        4. Assign it the `whatsapp_business_management` and `whatsapp_business_messaging` permissions
        5. Generate a permanent access token
        6. Get the WABA ID from WhatsApp Manager > Account Tools > Phone Numbers
        7. Get the Phone Number ID from the same page (click on the number)
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [profileId, accessToken, wabaId, phoneNumberId]
              properties:
                profileId:
                  type: string
                  description: Your Zernio profile ID
                accessToken:
                  type: string
                  description: Permanent System User access token from Meta Business Suite
                wabaId:
                  type: string
                  description: WhatsApp Business Account ID from Meta
                phoneNumberId:
                  type: string
                  description: Phone Number ID from Meta WhatsApp Manager
            example:
              profileId: "6507a1b2c3d4e5f6a7b8c9d0"
              accessToken: "EAABsbCS...your-system-user-token"
              wabaId: "123456789012345"
              phoneNumberId: "987654321098765"
      responses:
        '200':
          description: WhatsApp connected successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  account:
                    type: object
                    properties:
                      accountId: { type: string }
                      platform: { type: string, enum: [whatsapp] }
                      username: { type: string, description: Display phone number }
                      displayName: { type: string, description: Meta-verified business name }
                      isActive: { type: boolean }
                      selectedPhoneNumber: { type: string, description: The connected phone number }
              example:
                message: "WhatsApp connected successfully"
                account:
                  accountId: "6507a1b2c3d4e5f6a7b8c9d0"
                  platform: "whatsapp"
                  username: "+1 555-123-4567"
                  displayName: "Acme Corp"
                  isActive: true
                  selectedPhoneNumber: "+1 555-123-4567"
        '400':
          description: |
            Invalid request. Either missing fields or the phoneNumberId was not found
            in the specified WABA. If the phone was not found, the response includes
            `availablePhoneNumbers` to help identify the correct ID.
        '401':
          description: Invalid or expired access token
        '403':
          description: Profile limit exceeded for this plan

  /v1/connect/telegram:
    get:
      operationId: getTelegramConnectStatus
      tags: [Connect]
      summary: Generate Telegram code
      description: Generate an access code (valid 15 minutes) for connecting a Telegram channel or group. Add the bot as admin, then send the code + @yourchannel to the bot. Poll PATCH /v1/connect/telegram to check status.
      parameters:
        - name: profileId
          in: query
          required: true
          schema: { type: string }
          description: The profile ID to connect the Telegram account to
      responses:
        '200':
          description: Access code generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    description: The access code to send to the Telegram bot
                    example: "ZRN-ABC123"
                  expiresAt:
                    type: string
                    format: date-time
                    description: When the code expires
                  expiresIn:
                    type: integer
                    description: Seconds until expiration
                    example: 900
                  botUsername:
                    type: string
                    description: The Telegram bot username to message
                    example: "LateScheduleBot"
                  instructions:
                    type: array
                    items: { type: string }
                    description: Step-by-step connection instructions
              example:
                code: "ZRN-ABC123"
                expiresAt: "2024-01-15T12:30:00.000Z"
                expiresIn: 900
                botUsername: "LateScheduleBot"
                instructions:
                  - "1. Add @ZernioScheduleBot as an administrator in your channel/group"
                  - "2. Open a private chat with @ZernioScheduleBot"
                  - "3. Send: ZRN-ABC123 @yourchannel (replace @yourchannel with your channel username)"
                  - "4. Wait for confirmation - the connection will appear in your dashboard"
                  - "Tip: If your channel has no public username, forward a message from it along with the code"
        '400': { description: Profile ID required or invalid format }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { description: No access to this profile }
        '404': { description: Profile not found }
        '500': { description: Internal error }
    post:
      operationId: initiateTelegramConnect
      tags: [Connect]
      summary: Connect Telegram directly
      description: Connect a Telegram channel/group directly using the chat ID. Alternative to the access code flow. The bot must already be an admin in the channel/group.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [chatId, profileId]
              properties:
                chatId:
                  type: string
                  description: The Telegram chat ID. Numeric ID (e.g. "-1001234567890") or username with @ prefix (e.g. "@mychannel").
                profileId:
                  type: string
                  description: The profile ID to connect the account to
            example:
              chatId: "-1001234567890"
              profileId: "6507a1b2c3d4e5f6a7b8c9d0"
      responses:
        '200':
          description: Telegram channel connected successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  account:
                    type: object
                    properties:
                      _id: { type: string }
                      platform: { type: string, enum: [telegram] }
                      username: { type: string }
                      displayName: { type: string }
                      isActive: { type: boolean }
                      chatType: { type: string, enum: [channel, group, supergroup, private] }
              example:
                message: "Telegram channel connected successfully"
                account:
                  _id: "64e1f0a9e2b5af0012ab34cd"
                  platform: "telegram"
                  username: "mychannel"
                  displayName: "My Channel"
                  isActive: true
                  chatType: "channel"
        '400': { description: Chat ID required, bot not admin, or cannot access chat }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { description: No access to this profile }
        '404': { description: Profile not found }
        '500': { description: Internal error }
    patch:
      operationId: completeTelegramConnect
      tags: [Connect]
      summary: Check Telegram status
      description: |
        Poll this endpoint to check if a Telegram access code has been used to connect a channel/group. Recommended polling interval: 3 seconds.
        Status values: pending (waiting for user), connected (channel/group linked), expired (generate a new code).
      parameters:
        - name: code
          in: query
          required: true
          schema: { type: string }
          description: The access code to check status for
          example: "ZRN-ABC123"
      responses:
        '200':
          description: Connection status
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    title: Pending
                    properties:
                      status: { type: string, enum: [pending] }
                      expiresAt: { type: string, format: date-time }
                      expiresIn: { type: integer, description: Seconds until expiration }
                  - type: object
                    title: Connected
                    properties:
                      status: { type: string, enum: [connected] }
                      chatId: { type: string }
                      chatTitle: { type: string }
                      chatType: { type: string, enum: [channel, group, supergroup] }
                      account:
                        type: object
                        properties:
                          _id: { type: string }
                          platform: { type: string }
                          username: { type: string }
                          displayName: { type: string }
                  - type: object
                    title: Expired
                    properties:
                      status: { type: string, enum: [expired] }
                      message: { type: string }
              examples:
                pending:
                  summary: Waiting for connection
                  value:
                    status: "pending"
                    expiresAt: "2024-01-15T12:30:00.000Z"
                    expiresIn: 542
                connected:
                  summary: Successfully connected
                  value:
                    status: "connected"
                    chatId: "-1001234567890"
                    chatTitle: "My Channel"
                    chatType: "channel"
                    account:
                      _id: "64e1f0a9e2b5af0012ab34cd"
                      platform: "telegram"
                      username: "mychannel"
                      displayName: "My Channel"
                expired:
                  summary: Code expired
                  value:
                    status: "expired"
                    message: "Access code has expired. Please generate a new one."
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Code not found }
        '500': { description: Internal error }

  /v1/accounts/{accountId}/facebook-page:
    get:
      operationId: getFacebookPages
      tags: [Connect]
      summary: List Facebook pages
      description: Returns all Facebook pages the connected account has access to, including the currently selected page.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Pages list
          content:
            application/json:
              schema:
                type: object
                properties:
                  pages:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        name: { type: string }
                        username: { type: string }
                        category: { type: string }
                        fan_count: { type: integer }
                  selectedPageId: { type: string }
                  cached: { type: boolean }
              example:
                pages:
                  - id: "123456789012345"
                    name: "My Brand Page"
                    username: "mybrand"
                    category: "Brand"
                    fan_count: 5000
                  - id: "234567890123456"
                    name: "My Other Page"
                    username: "myotherpage"
                    category: "Business"
                    fan_count: 1200
                selectedPageId: "123456789012345"
                cached: true
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }
    put:
      operationId: updateFacebookPage
      tags: [Connect]
      summary: Update Facebook page
      description: Switch which Facebook Page is active for a connected account.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [selectedPageId]
              properties:
                selectedPageId: { type: string }
            example:
              selectedPageId: "123456789012345"
      responses:
        '200':
          description: Page updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  selectedPage:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
              example:
                message: "Facebook page updated successfully"
                selectedPage:
                  id: "123456789012345"
                  name: "My Brand Page"
        '400': { description: Page not in available pages }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }

  /v1/accounts/{accountId}/linkedin-organizations:
    get:
      operationId: getLinkedInOrganizations
      tags: [Connect]
      summary: List LinkedIn orgs
      description: Returns LinkedIn organizations (company pages) the connected account has admin access to.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Organizations list
          content:
            application/json:
              schema:
                type: object
                properties:
                  organizations:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        name: { type: string }
                        vanityName: { type: string }
                        localizedName: { type: string }
              example:
                organizations:
                  - id: "12345678"
                    name: "Acme Corporation"
                    vanityName: "acme-corp"
                    localizedName: "Acme Corporation"
                  - id: "87654321"
                    name: "Acme Subsidiary"
                    vanityName: "acme-sub"
                    localizedName: "Acme Subsidiary"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }

  /v1/accounts/{accountId}/linkedin-aggregate-analytics:
    get:
      operationId: getLinkedInAggregateAnalytics
      tags: [Analytics]
      summary: Get LinkedIn aggregate stats
      description: Returns aggregate analytics across all posts for a LinkedIn personal account. Org accounts should use /v1/analytics instead. Requires r_member_postAnalytics scope.
      parameters:
        - name: accountId
          in: path
          required: true
          description: The ID of the LinkedIn personal account
          schema: { type: string }
        - name: aggregation
          in: query
          required: false
          description: TOTAL (default, lifetime totals) or DAILY (time series). MEMBERS_REACHED not available with DAILY.
          schema:
            type: string
            enum: [TOTAL, DAILY]
            default: TOTAL
        - name: startDate
          in: query
          required: false
          description: Start date (YYYY-MM-DD). If omitted, returns lifetime analytics.
          schema:
            type: string
            format: date
          example: "2024-01-01"
        - name: endDate
          in: query
          required: false
          description: End date (YYYY-MM-DD, exclusive). Defaults to today if omitted.
          schema:
            type: string
            format: date
          example: "2024-01-31"
        - name: metrics
          in: query
          required: false
          description: "Comma-separated metrics: IMPRESSION, MEMBERS_REACHED, REACTION, COMMENT, RESHARE. Omit for all."
          schema:
            type: string
          example: "IMPRESSION,REACTION,COMMENT"
      responses:
        '200':
          description: Aggregate analytics data
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/LinkedInAggregateAnalyticsTotalResponse'
                  - $ref: '#/components/schemas/LinkedInAggregateAnalyticsDailyResponse'
              examples:
                totalAggregation:
                  summary: TOTAL aggregation (lifetime totals)
                  value:
                    accountId: "64abc123def456"
                    platform: "linkedin"
                    accountType: "personal"
                    username: "John Doe"
                    aggregation: "TOTAL"
                    dateRange: null
                    analytics:
                      impressions: 1250000
                      reach: 450000
                      reactions: 7500
                      comments: 2500
                      shares: 1200
                      engagementRate: 0.90
                    note: "Aggregate analytics across all posts on this LinkedIn personal account (lifetime totals)."
                    lastUpdated: "2025-01-15T10:30:00.000Z"
                totalWithDateRange:
                  summary: TOTAL aggregation with date range
                  value:
                    accountId: "64abc123def456"
                    platform: "linkedin"
                    accountType: "personal"
                    username: "John Doe"
                    aggregation: "TOTAL"
                    dateRange:
                      startDate: "2024-01-01"
                      endDate: "2024-01-31"
                    analytics:
                      impressions: 125000
                      reach: 45000
                      reactions: 750
                      comments: 250
                      shares: 120
                      engagementRate: 0.90
                    note: "Aggregate analytics for the specified date range."
                    lastUpdated: "2025-01-15T10:30:00.000Z"
                dailyAggregation:
                  summary: DAILY aggregation (time series)
                  value:
                    accountId: "64abc123def456"
                    platform: "linkedin"
                    accountType: "personal"
                    username: "John Doe"
                    aggregation: "DAILY"
                    dateRange:
                      startDate: "2024-05-04"
                      endDate: "2024-05-06"
                    analytics:
                      impressions:
                        - date: "2024-05-04"
                          count: 1500
                        - date: "2024-05-05"
                          count: 2300
                      reactions:
                        - date: "2024-05-04"
                          count: 10
                        - date: "2024-05-05"
                          count: 20
                      comments:
                        - date: "2024-05-04"
                          count: 3
                        - date: "2024-05-05"
                          count: 5
                      shares:
                        - date: "2024-05-04"
                          count: 2
                        - date: "2024-05-05"
                          count: 4
                    skippedMetrics:
                      - "MEMBERS_REACHED (not supported with DAILY aggregation)"
                    note: "Daily breakdown of analytics across all posts. MEMBERS_REACHED is not available with DAILY aggregation per LinkedIn API limitations."
                    lastUpdated: "2025-01-15T10:30:00.000Z"
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  code: { type: string }
                  validOptions: { type: array, items: { type: string } }
              examples:
                not_linkedin:
                  summary: Not a LinkedIn account
                  value:
                    error: "This endpoint only supports LinkedIn accounts"
                    code: "invalid_platform"
                organization:
                  summary: Org account not supported
                  value:
                    error: "Aggregate analytics only available for LinkedIn personal accounts. Organization accounts can use per-post analytics via /v1/analytics."
                    code: "organization_not_supported"
                invalid_aggregation:
                  summary: Invalid aggregation type
                  value:
                    error: "Invalid aggregation type. Must be one of: TOTAL, DAILY"
                    code: "invalid_aggregation"
                    validOptions: ["TOTAL", "DAILY"]
                invalid_date:
                  summary: Invalid date format
                  value:
                    error: "Invalid date format. Use YYYY-MM-DD format."
                    code: "invalid_date_format"
                    example:
                      startDate: "2024-01-01"
                      endDate: "2024-01-31"
                invalid_metrics:
                  summary: Invalid metrics requested
                  value:
                    error: "Invalid metrics: INVALID_METRIC. Valid options: IMPRESSION, MEMBERS_REACHED, REACTION, COMMENT, RESHARE"
                    code: "invalid_metrics"
                    validOptions: ["IMPRESSION", "MEMBERS_REACHED", "REACTION", "COMMENT", "RESHARE"]
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402':
          description: Analytics add-on required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  code: { type: string }
        '403':
          description: Missing required LinkedIn scope
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  code: { type: string, example: missing_scope }
                  requiredScope: { type: string, example: r_member_postAnalytics }
                  action: { type: string, example: reconnect }
              example:
                error: "Missing r_member_postAnalytics scope. Please reconnect your LinkedIn account to grant analytics permissions."
                code: "missing_scope"
                requiredScope: "r_member_postAnalytics"
                action: "reconnect"
        '404': { description: Account not found }

  /v1/accounts/{accountId}/linkedin-post-analytics:
    get:
      operationId: getLinkedInPostAnalytics
      tags: [Analytics]
      summary: Get LinkedIn post stats
      description: Returns analytics for a specific LinkedIn post by URN. Works for both personal and organization accounts.
      parameters:
        - name: accountId
          in: path
          required: true
          description: The ID of the LinkedIn account
          schema: { type: string }
        - name: urn
          in: query
          required: true
          description: The LinkedIn post URN
          schema: { type: string }
          example: "urn:li:share:7123456789012345678"
      responses:
        '200':
          description: Post analytics data
          content:
            application/json:
              schema:
                type: object
                properties:
                  accountId: { type: string }
                  platform: { type: string, example: linkedin }
                  accountType: { type: string, enum: [personal, organization] }
                  username: { type: string }
                  postUrn: { type: string }
                  analytics:
                    type: object
                    properties:
                      impressions: { type: integer, description: Times the post was shown }
                      reach: { type: integer, description: Unique members who saw the post }
                      likes: { type: integer, description: Reactions on the post }
                      comments: { type: integer, description: Comments on the post }
                      shares: { type: integer, description: Reshares of the post }
                      clicks: { type: integer, description: Clicks on the post (organization accounts only) }
                      views: { type: integer, description: Video views (video posts only) }
                      engagementRate: { type: number, description: Engagement rate as percentage }
                  lastUpdated: { type: string, format: date-time }
              example:
                accountId: "64abc123def456"
                platform: "linkedin"
                accountType: "personal"
                username: "John Doe"
                postUrn: "urn:li:share:7123456789012345678"
                analytics:
                  impressions: 5420
                  reach: 3200
                  likes: 156
                  comments: 23
                  shares: 12
                  clicks: 0
                  views: 1250
                  engagementRate: 5.17
                lastUpdated: "2025-01-15T10:30:00.000Z"
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  code: { type: string, enum: [missing_urn, invalid_urn, invalid_platform] }
              examples:
                missing_urn:
                  value:
                    error: "Missing required parameter: urn"
                    code: "missing_urn"
                    example: "urn:li:share:7123456789012345678 or urn:li:ugcPost:7123456789012345678"
                invalid_urn:
                  value:
                    error: "Invalid URN format. Must be urn:li:share:ID or urn:li:ugcPost:ID"
                    code: "invalid_urn"
                    providedUrn: "invalid-urn"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402':
          description: Analytics add-on required
        '403':
          description: Missing required LinkedIn scope
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  code: { type: string, example: missing_scope }
                  requiredScope: { type: string }
                  action: { type: string, example: reconnect }
        '404':
          description: Account or post not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  code: { type: string }
              examples:
                account_not_found:
                  value:
                    error: "Account not found"
                post_not_found:
                  value:
                    error: "Post not found. The URN may be invalid or the post may have been deleted."
                    code: "post_not_found"
                    postUrn: "urn:li:share:123"

  /v1/accounts/{accountId}/linkedin-post-reactions:
    get:
      operationId: getLinkedInPostReactions
      tags: [Analytics]
      summary: Get LinkedIn post reactions
      description: |
        Returns individual reactions for a specific LinkedIn post, including reactor profiles
        (name, headline/job title, profile picture, profile URL, reaction type).
        Only works for **organization/company page** accounts. LinkedIn restricts reaction
        data for personal profiles (r_member_social_feed is a closed permission).
      parameters:
        - name: accountId
          in: path
          required: true
          description: The ID of the LinkedIn organization account
          schema: { type: string }
        - name: urn
          in: query
          required: true
          description: The LinkedIn post URN
          schema: { type: string }
          example: "urn:li:share:7123456789012345678"
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
          description: Maximum number of reactions to return per page
        - name: cursor
          in: query
          schema: { type: string }
          description: Offset-based pagination start index
      responses:
        '200':
          description: Reactions with reactor profiles
          content:
            application/json:
              schema:
                type: object
                properties:
                  accountId: { type: string }
                  platform: { type: string, example: linkedin }
                  accountType: { type: string, example: organization }
                  username: { type: string }
                  postUrn: { type: string }
                  reactions:
                    type: array
                    items:
                      type: object
                      properties:
                        reactionType:
                          type: string
                          description: LinkedIn reaction enum (LIKE, PRAISE, EMPATHY, INTEREST, APPRECIATION, ENTERTAINMENT)
                        reactionLabel:
                          type: string
                          description: User-friendly label (Like, Celebrate, Love, Insightful, Support, Funny)
                        reactedAt: { type: string, format: date-time }
                        from:
                          type: object
                          properties:
                            urn: { type: string, description: "LinkedIn person or organization URN" }
                            name: { type: string, description: "Reactor's display name" }
                            headline: { type: string, description: "Reactor's headline/job title" }
                            username: { type: string, description: "LinkedIn vanity name" }
                            profilePicture: { type: string, description: "Profile picture URL" }
                            profileUrl: { type: string, description: "Direct link to LinkedIn profile" }
                  pagination:
                    type: object
                    properties:
                      hasMore: { type: boolean }
                      cursor: { type: string, description: "Offset for next page" }
                      total: { type: integer, description: "Total number of reactions (when available)" }
                  lastUpdated: { type: string, format: date-time }
              example:
                accountId: "64abc123def456"
                platform: "linkedin"
                accountType: "organization"
                username: "Acme Corp"
                postUrn: "urn:li:share:7123456789012345678"
                reactions:
                  - reactionType: "LIKE"
                    reactionLabel: "Like"
                    reactedAt: "2026-03-08T12:00:00.000Z"
                    from:
                      urn: "urn:li:person:abc123"
                      name: "Jane Smith"
                      headline: "Product Manager at Acme Corp"
                      username: "janesmith"
                      profilePicture: "https://media.licdn.com/..."
                      profileUrl: "https://www.linkedin.com/in/janesmith"
                pagination:
                  hasMore: true
                  cursor: "25"
                  total: 156
                lastUpdated: "2026-03-08T12:00:00.000Z"
        '400':
          description: Invalid request or platform limitation
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  code: { type: string, enum: [missing_urn, invalid_urn, invalid_platform, PLATFORM_LIMITATION] }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402':
          description: Analytics add-on required
        '403':
          description: Missing required LinkedIn scope
        '404':
          description: Account or post not found

  /v1/accounts/{accountId}/linkedin-organization:
    put:
      operationId: updateLinkedInOrganization
      tags: [Connect]
      summary: Switch LinkedIn account type
      description: Switch a LinkedIn account between personal profile and organization (company page) posting.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountType]
              properties:
                accountType: { type: string, enum: [personal, organization] }
                selectedOrganization: { type: object }
            example:
              accountType: "organization"
              selectedOrganization:
                id: "12345678"
                name: "Acme Corporation"
                vanityName: "acme-corp"
      responses:
        '200':
          description: Account updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  account: { $ref: '#/components/schemas/SocialAccount' }
              example:
                message: "LinkedIn account type updated successfully"
                account:
                  _id: "64e1f0a9e2b5af0012ab34cd"
                  platform: "linkedin"
                  username: "acme-corp"
                  displayName: "Acme Corporation"
                  isActive: true
        '400': { description: Invalid request }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }

  /v1/accounts/{accountId}/linkedin-mentions:
    get:
      operationId: getLinkedInMentions
      tags: [LinkedIn Mentions]
      summary: Resolve LinkedIn mention
      description: |
        Converts a LinkedIn profile or company URL to a URN for @mentions in posts.

        **How to use LinkedIn @mentions (2-step workflow):**

        1. Call this endpoint with the LinkedIn profile/company URL to get the mention URN and format.
        2. Embed the returned `mentionFormat` (e.g. `@[Vincent Jong](urn:li:person:xxx)`) directly in your post's `content` field.

        **Example:**
        - Resolve: `GET /v1/accounts/{id}/linkedin-mentions?url=linkedin.com/in/vincentjong&displayName=Vincent Jong`
        - Returns: `mentionFormat: "@[Vincent Jong](urn:li:person:xxx)"`
        - Use in post content: `"Great talk with @[Vincent Jong](urn:li:person:xxx) today!"`

        **Important:** The `mentions` array field in POST /v1/posts is stored for reference only and does NOT trigger @mentions on LinkedIn. You must embed the mention format directly in the content text.

        **Requirements:**
        - **Person mentions** require the LinkedIn account to be admin of at least one organization. This is a LinkedIn API limitation: the only endpoints that resolve profile URLs to member URNs (`vanityUrl`, `peopleTypeahead`) are scoped to organization followers. There is no public LinkedIn API to resolve a vanity URL without organization context.
        - **Organization mentions** (e.g. @Microsoft) work without this requirement.
        - For person mentions to be clickable, the `displayName` parameter must exactly match the name shown on their LinkedIn profile.
        - Person mentions DO work when published from personal profiles (the URN just needs to be valid). The limitation is only in the resolution step (URL to URN), not in publishing.
      parameters:
        - name: accountId
          in: path
          required: true
          description: The LinkedIn account ID
          schema: { type: string }
        - name: url
          in: query
          required: true
          description: LinkedIn profile URL, company URL, or vanity name.
          schema: { type: string }
          examples:
            personVanityName:
              value: "miquelpalet"
              summary: Person - just the vanity name
            personFullUrl:
              value: "https://www.linkedin.com/in/miquelpalet"
              summary: Person - full LinkedIn URL
            orgShortUrl:
              value: "company/microsoft"
              summary: Org - short format
            orgFullUrl:
              value: "https://www.linkedin.com/company/microsoft"
              summary: Org - full LinkedIn URL
        - name: displayName
          in: query
          required: false
          description: Exact display name as shown on LinkedIn. Required for person mentions to be clickable. Optional for org mentions.
          schema: { type: string }
          examples:
            personName:
              value: "Miquel Palet"
              summary: Exact name as shown on LinkedIn profile
            orgName:
              value: "Microsoft"
              summary: Company name (optional for orgs)
      responses:
        '200':
          description: URN resolved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  urn:
                    type: string
                    description: The LinkedIn URN (person or organization)
                    example: "urn:li:person:4qj5ox-agD"
                  type:
                    type: string
                    enum: [person, organization]
                    description: The type of entity (person or organization)
                    example: "person"
                  displayName:
                    type: string
                    description: Display name (provided, from API, or derived from vanity URL)
                    example: "Miquel Palet"
                  mentionFormat:
                    type: string
                    description: Ready-to-use mention format for post content
                    example: "@[Miquel Palet](urn:li:person:4qj5ox-agD)"
                  vanityName:
                    type: string
                    description: The vanity name/slug (only for organization mentions)
                    example: "microsoft"
                  warning:
                    type: string
                    description: Warning about clickable mentions (only present for person mentions if displayName was not provided)
                    example: "For clickable person mentions, provide the displayName parameter with the exact name as shown on their LinkedIn profile."
              examples:
                personWithDisplayName:
                  summary: Person mention with displayName (recommended)
                  value:
                    urn: "urn:li:person:4qj5ox-agD"
                    type: "person"
                    displayName: "Miquel Palet"
                    mentionFormat: "@[Miquel Palet](urn:li:person:4qj5ox-agD)"
                personWithoutDisplayName:
                  summary: Person mention without displayName (may not be clickable)
                  value:
                    urn: "urn:li:person:4qj5ox-agD"
                    type: "person"
                    displayName: "Miquelpalet"
                    mentionFormat: "@[Miquelpalet](urn:li:person:4qj5ox-agD)"
                    warning: "For clickable person mentions, provide the displayName parameter with the exact name as shown on their LinkedIn profile."
                organization:
                  summary: Org mention
                  value:
                    urn: "urn:li:organization:1035"
                    type: "organization"
                    displayName: "Microsoft"
                    mentionFormat: "@[Microsoft](urn:li:organization:1035)"
                    vanityName: "microsoft"
        '400':
          description: Invalid request or no organization found (for person mentions)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
              examples:
                missingUrl:
                  value: { error: "url parameter is required" }
                noOrgForPersonMention:
                  value: { error: "No organization found. You need to be an admin of a LinkedIn organization to use person mentions. Organization mentions work without this requirement." }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404':
          description: Person or organization not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
              examples:
                memberNotFound:
                  value: { error: "Member not found. Check the LinkedIn URL is correct." }
                orgNotFound:
                  value: { error: "Organization not found. Check the LinkedIn company URL is correct." }

  /v1/accounts/{accountId}/pinterest-boards:
    get:
      operationId: getPinterestBoards
      tags: [Connect]
      summary: List Pinterest boards
      description: Returns the boards available for a connected Pinterest account. Use this to get a board ID when creating a Pinterest post.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Boards list
          content:
            application/json:
              schema:
                type: object
                properties:
                  boards:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        name: { type: string }
                        description: { type: string }
                        privacy: { type: string }
              example:
                boards:
                  - id: "123456789012345678"
                    name: "Marketing Ideas"
                    description: "Collection of marketing inspiration"
                    privacy: "PUBLIC"
                  - id: "234567890123456789"
                    name: "Product Photos"
                    description: "Product photography"
                    privacy: "PUBLIC"
        '400': { description: Not a Pinterest account }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }
    put:
      operationId: updatePinterestBoards
      tags: [Connect]
      summary: Set default Pinterest board
      description: Sets the default board used when publishing pins for this account.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [defaultBoardId]
              properties:
                defaultBoardId: { type: string }
                defaultBoardName: { type: string }
            example:
              defaultBoardId: "123456789012345678"
              defaultBoardName: "Marketing Ideas"
      responses:
        '200':
          description: Default board set
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  account: { $ref: '#/components/schemas/SocialAccount' }
              example:
                message: "Default Pinterest board updated successfully"
                account:
                  _id: "64e1f0a9e2b5af0012ab34cd"
                  platform: "pinterest"
                  username: "mybrand"
                  displayName: "My Brand"
                  isActive: true
        '400': { description: Invalid request }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }

  /v1/accounts/{accountId}/youtube-playlists:
    get:
      operationId: getYoutubePlaylists
      tags: [Connect]
      summary: List YouTube playlists
      description: Returns the playlists available for a connected YouTube account. Use this to get a playlist ID when creating a YouTube post with the `playlistId` field.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Playlists list
          content:
            application/json:
              schema:
                type: object
                properties:
                  playlists:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        title: { type: string }
                        description: { type: string }
                        privacy: { type: string, enum: [public, private, unlisted] }
                        itemCount: { type: integer }
                        thumbnailUrl: { type: string }
                  defaultPlaylistId:
                    type: string
                    nullable: true
              example:
                playlists:
                  - id: "PLxxxxxxxxxxxxx"
                    title: "Tutorials"
                    description: "Step-by-step video tutorials"
                    privacy: "public"
                    itemCount: 24
                    thumbnailUrl: "https://i.ytimg.com/vi/xxx/mqdefault.jpg"
                  - id: "PLyyyyyyyyyyyyy"
                    title: "Vlogs"
                    description: "Weekly vlogs"
                    privacy: "public"
                    itemCount: 52
                    thumbnailUrl: "https://i.ytimg.com/vi/yyy/mqdefault.jpg"
                defaultPlaylistId: null
        '400': { description: Not a YouTube account }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }
    put:
      operationId: updateYoutubeDefaultPlaylist
      tags: [Connect]
      summary: Set default YouTube playlist
      description: Sets the default playlist used when publishing videos for this account. When a post does not specify a `playlistId`, the default playlist is not automatically used (it is stored for client-side convenience).
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [defaultPlaylistId]
              properties:
                defaultPlaylistId: { type: string }
                defaultPlaylistName: { type: string }
            example:
              defaultPlaylistId: "PLxxxxxxxxxxxxx"
              defaultPlaylistName: "Tutorials"
      responses:
        '200':
          description: Default playlist set
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
              example:
                success: true
        '400': { description: Invalid request }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }

  /v1/accounts/{accountId}/gmb-locations:
    get:
      operationId: getGmbLocations
      tags: [Connect]
      summary: List GBP locations
      description: Returns all Google Business Profile locations the connected account has access to, including the currently selected location.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Locations list
          content:
            application/json:
              schema:
                type: object
                properties:
                  locations:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        name: { type: string }
                        accountId: { type: string }
                        accountName: { type: string }
                        address: { type: string }
                        category: { type: string }
                        websiteUrl: { type: string }
                  selectedLocationId: { type: string }
                  cached: { type: boolean }
              example:
                locations:
                  - id: "12345678901234567890"
                    name: "My Business Location"
                    accountId: "accounts/123456789"
                    accountName: "My Business Account"
                    address: "123 Main St, San Francisco, CA"
                    category: "Restaurant"
                    websiteUrl: "https://mybusiness.com"
                selectedLocationId: "12345678901234567890"
                cached: true
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }
    put:
      operationId: updateGmbLocation
      tags: [Connect]
      summary: Update GBP location
      description: Switch which GBP location is active for a connected account.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [selectedLocationId]
              properties:
                selectedLocationId: { type: string }
            example:
              selectedLocationId: "12345678901234567890"
      responses:
        '200':
          description: Location updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  selectedLocation:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
              example:
                message: "Google Business location updated successfully"
                selectedLocation:
                  id: "12345678901234567890"
                  name: "My Business Location"
        '400': { description: Location not in available locations }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }

  /v1/accounts/{accountId}/reddit-subreddits:
    get:
      operationId: getRedditSubreddits
      tags: [Connect]
      summary: List Reddit subreddits
      description: Returns the subreddits the connected Reddit account can post to. Use this to get a subreddit name when creating a Reddit post.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Subreddits list
          content:
            application/json:
              schema:
                type: object
                properties:
                  subreddits:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, description: Reddit subreddit ID }
                        name: { type: string, description: Subreddit name without r/ prefix }
                        title: { type: string, description: Subreddit title }
                        url: { type: string, description: Subreddit URL path }
                        over18: { type: boolean, description: Whether the subreddit is NSFW }
                  defaultSubreddit:
                    type: string
                    description: Currently set default subreddit for posting
              example:
                subreddits:
                  - id: "2qh1i"
                    name: "marketing"
                    title: "Marketing"
                    url: "/r/marketing/"
                    over18: false
                  - id: "2qh3l"
                    name: "socialmedia"
                    title: "Social Media"
                    url: "/r/socialmedia/"
                    over18: false
                defaultSubreddit: "marketing"
        '400': { description: Not a Reddit account }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }

    put:
      operationId: updateRedditSubreddits
      tags: [Connect]
      summary: Set default subreddit
      description: Sets the default subreddit used when publishing posts for this Reddit account.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [defaultSubreddit]
              properties:
                defaultSubreddit: { type: string }
            example:
              defaultSubreddit: "marketing"
      responses:
        '200':
          description: Default subreddit set
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
              example:
                success: true
        '400': { description: Invalid request }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }

  /v1/accounts/{accountId}/reddit-flairs:
    get:
      operationId: getRedditFlairs
      tags: [Connect]
      summary: List subreddit flairs
      description: Returns available post flairs for a subreddit. Some subreddits require a flair when posting.
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
        - name: subreddit
          in: query
          required: true
          schema: { type: string }
          description: Subreddit name (without "r/" prefix) to fetch flairs for
      responses:
        '200':
          description: Flairs list
          content:
            application/json:
              schema:
                type: object
                properties:
                  flairs:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, description: Flair ID to pass as flairId in platformSpecificData }
                        text: { type: string, description: Flair display text }
                        textColor: { type: string, description: "Text color: 'dark' or 'light'" }
                        backgroundColor: { type: string, description: "Background hex color (e.g. '#ff4500')" }
              example:
                flairs:
                  - id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                    text: "Discussion"
                    textColor: "dark"
                    backgroundColor: "#edeff1"
                  - id: "b2c3d4e5-f6a7-8901-bcde-f12345678901"
                    text: "News"
                    textColor: "light"
                    backgroundColor: "#ff4500"
        '400': { description: Not a Reddit account or missing subreddit parameter }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }

  /v1/queue/slots:
    get:
      operationId: listQueueSlots
      tags: [Queue]
      summary: List schedules
      description: Returns queue schedules for a profile. Use all=true for all queues, or queueId for a specific one. Defaults to the default queue.
      parameters:
        - name: profileId
          in: query
          required: true
          schema: { type: string }
          description: Profile ID to get queues for
        - name: queueId
          in: query
          required: false
          schema: { type: string }
          description: Specific queue ID to retrieve (optional)
        - name: all
          in: query
          required: false
          schema: { type: string, enum: ['true'] }
          description: Set to 'true' to list all queues for the profile
      responses:
        '200':
          description: Queue schedule(s) retrieved
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    description: Single queue response (default behavior)
                    properties:
                      exists: { type: boolean }
                      schedule:
                        $ref: '#/components/schemas/QueueSchedule'
                      nextSlots:
                        type: array
                        items: { type: string, format: date-time }
                  - type: object
                    description: All queues response (when all=true)
                    properties:
                      queues:
                        type: array
                        items:
                          $ref: '#/components/schemas/QueueSchedule'
                      count: { type: integer }
              examples:
                singleQueue:
                  summary: Single queue response
                  value:
                    exists: true
                    schedule:
                      _id: "64f0a1b2c3d4e5f6a7b8c9d1"
                      profileId: "64f0a1b2c3d4e5f6a7b8c9d0"
                      name: "Morning Posts"
                      timezone: "America/New_York"
                      slots:
                        - dayOfWeek: 1
                          time: "09:00"
                        - dayOfWeek: 3
                          time: "09:00"
                        - dayOfWeek: 5
                          time: "10:00"
                      active: true
                      isDefault: true
                    nextSlots:
                      - "2024-11-04T09:00:00-05:00"
                      - "2024-11-06T09:00:00-05:00"
                allQueues:
                  summary: All queues response (all=true)
                  value:
                    queues:
                      - _id: "64f0a1b2c3d4e5f6a7b8c9d1"
                        name: "Morning Posts"
                        isDefault: true
                        timezone: "America/New_York"
                        slots: [{ dayOfWeek: 1, time: "09:00" }]
                        active: true
                      - _id: "64f0a1b2c3d4e5f6a7b8c9d2"
                        name: "Evening Content"
                        isDefault: false
                        timezone: "America/New_York"
                        slots: [{ dayOfWeek: 1, time: "18:00" }]
                        active: true
                    count: 2
        '400': { description: Missing profileId }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Profile not found }
    post:
      operationId: createQueueSlot
      tags: [Queue]
      summary: Create schedule
      description: |
        Create an additional queue for a profile. The first queue created becomes the default.
        Subsequent queues are non-default unless explicitly set.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [profileId, name, timezone, slots]
              properties:
                profileId: { type: string, description: Profile ID }
                name: { type: string, description: "Queue name (e.g., Evening Posts)" }
                timezone: { type: string, description: IANA timezone }
                slots:
                  type: array
                  items:
                    $ref: '#/components/schemas/QueueSlot'
                active: { type: boolean, default: true }
            example:
              profileId: "64f0a1b2c3d4e5f6a7b8c9d0"
              name: "Evening Posts"
              timezone: "America/New_York"
              slots:
                - dayOfWeek: 1
                  time: "18:00"
                - dayOfWeek: 3
                  time: "18:00"
                - dayOfWeek: 5
                  time: "18:00"
              active: true
      responses:
        '201':
          description: Queue created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  schedule:
                    $ref: '#/components/schemas/QueueSchedule'
                  nextSlots:
                    type: array
                    items: { type: string, format: date-time }
        '400': { description: Invalid request or validation error }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Profile not found }
    put:
      operationId: updateQueueSlot
      tags: [Queue]
      summary: Update schedule
      description: |
        Create a new queue or update an existing one. Without queueId, creates/updates the default queue. With queueId, updates a specific queue. With setAsDefault=true, makes this queue the default for the profile.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [profileId, timezone, slots]
              properties:
                profileId: { type: string }
                queueId: { type: string, description: Queue ID to update (optional) }
                name: { type: string, description: Queue name }
                timezone: { type: string }
                slots:
                  type: array
                  items:
                    $ref: '#/components/schemas/QueueSlot'
                active: { type: boolean, default: true }
                setAsDefault: { type: boolean, description: Make this queue the default }
                reshuffleExisting:
                  type: boolean
                  default: false
                  description: Whether to reschedule existing queued posts to match new slots
            example:
              profileId: "64f0a1b2c3d4e5f6a7b8c9d0"
              queueId: "64f0a1b2c3d4e5f6a7b8c9d1"
              name: "Morning Posts"
              timezone: "America/New_York"
              slots:
                - dayOfWeek: 1
                  time: "09:00"
                - dayOfWeek: 3
                  time: "09:00"
                - dayOfWeek: 5
                  time: "10:00"
              active: true
              setAsDefault: false
      responses:
        '200':
          description: Queue schedule updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  schedule:
                    $ref: '#/components/schemas/QueueSchedule'
                  nextSlots:
                    type: array
                    items: { type: string, format: date-time }
                  reshuffledCount: { type: integer }
              example:
                success: true
                schedule:
                  _id: "64f0a1b2c3d4e5f6a7b8c9d1"
                  profileId: "64f0a1b2c3d4e5f6a7b8c9d0"
                  name: "Morning Posts"
                  timezone: "America/New_York"
                  slots:
                    - dayOfWeek: 1
                      time: "09:00"
                    - dayOfWeek: 3
                      time: "09:00"
                    - dayOfWeek: 5
                      time: "10:00"
                  active: true
                  isDefault: true
                nextSlots:
                  - "2024-11-04T09:00:00-05:00"
                  - "2024-11-06T09:00:00-05:00"
                reshuffledCount: 0
        '400': { description: Invalid request }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Profile not found }
    delete:
      operationId: deleteQueueSlot
      tags: [Queue]
      summary: Delete schedule
      description: |
        Delete a queue from a profile. Requires queueId to specify which queue to delete.
        If deleting the default queue, another queue will be promoted to default.
      parameters:
        - name: profileId
          in: query
          required: true
          schema: { type: string }
        - name: queueId
          in: query
          required: true
          schema: { type: string }
          description: Queue ID to delete
      responses:
        '200':
          description: Queue schedule deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  deleted: { type: boolean }
              example:
                success: true
                deleted: true
        '400': { description: Missing profileId or queueId }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /v1/queue/preview:
    get:
      operationId: previewQueue
      tags: [Queue]
      summary: Preview upcoming slots
      description: Returns the next N upcoming queue slot times for a profile as ISO datetime strings.
      parameters:
        - name: profileId
          in: query
          required: true
          schema: { type: string }
        - name: queueId
          in: query
          schema: { type: string }
          description: Filter by specific queue ID. Omit to use the default queue.
        - name: count
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
      responses:
        '200':
          description: Queue slots preview
          content:
            application/json:
              schema:
                type: object
                properties:
                  profileId: { type: string }
                  count: { type: integer }
                  slots:
                    type: array
                    items: { type: string, format: date-time }
              example:
                profileId: "64f0a1b2c3d4e5f6a7b8c9d0"
                count: 10
                slots:
                  - "2024-11-04T09:00:00-05:00"
                  - "2024-11-04T14:00:00-05:00"
                  - "2024-11-06T09:00:00-05:00"
                  - "2024-11-08T10:00:00-05:00"
                  - "2024-11-11T09:00:00-05:00"
                  - "2024-11-11T14:00:00-05:00"
                  - "2024-11-13T09:00:00-05:00"
                  - "2024-11-15T10:00:00-05:00"
                  - "2024-11-18T09:00:00-05:00"
                  - "2024-11-18T14:00:00-05:00"
        '400': { description: Invalid parameters }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Profile or queue schedule not found }
  /v1/queue/next-slot:
    get:
      operationId: getNextQueueSlot
      tags: [Queue]
      summary: Get next available slot
      description: Returns the next available queue slot for preview purposes. To create a queue post, use POST /v1/posts with queuedFromProfile instead of scheduledFor.
      parameters:
        - name: profileId
          in: query
          required: true
          schema: { type: string }
        - name: queueId
          in: query
          required: false
          schema: { type: string }
          description: Specific queue ID (optional, defaults to profile's default queue)
      responses:
        '200':
          description: Next available slot
          content:
            application/json:
              schema:
                type: object
                properties:
                  profileId: { type: string }
                  nextSlot: { type: string, format: date-time }
                  timezone: { type: string }
                  queueId: { type: string, description: Queue ID this slot belongs to }
                  queueName: { type: string, description: Queue name }
              example:
                profileId: "64f0a1b2c3d4e5f6a7b8c9d0"
                nextSlot: "2024-11-04T09:00:00-05:00"
                timezone: "America/New_York"
                queueId: "64f0a1b2c3d4e5f6a7b8c9d1"
                queueName: "Morning Posts"
        '400':
          description: Invalid parameters or inactive queue
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404':
          description: "Profile or queue schedule not found, or no available slots"
  # ============================================
  # Webhooks API (Multi-Webhook System)
  # ============================================
  /v1/webhooks/settings:
    get:
      operationId: getWebhookSettings
      tags: [Webhooks]
      summary: List webhooks
      description: Retrieve all configured webhooks for the authenticated user. Supports up to 10 webhooks per user.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Webhooks retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
              example:
                webhooks:
                  - _id: "507f1f77bcf86cd799439011"
                    name: "My Production Webhook"
                    url: "https://example.com/webhook"
                    events: ["post.published", "post.failed"]
                    isActive: true
                    lastFiredAt: "2024-01-15T10:30:00Z"
                    failureCount: 0
                  - _id: "507f1f77bcf86cd799439012"
                    name: "Slack Notifications"
                    url: "https://hooks.slack.com/services/xxx"
                    events: ["post.failed", "account.disconnected"]
                    isActive: true
                    failureCount: 0
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      operationId: createWebhookSettings
      tags: [Webhooks]
      summary: Create webhook
      description: |
        Create a new webhook configuration. Maximum 10 webhooks per user.

        Webhooks are automatically disabled after 10 consecutive delivery failures.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Webhook name (max 50 characters)
                  maxLength: 50
                url:
                  type: string
                  format: uri
                  description: Webhook endpoint URL (must be HTTPS in production)
                secret:
                  type: string
                  description: Secret key for HMAC-SHA256 signature verification
                events:
                  type: array
                  items:
                    type: string
                    enum: [post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled, account.connected, account.disconnected, message.received, comment.received]
                  description: Events to subscribe to
                isActive:
                  type: boolean
                  description: Enable or disable webhook delivery
                customHeaders:
                  type: object
                  additionalProperties:
                    type: string
                  description: Custom headers to include in webhook requests
            examples:
              createWebhook:
                summary: Create webhook with all events
                value:
                  name: "My Production Webhook"
                  url: "https://example.com/webhook"
                  secret: "your-secret-key"
                  events: ["post.scheduled", "post.published", "post.failed", "post.partial", "post.cancelled", "post.recycled", "account.connected", "account.disconnected", "message.received", "comment.received"]
                  isActive: true
      responses:
        '200':
          description: Webhook created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  webhook:
                    $ref: '#/components/schemas/Webhook'
        '400': { description: Validation error or maximum webhooks reached }
        '401': { $ref: '#/components/responses/Unauthorized' }
    put:
      operationId: updateWebhookSettings
      tags: [Webhooks]
      summary: Update webhook
      description: |
        Update an existing webhook configuration. All fields except _id are optional; only provided fields will be updated.

        Webhooks are automatically disabled after 10 consecutive delivery failures.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - _id
              properties:
                _id:
                  type: string
                  description: Webhook ID to update (required)
                name:
                  type: string
                  description: Webhook name (max 50 characters)
                  maxLength: 50
                url:
                  type: string
                  format: uri
                  description: Webhook endpoint URL (must be HTTPS in production)
                secret:
                  type: string
                  description: Secret key for HMAC-SHA256 signature verification
                events:
                  type: array
                  items:
                    type: string
                    enum: [post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled, account.connected, account.disconnected, message.received, comment.received]
                  description: Events to subscribe to
                isActive:
                  type: boolean
                  description: Enable or disable webhook delivery
                customHeaders:
                  type: object
                  additionalProperties:
                    type: string
                  description: Custom headers to include in webhook requests
            examples:
              updateWebhook:
                summary: Update webhook URL and events
                value:
                  _id: "507f1f77bcf86cd799439011"
                  url: "https://new-example.com/webhook"
                  events: ["post.published", "post.failed"]
              toggleWebhook:
                summary: Enable/disable webhook
                value:
                  _id: "507f1f77bcf86cd799439011"
                  isActive: false
      responses:
        '200':
          description: Webhook updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  webhook:
                    $ref: '#/components/schemas/Webhook'
        '400': { description: Validation error or missing webhook ID }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Webhook not found }
    delete:
      operationId: deleteWebhookSettings
      tags: [Webhooks]
      summary: Delete webhook
      description: Permanently delete a webhook configuration.
      security:
        - bearerAuth: []
      parameters:
        - name: id
          in: query
          required: true
          description: Webhook ID to delete
          schema:
            type: string
      responses:
        '200':
          description: Webhook deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
        '400': { description: Webhook ID required }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/webhooks/test:
    post:
      operationId: testWebhook
      tags: [Webhooks]
      summary: Send test webhook
      description: |
        Send a test webhook to verify your endpoint is configured correctly. The test payload includes event: "webhook.test" to distinguish it from real events.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - webhookId
              properties:
                webhookId:
                  type: string
                  description: ID of the webhook to test
            example:
              webhookId: "507f1f77bcf86cd799439011"
      responses:
        '200':
          description: Test webhook sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
              example:
                success: true
                message: "Test webhook sent successfully"
        '400': { description: Webhook ID required }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '500':
          description: Test webhook failed to deliver
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
              example:
                success: false
                message: "Test webhook failed"

  /v1/logs:
    get:
      operationId: listLogs
      tags: [Logs]
      summary: List activity logs
      description: |
        Unified logs endpoint. Returns logs for publishing, connections, webhooks, and messaging.
        Filter by type, platform, status, and time range. Logs are retained for 90 days.
      security:
        - bearerAuth: []
      parameters:
        - name: type
          in: query
          description: Log category to query
          schema:
            type: string
            enum: [publishing, connections, webhooks, messaging]
            default: publishing
        - name: status
          in: query
          description: Filter by status
          schema:
            type: string
            enum: [success, failed, pending, skipped, all]
        - name: platform
          in: query
          description: Filter by platform
          schema:
            type: string
            enum: [tiktok, instagram, whatsapp, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, all]
        - name: action
          in: query
          description: Filter by action (e.g., post.published, message.sent, account.connected, webhook.delivered)
          schema:
            type: string
        - name: search
          in: query
          description: Free-text search across log fields
          schema:
            type: string
        - name: days
          in: query
          description: Number of days to look back (max 90)
          schema:
            type: integer
            minimum: 1
            maximum: 90
            default: 90
        - name: limit
          in: query
          description: Maximum number of logs to return (max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: skip
          in: query
          description: Number of logs to skip (for pagination)
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Logs retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  logs:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          description: Log category (publishing, connections, webhooks, messaging)
                        action:
                          type: string
                          description: Specific action (post.published, message.sent, account.connected, etc.)
                        user_id:
                          type: string
                        platform:
                          type: string
                        account_id:
                          type: string
                        status:
                          type: string
                          enum: [success, failed, pending, skipped]
                        status_code:
                          type: integer
                        error_message:
                          type: string
                        error_code:
                          type: string
                        duration_ms:
                          type: integer
                        endpoint:
                          type: string
                          description: The API endpoint that triggered this log
                        request_body:
                          type: string
                          description: Request JSON (truncated to 5KB)
                        response_body:
                          type: string
                          description: Response JSON (truncated to 10KB)
                        created_at:
                          type: string
                          format: date-time
                        metadata:
                          type: string
                          description: Additional context as JSON string
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                      limit:
                        type: integer
                      skip:
                        type: integer
                      pages:
                        type: integer
                      hasMore:
                        type: boolean
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/webhooks/logs:
    get:
      operationId: getWebhookLogs
      tags: [Webhooks]
      summary: Get delivery logs
      deprecated: true
      description: |
        **Deprecated.** Use `GET /v1/logs?type=webhooks` instead.
        Retrieve webhook delivery history. Logs are retained for 90 days.
      security:
        - bearerAuth: []
      parameters:
        - name: limit
          in: query
          description: Maximum number of logs to return (max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: status
          in: query
          description: Filter by delivery status
          schema:
            type: string
            enum: [success, failed]
        - name: event
          in: query
          description: Filter by event type
          schema:
            type: string
            enum: [post.scheduled, post.published, post.failed, post.partial, post.cancelled, post.recycled, account.connected, account.disconnected, message.received, message.sent, comment.received, webhook.test]
        - name: webhookId
          in: query
          description: Filter by webhook ID
          schema:
            type: string
      responses:
        '200':
          description: Webhook logs retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  logs:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookLog'
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/posts/logs:
    get:
      operationId: listPostsLogs
      tags: [Logs]
      summary: List publishing logs
      deprecated: true
      description: |
        **Deprecated.** Use `GET /v1/logs?type=publishing` instead.
        Retrieve publishing logs for all posts. Logs are retained for 90 days.
      security:
        - bearerAuth: []
      parameters:
        - name: status
          in: query
          description: Filter by log status
          schema:
            type: string
            enum: [success, failed, pending, skipped, all]
        - name: platform
          in: query
          description: Filter by platform
          schema:
            type: string
            enum: [tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, all]
        - name: action
          in: query
          description: Filter by action type
          schema:
            type: string
            enum: [publish, retry, media_upload, rate_limit_pause, token_refresh, cancelled, all]
        - name: days
          in: query
          description: Number of days to look back (max 7)
          schema:
            type: integer
            minimum: 1
            maximum: 7
            default: 7
        - name: limit
          in: query
          description: Maximum number of logs to return (max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: skip
          in: query
          description: Number of logs to skip (for pagination)
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: search
          in: query
          description: Search through log entries by text content.
          schema:
            type: string
      responses:
        '200':
          description: Publishing logs retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  logs:
                    type: array
                    items:
                      $ref: '#/components/schemas/PostLog'
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                        description: Total number of logs matching the query
                      limit:
                        type: integer
                      skip:
                        type: integer
                      pages:
                        type: integer
                        description: Total number of pages
                      hasMore:
                        type: boolean
              example:
                logs:
                  - _id: "675f1c0a9e2b5af0012ab34cd"
                    postId:
                      _id: "65f1c0a9e2b5af0012ab34cd"
                      content: "Check out our new feature!"
                      status: "published"
                    userId: "64e1f0a9e2b5af0012ab34de"
                    platform: "instagram"
                    accountId: "64e1f0a9e2b5af0012ab34ef"
                    accountUsername: "@acmecorp"
                    action: "publish"
                    status: "success"
                    statusCode: 200
                    endpoint: "graph.facebook.com/me/media_publish"
                    request:
                      contentPreview: "Check out our new feature!"
                      mediaCount: 1
                      mediaTypes: ["image"]
                      mediaUrls: ["https://storage.zernio.com/abc123.jpg"]
                    response:
                      platformPostId: "17895695668004550"
                      platformPostUrl: "https://www.instagram.com/p/ABC123/"
                    durationMs: 2340
                    attemptNumber: 1
                    createdAt: "2024-11-01T10:00:05Z"
                pagination:
                  total: 150
                  limit: 50
                  skip: 0
                  pages: 3
                  hasMore: true
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/connections/logs:
    get:
      operationId: listConnectionLogs
      tags: [Logs]
      summary: List connection logs
      deprecated: true
      description: |
        **Deprecated.** Use `GET /v1/logs?type=connections` instead.
        Retrieve connection event logs. Logs are retained for 90 days.
      security:
        - bearerAuth: []
      parameters:
        - name: platform
          in: query
          description: Filter by platform
          schema:
            type: string
            enum: [tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, all]
        - name: eventType
          in: query
          description: Filter by event type
          schema:
            type: string
            enum: [connect_success, connect_failed, disconnect, reconnect_success, reconnect_failed, all]
        - name: status
          in: query
          description: Filter by status (shorthand for event types)
          schema:
            type: string
            enum: [success, failed, all]
            description: success = connect_success + reconnect_success, failed = connect_failed + reconnect_failed
        - name: days
          in: query
          description: Number of days to look back (max 7)
          schema:
            type: integer
            minimum: 1
            maximum: 7
            default: 7
        - name: limit
          in: query
          description: Maximum number of logs to return (max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: skip
          in: query
          description: Number of logs to skip (for pagination)
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        '200':
          description: Connection logs retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  logs:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConnectionLog'
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                        description: Total number of logs matching the query
                      limit:
                        type: integer
                      skip:
                        type: integer
                      pages:
                        type: integer
                        description: Total number of pages
                      hasMore:
                        type: boolean
              example:
                logs:
                  - _id: "675f1c0a9e2b5af0012ab34cd"
                    userId: "64e1f0a9e2b5af0012ab34de"
                    profileId: "64e1f0a9e2b5af0012ab34ef"
                    accountId: "64e1f0a9e2b5af0012ab3500"
                    platform: "instagram"
                    eventType: "connect_success"
                    connectionMethod: "oauth"
                    success:
                      displayName: "Acme Corp"
                      username: "acmecorp"
                      profilePicture: "https://..."
                      permissions: ["instagram_basic", "instagram_content_publish"]
                      tokenExpiresAt: "2024-12-01T10:00:00Z"
                      accountType: "business"
                    context:
                      hasCustomRedirectUrl: false
                    createdAt: "2024-11-01T10:00:00Z"
                  - _id: "675f1c0a9e2b5af0012ab34ce"
                    userId: "64e1f0a9e2b5af0012ab34de"
                    profileId: "64e1f0a9e2b5af0012ab34ef"
                    platform: "twitter"
                    eventType: "connect_failed"
                    connectionMethod: "oauth"
                    error:
                      code: "oauth_denied"
                      message: "OAuth error: access_denied"
                    context:
                      hasCustomRedirectUrl: true
                    createdAt: "2024-11-01T09:00:00Z"
                pagination:
                  total: 25
                  limit: 50
                  skip: 0
                  pages: 1
                  hasMore: false
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/posts/{postId}/logs:
    get:
      operationId: getPostLogs
      tags: [Logs]
      summary: Get post logs
      description: |
        Retrieve all publishing logs for a specific post. Shows the complete history
        of publishing attempts for that post across all platforms.
      security:
        - bearerAuth: []
      parameters:
        - name: postId
          in: path
          required: true
          description: The post ID
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of logs to return (max 100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
      responses:
        '200':
          description: Post logs retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  logs:
                    type: array
                    items:
                      $ref: '#/components/schemas/PostLog'
                  count:
                    type: integer
                    description: Number of logs returned
                  postId:
                    type: string
              example:
                logs:
                  - _id: "675f1c0a9e2b5af0012ab34cd"
                    postId: "65f1c0a9e2b5af0012ab34cd"
                    userId: "64e1f0a9e2b5af0012ab34de"
                    platform: "instagram"
                    accountUsername: "@acmecorp"
                    action: "publish"
                    status: "success"
                    statusCode: 200
                    durationMs: 2340
                    createdAt: "2024-11-01T10:00:05Z"
                  - _id: "675f1c0a9e2b5af0012ab34ce"
                    postId: "65f1c0a9e2b5af0012ab34cd"
                    userId: "64e1f0a9e2b5af0012ab34de"
                    platform: "twitter"
                    accountUsername: "@acme"
                    action: "publish"
                    status: "failed"
                    statusCode: 429
                    response:
                      errorMessage: "Rate limit exceeded"
                      errorCode: "RATE_LIMITED"
                    durationMs: 150
                    attemptNumber: 1
                    createdAt: "2024-11-01T10:00:03Z"
                count: 2
                postId: "65f1c0a9e2b5af0012ab34cd"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Forbidden - not authorized to view this post
        '404': { $ref: '#/components/responses/NotFound' }

  # Unified Inbox Endpoints
  /v1/inbox/conversations:
    get:
      operationId: listInboxConversations
      summary: List conversations
      description: |
        Fetch conversations (DMs) from all connected messaging accounts in a single API call. Supports filtering by profile and platform. Results are aggregated and deduplicated.
        Supported platforms: Facebook, Instagram, Twitter/X, Bluesky, Reddit, Telegram.

        **Twitter/X limitation:** X has replaced traditional DMs with encrypted "X Chat" for many accounts. Messages sent or received through encrypted X Chat are not accessible via X's API (the `/2/dm_events` endpoint only returns legacy unencrypted DMs). This means some Twitter/X conversations may show only outgoing messages or appear empty. This is an X platform limitation that affects all third-party applications. See [X's docs on encrypted messaging](https://help.x.com/en/using-x/about-chat) for more details.
      tags: [Messages]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: profileId
          in: query
          schema: { type: string }
          description: Filter by profile ID
        - name: platform
          in: query
          schema: { type: string, enum: [facebook, instagram, twitter, bluesky, reddit, telegram] }
          description: Filter by platform
        - name: status
          in: query
          schema: { type: string, enum: [active, archived] }
          description: Filter by conversation status
        - name: sortOrder
          in: query
          schema: { type: string, enum: [asc, desc], default: desc }
          description: Sort order by updated time
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
          description: Maximum number of conversations to return
        - name: cursor
          in: query
          schema: { type: string }
          description: Pagination cursor for next page
        - name: accountId
          in: query
          schema: { type: string }
          description: Filter by specific social account ID
      responses:
        '200':
          description: Aggregated conversations
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        platform: { type: string }
                        accountId: { type: string }
                        accountUsername: { type: string }
                        participantId: { type: string }
                        participantName: { type: string }
                        participantPicture: { type: string, nullable: true }
                        participantVerifiedType:
                          type: string
                          nullable: true
                          enum: [blue, government, business, none]
                          description: X/Twitter verified badge type. Only present for Twitter/X conversations.
                        lastMessage: { type: string }
                        updatedTime: { type: string, format: date-time }
                        status: { type: string, enum: [active, archived] }
                        unreadCount: { type: integer, nullable: true, description: Number of unread messages }
                        url:
                          type: string
                          nullable: true
                          description: Direct link to open the conversation on the platform (if available)
                        instagramProfile:
                          type: object
                          nullable: true
                          description: Instagram profile data for the participant. Only present for Instagram conversations.
                          properties:
                            isFollower:
                              type: boolean
                              nullable: true
                              description: Whether the participant follows your Instagram business account
                            isFollowing:
                              type: boolean
                              nullable: true
                              description: Whether your Instagram business account follows the participant
                            followerCount:
                              type: integer
                              nullable: true
                              description: The participant's follower count on Instagram
                            isVerified:
                              type: boolean
                              nullable: true
                              description: Whether the participant is a verified Instagram user
                            fetchedAt:
                              type: string
                              format: date-time
                              nullable: true
                              description: When this profile data was last fetched from Instagram
                  pagination:
                    type: object
                    properties:
                      hasMore: { type: boolean }
                      nextCursor: { type: string, nullable: true }
                  meta:
                    type: object
                    properties:
                      accountsQueried: { type: integer }
                      accountsFailed: { type: integer }
                      failedAccounts:
                        type: array
                        items:
                          type: object
                          properties:
                            accountId: { type: string }
                            accountUsername: { type: string, nullable: true }
                            platform: { type: string }
                            error: { type: string }
                            code: { type: string, nullable: true, description: Error code if available }
                            retryAfter: { type: integer, nullable: true, description: Seconds to wait before retry (rate limits) }
                      lastUpdated: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required
    post:
      operationId: createInboxConversation
      summary: Create conversation
      description: |
        Initiate a new direct message conversation with a specified user. If a conversation already exists with the recipient, the message is added to the existing thread.

        **Currently supported platforms:** Twitter/X only. Other platforms will return `PLATFORM_NOT_SUPPORTED`.

        **DM eligibility:** Before sending, the endpoint checks if the recipient accepts DMs from your account (via the `receives_your_dm` field). If not, a 422 error with code `DM_NOT_ALLOWED` is returned. You can skip this check with `skipDmCheck: true` if you have already verified eligibility.

        **X API tier requirement:** DM write endpoints require X API Pro tier ($5,000/month) or Enterprise access. This applies to BYOK (Bring Your Own Key) users who provide their own X API credentials.

        **Rate limits:** 200 requests per 15 minutes, 1,000 per 24 hours per user, 15,000 per 24 hours per app (shared across all DM endpoints).
      tags: [Messages]
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId]
              properties:
                accountId:
                  type: string
                  description: The social account ID to send from
                participantId:
                  type: string
                  description: Twitter numeric user ID of the recipient. Provide either this or `participantUsername`.
                participantUsername:
                  type: string
                  description: Twitter username (with or without @) of the recipient. Resolved to a user ID via lookup. Provide either this or `participantId`.
                message:
                  type: string
                  description: Text content of the message. At least one of `message` or attachment is required.
                skipDmCheck:
                  type: boolean
                  default: false
                  description: Skip the `receives_your_dm` eligibility check before sending. Use if you have already verified the recipient accepts DMs.
          multipart/form-data:
            schema:
              type: object
              required: [accountId]
              properties:
                accountId:
                  type: string
                  description: The social account ID to send from
                participantId:
                  type: string
                  description: Twitter numeric user ID of the recipient
                participantUsername:
                  type: string
                  description: Twitter username (with or without @) of the recipient
                message:
                  type: string
                  description: Text content of the message
                attachment:
                  type: string
                  format: binary
                  description: Media attachment (image or video). One attachment per message.
                skipDmCheck:
                  type: string
                  enum: ['true', 'false']
                  default: 'false'
                  description: Skip the DM eligibility check
      responses:
        '201':
          description: Conversation created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean, example: true }
                  data:
                    type: object
                    properties:
                      messageId:
                        type: string
                        description: Platform message ID (dm_event_id)
                      conversationId:
                        type: string
                        description: Platform conversation ID (dm_conversation_id)
                      participantId:
                        type: string
                        description: Twitter numeric user ID of the recipient
                      participantName:
                        type: string
                        nullable: true
                        description: Display name of the recipient
                      participantUsername:
                        type: string
                        nullable: true
                        description: Twitter username of the recipient
        '400':
          description: Validation error or platform not supported
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  code: { type: string, enum: [PLATFORM_NOT_SUPPORTED] }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required or profile limit reached
        '404':
          description: Account or recipient user not found
        '422':
          description: Recipient does not accept DMs from this account
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  code: { type: string, enum: [DM_NOT_ALLOWED] }
        '429':
          description: X API rate limit exceeded
  /v1/inbox/conversations/{conversationId}:
    get:
      operationId: getInboxConversation
      summary: Get conversation
      description: Retrieve details and metadata for a specific conversation. Requires accountId query parameter.
      tags: [Messages]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: conversationId
          in: path
          required: true
          schema: { type: string }
          description: The conversation ID (id field from list conversations endpoint). This is the platform-specific conversation identifier, not an internal database ID.
        - name: accountId
          in: query
          required: true
          schema: { type: string }
          description: The social account ID
      responses:
        '200':
          description: Conversation details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id: { type: string }
                      accountId: { type: string }
                      accountUsername: { type: string }
                      platform: { type: string }
                      status: { type: string, enum: [active, archived] }
                      participantName: { type: string }
                      participantId: { type: string }
                      participantVerifiedType:
                        type: string
                        nullable: true
                        enum: [blue, government, business, none]
                        description: X/Twitter verified badge type. Only present for Twitter/X conversations.
                      lastMessage: { type: string }
                      lastMessageAt: { type: string, format: date-time }
                      updatedTime: { type: string, format: date-time }
                      participants:
                        type: array
                        items:
                          type: object
                          properties:
                            id: { type: string }
                            name: { type: string }
                      instagramProfile:
                        type: object
                        nullable: true
                        description: Instagram profile data for the participant. Only present for Instagram conversations.
                        properties:
                          isFollower:
                            type: boolean
                            nullable: true
                            description: Whether the participant follows your Instagram business account
                          isFollowing:
                            type: boolean
                            nullable: true
                            description: Whether your Instagram business account follows the participant
                          followerCount:
                            type: integer
                            nullable: true
                            description: The participant's follower count on Instagram
                          isVerified:
                            type: boolean
                            nullable: true
                            description: Whether the participant is a verified Instagram user
                          fetchedAt:
                            type: string
                            format: date-time
                            nullable: true
                            description: When this profile data was last fetched from Instagram
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required
        '404':
          description: Conversation not found
    put:
      operationId: updateInboxConversation
      summary: Update conversation status
      description: Archive or activate a conversation. Requires accountId in request body.
      tags: [Messages]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: conversationId
          in: path
          required: true
          schema: { type: string }
          description: The conversation ID (id field from list conversations endpoint). This is the platform-specific conversation identifier, not an internal database ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId, status]
              properties:
                accountId: { type: string, description: Social account ID }
                status: { type: string, enum: [active, archived] }
      responses:
        '200':
          description: Conversation updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      id: { type: string }
                      accountId: { type: string }
                      status: { type: string, enum: [active, archived] }
                      platform: { type: string }
                      updatedAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required

  /v1/inbox/conversations/{conversationId}/messages:
    get:
      operationId: getInboxConversationMessages
      summary: List messages
      description: |
        Fetch messages for a specific conversation. Requires accountId query parameter.

        **Twitter/X limitation:** X's encrypted "X Chat" messages are not accessible via the API. Conversations where the other participant uses encrypted X Chat may only show your outgoing messages. See the [list conversations endpoint](#/Messages/listInboxConversations) for more details.
      tags: [Messages]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: conversationId
          in: path
          required: true
          schema: { type: string }
          description: The conversation ID (id field from list conversations endpoint). This is the platform-specific conversation identifier, not an internal database ID.
        - name: accountId
          in: query
          required: true
          schema: { type: string }
          description: Social account ID
      responses:
        '200':
          description: Messages in conversation
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string }
                  messages:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        conversationId: { type: string }
                        accountId: { type: string }
                        platform: { type: string }
                        message: { type: string }
                        senderId: { type: string }
                        senderName: { type: string, nullable: true }
                        senderVerifiedType:
                          type: string
                          nullable: true
                          enum: [blue, government, business, none]
                          description: X/Twitter verified badge type. Only present for Twitter/X messages.
                        direction: { type: string, enum: [incoming, outgoing] }
                        createdAt: { type: string, format: date-time }
                        attachments:
                          type: array
                          items:
                            type: object
                            properties:
                              id: { type: string }
                              type: { type: string, enum: [image, video, audio, file, sticker, share] }
                              url: { type: string }
                              filename: { type: string, nullable: true }
                              previewUrl: { type: string, nullable: true }
                        subject: { type: string, nullable: true, description: Reddit message subject }
                        storyReply: { type: boolean, nullable: true, description: Instagram story reply }
                        isStoryMention: { type: boolean, nullable: true, description: Instagram story mention }
                  lastUpdated: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required
    post:
      operationId: sendInboxMessage
      summary: Send message
      description: Send a message in a conversation. Supports text, attachments, quick replies, buttons, and message tags. Attachment and interactive message support varies by platform.
      tags: [Messages]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: conversationId
          in: path
          required: true
          schema: { type: string }
          description: The conversation ID (id field from list conversations endpoint). This is the platform-specific conversation identifier, not an internal database ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId]
              properties:
                accountId: { type: string, description: Social account ID }
                message: { type: string, description: Message text }
                attachmentUrl: { type: string, description: "URL of the attachment to send (image, video, audio, or file). The URL must be publicly accessible. For binary file uploads, use multipart/form-data instead." }
                attachmentType:
                  type: string
                  enum: [image, video, audio, file]
                  description: "Type of attachment. Defaults to file if not specified."
                quickReplies:
                  type: array
                  maxItems: 13
                  description: Quick reply buttons. Mutually exclusive with buttons. Max 13 items.
                  items:
                    type: object
                    required: [title, payload]
                    properties:
                      title: { type: string, maxLength: 20, description: Button label (max 20 chars) }
                      payload: { type: string, description: Payload sent back on tap }
                      imageUrl: { type: string, description: Optional icon URL (Meta only) }
                buttons:
                  type: array
                  maxItems: 3
                  description: Action buttons. Mutually exclusive with quickReplies. Max 3 items.
                  items:
                    type: object
                    required: [type, title]
                    properties:
                      type: { type: string, enum: [url, postback, phone], description: Button type. phone is Facebook only. }
                      title: { type: string, maxLength: 20, description: Button label (max 20 chars) }
                      url: { type: string, description: URL for url-type buttons }
                      payload: { type: string, description: Payload for postback-type buttons }
                      phone: { type: string, description: Phone number for phone-type buttons (Facebook only) }
                template:
                  type: object
                  description: Generic template for carousels (Instagram/Facebook only, ignored on Telegram).
                  properties:
                    type: { type: string, enum: [generic], description: Template type }
                    elements:
                      type: array
                      maxItems: 10
                      items:
                        type: object
                        required: [title]
                        properties:
                          title: { type: string, maxLength: 80, description: Element title (max 80 chars) }
                          subtitle: { type: string, description: Element subtitle }
                          imageUrl: { type: string, description: Element image URL }
                          buttons:
                            type: array
                            maxItems: 3
                            items:
                              type: object
                              properties:
                                type: { type: string, enum: [url, postback] }
                                title: { type: string, maxLength: 20 }
                                url: { type: string }
                                payload: { type: string }
                replyMarkup:
                  type: object
                  description: Telegram-native keyboard markup. Ignored on other platforms.
                  properties:
                    type: { type: string, enum: [inline_keyboard, reply_keyboard], description: Keyboard type }
                    keyboard:
                      type: array
                      description: Array of rows, each row is an array of buttons
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            text: { type: string, description: Button text }
                            callbackData: { type: string, maxLength: 64, description: Callback data (inline_keyboard only, max 64 bytes) }
                            url: { type: string, description: URL to open (inline_keyboard only) }
                    oneTime: { type: boolean, default: true, description: Hide keyboard after use (reply_keyboard only) }
                messagingType:
                  type: string
                  enum: [RESPONSE, UPDATE, MESSAGE_TAG]
                  description: Facebook messaging type. Required when using messageTag.
                messageTag:
                  type: string
                  enum: [CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE, ACCOUNT_UPDATE, HUMAN_AGENT]
                  description: Facebook message tag for messaging outside 24h window. Requires messagingType MESSAGE_TAG. Instagram only supports HUMAN_AGENT.
                replyTo:
                  type: string
                  description: Platform message ID to reply to (Telegram only).
          multipart/form-data:
            schema:
              type: object
              required: [accountId]
              properties:
                accountId: { type: string, description: Social account ID }
                message: { type: string, description: Message text (optional when sending attachment) }
                attachment:
                  type: string
                  format: binary
                  description: "File attachment (images, videos, documents). Supported formats: JPEG, PNG, GIF, MP4, AAC, WAV. Max 25MB."
                quickReplies:
                  type: string
                  description: JSON string of quick replies array (same schema as application/json body)
                buttons:
                  type: string
                  description: JSON string of buttons array (same schema as application/json body)
                template:
                  type: string
                  description: JSON string of template object (same schema as application/json body)
                replyMarkup:
                  type: string
                  description: JSON string of replyMarkup object (same schema as application/json body)
                messagingType:
                  type: string
                  description: Messaging type (Facebook only). RESPONSE, UPDATE, or MESSAGE_TAG.
                messageTag:
                  type: string
                  description: Message tag (requires messagingType MESSAGE_TAG)
                replyTo:
                  type: string
                  description: Platform message ID to reply to (Telegram only)
      responses:
        '200':
          description: Message sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      messageId: { type: string, description: ID of the sent message (not returned for Reddit) }
                      conversationId: { type: string, nullable: true, description: Twitter conversation ID }
                      sentAt: { type: string, format: date-time, nullable: true, description: Bluesky sent timestamp }
                      message: { type: string, nullable: true, description: Success message (Reddit only) }
        '400':
          description: Bad request (e.g., attachment not supported for platform, validation error)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
                  code:
                    type: string
                    enum: [PLATFORM_LIMITATION]
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required

  /v1/inbox/conversations/{conversationId}/messages/{messageId}:
    patch:
      operationId: editInboxMessage
      summary: Edit message
      description: |
        Edit the text and/or reply markup of a previously sent Telegram message.
        Only supported for Telegram. Returns 400 for other platforms.
      tags: [Messages]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: conversationId
          in: path
          required: true
          schema: { type: string }
          description: The conversation ID
        - name: messageId
          in: path
          required: true
          schema: { type: string }
          description: The Telegram message ID to edit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId]
              properties:
                accountId: { type: string, description: Social account ID }
                text: { type: string, description: New message text }
                replyMarkup:
                  type: object
                  description: New inline keyboard markup
                  properties:
                    type: { type: string, enum: [inline_keyboard] }
                    keyboard:
                      type: array
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            text: { type: string }
                            callbackData: { type: string }
                            url: { type: string }
      responses:
        '200':
          description: Message edited
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      messageId: { type: integer }
        '400':
          description: Not supported or invalid request
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required
    delete:
      operationId: deleteInboxMessage
      summary: Delete message
      description: |
        Delete a message from a conversation. Platform support varies:
        - **Telegram**: Full delete (bot's own messages anytime, others if admin)
        - **X/Twitter**: Full delete (own DM events only)
        - **Bluesky**: Delete for self only (recipient still sees it)
        - **Reddit**: Delete from sender's view only
        - **Facebook, Instagram, WhatsApp**: Not supported (returns 400)
      tags: [Messages]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: conversationId
          in: path
          required: true
          schema: { type: string }
          description: The conversation ID
        - name: messageId
          in: path
          required: true
          schema: { type: string }
          description: The platform message ID to delete
        - name: accountId
          in: query
          required: true
          schema: { type: string }
          description: Social account ID
      responses:
        '200':
          description: Message deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
        '400':
          description: Platform does not support deletion or invalid request
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required
        '404':
          description: Account or conversation not found

  /v1/inbox/conversations/{conversationId}/typing:
    post:
      operationId: sendTypingIndicator
      summary: Send typing indicator
      description: |
        Show a typing indicator in a conversation. Platform support:
        - **Facebook Messenger**: Shows "Page is typing..." for 20 seconds
        - **Telegram**: Shows "Bot is typing..." for 5 seconds
        - **All others**: Returns 200 but no-op (platform doesn't support it)

        Typing indicators are best-effort. The endpoint always returns 200 even if the platform call fails.
      tags: [Messages]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: conversationId
          in: path
          required: true
          schema: { type: string }
          description: The conversation ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId]
              properties:
                accountId: { type: string, description: Social account ID }
      responses:
        '200':
          description: Typing indicator sent (or no-op on unsupported platforms)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required
        '404':
          description: Account or conversation not found

  /v1/inbox/conversations/{conversationId}/messages/{messageId}/reactions:
    post:
      operationId: addMessageReaction
      summary: Add reaction
      description: |
        Add an emoji reaction to a message. Platform support:
        - **Telegram**: Supports a subset of Unicode emoji reactions
        - **WhatsApp**: Supports any standard emoji (one reaction per message per sender)
        - **All others**: Returns 400 (not supported)
      tags: [Messages]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: conversationId
          in: path
          required: true
          schema: { type: string }
          description: The conversation ID
        - name: messageId
          in: path
          required: true
          schema: { type: string }
          description: The platform message ID to react to
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId, emoji]
              properties:
                accountId: { type: string, description: Social account ID }
                emoji: { type: string, description: 'Emoji character (e.g. "👍", "❤️")', example: '👍' }
      responses:
        '200':
          description: Reaction added
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
        '400':
          description: Platform does not support reactions or invalid request
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required
        '404':
          description: Account or conversation not found
    delete:
      operationId: removeMessageReaction
      summary: Remove reaction
      description: |
        Remove a reaction from a message. Platform support:
        - **Telegram**: Send empty reaction array to clear
        - **WhatsApp**: Send empty emoji to remove
        - **All others**: Returns 400 (not supported)
      tags: [Messages]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: conversationId
          in: path
          required: true
          schema: { type: string }
          description: The conversation ID
        - name: messageId
          in: path
          required: true
          schema: { type: string }
          description: The platform message ID
        - name: accountId
          in: query
          required: true
          schema: { type: string }
          description: Social account ID
      responses:
        '200':
          description: Reaction removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
        '400':
          description: Platform does not support reactions or invalid request
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required
        '404':
          description: Account or conversation not found

  /v1/media/upload-direct:
    post:
      operationId: uploadMediaDirect
      summary: Upload media file
      description: |
        Upload a media file using API key authentication and get back a publicly accessible URL.
        The URL can be used as `attachmentUrl` when sending inbox messages.

        Files are stored in temporary storage and auto-delete after 7 days.
        Maximum file size is 25MB.

        Unlike `/v1/media/upload` (which uses upload tokens for end-user flows),
        this endpoint uses standard Bearer token authentication for programmatic use.
      tags: [Messages]
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload (max 25MB)
                contentType:
                  type: string
                  description: 'Override MIME type (e.g. "image/jpeg"). Auto-detected from file if not provided.'
      responses:
        '200':
          description: File uploaded successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  url: { type: string, description: Publicly accessible URL for the uploaded file }
                  filename: { type: string, description: Generated unique filename }
                  contentType: { type: string, description: MIME type of the file }
                  size: { type: integer, description: File size in bytes }
        '400':
          description: No file provided or file too large
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/accounts/{accountId}/messenger-menu:
    get:
      operationId: getMessengerMenu
      summary: Get FB persistent menu
      description: Get the persistent menu configuration for a Facebook Messenger account.
      tags: [Account Settings]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Persistent menu configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { type: object } }
        '400':
          description: Not a Facebook account
        '401': { $ref: '#/components/responses/Unauthorized' }
    put:
      operationId: setMessengerMenu
      summary: Set FB persistent menu
      description: Set the persistent menu for a Facebook Messenger account. Max 3 top-level items, max 5 nested items.
      tags: [Account Settings]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [persistent_menu]
              properties:
                persistent_menu:
                  type: array
                  description: Persistent menu configuration array (Meta format)
                  items: { type: object }
      responses:
        '200':
          description: Menu set successfully
        '400':
          description: Invalid request
        '401': { $ref: '#/components/responses/Unauthorized' }
    delete:
      operationId: deleteMessengerMenu
      description: Removes the persistent menu from Facebook Messenger conversations for this account.
      summary: Delete FB persistent menu
      tags: [Account Settings]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Menu deleted
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/accounts/{accountId}/instagram-ice-breakers:
    get:
      operationId: getInstagramIceBreakers
      summary: Get IG ice breakers
      description: Get the ice breaker configuration for an Instagram account.
      tags: [Account Settings]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Ice breaker configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { type: object } }
        '400':
          description: Not an Instagram account
        '401': { $ref: '#/components/responses/Unauthorized' }
    put:
      operationId: setInstagramIceBreakers
      summary: Set IG ice breakers
      description: Set ice breakers for an Instagram account. Max 4 ice breakers, question max 80 chars.
      tags: [Account Settings]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [ice_breakers]
              properties:
                ice_breakers:
                  type: array
                  maxItems: 4
                  items:
                    type: object
                    required: [question, payload]
                    properties:
                      question: { type: string, maxLength: 80 }
                      payload: { type: string }
      responses:
        '200':
          description: Ice breakers set successfully
        '400':
          description: Invalid request
        '401': { $ref: '#/components/responses/Unauthorized' }
    delete:
      operationId: deleteInstagramIceBreakers
      description: Removes the ice breaker questions from an Instagram account's Messenger experience.
      summary: Delete IG ice breakers
      tags: [Account Settings]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Ice breakers deleted
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/accounts/{accountId}/telegram-commands:
    get:
      operationId: getTelegramCommands
      summary: Get TG bot commands
      description: Get the bot commands configuration for a Telegram account.
      tags: [Account Settings]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Bot commands list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        command: { type: string }
                        description: { type: string }
        '400':
          description: Not a Telegram account
        '401': { $ref: '#/components/responses/Unauthorized' }
    put:
      operationId: setTelegramCommands
      summary: Set TG bot commands
      description: Set bot commands for a Telegram account.
      tags: [Account Settings]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [commands]
              properties:
                commands:
                  type: array
                  items:
                    type: object
                    required: [command, description]
                    properties:
                      command: { type: string, description: Bot command without leading slash }
                      description: { type: string, description: Command description }
      responses:
        '200':
          description: Commands set successfully
        '400':
          description: Invalid request
        '401': { $ref: '#/components/responses/Unauthorized' }
    delete:
      operationId: deleteTelegramCommands
      description: Clears all bot commands configured for a Telegram bot account.
      summary: Delete TG bot commands
      tags: [Account Settings]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: accountId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Commands deleted
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/inbox/comments:
    get:
      operationId: listInboxComments
      summary: List commented posts
      description: Returns posts with comment counts from all connected accounts. Aggregates data across multiple accounts.
      tags: [Comments]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: profileId
          in: query
          schema: { type: string }
          description: Filter by profile ID
        - name: platform
          in: query
          schema: { type: string, enum: [facebook, instagram, twitter, bluesky, threads, youtube, linkedin, reddit] }
          description: Filter by platform
        - name: minComments
          in: query
          schema: { type: integer, minimum: 0 }
          description: Minimum comment count
        - name: since
          in: query
          schema: { type: string, format: date-time }
          description: Posts created after this date
        - name: sortBy
          in: query
          schema: { type: string, enum: [date, comments], default: date }
          description: Sort field
        - name: sortOrder
          in: query
          schema: { type: string, enum: [asc, desc], default: desc }
          description: Sort order
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
        - name: cursor
          in: query
          schema: { type: string }
        - name: accountId
          in: query
          schema: { type: string }
          description: Filter by specific social account ID
      responses:
        '200':
          description: Aggregated posts with comments
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        platform: { type: string }
                        accountId: { type: string }
                        accountUsername: { type: string }
                        content: { type: string }
                        picture: { type: string, nullable: true }
                        permalink: { type: string, nullable: true }
                        createdTime: { type: string, format: date-time }
                        commentCount: { type: integer }
                        likeCount: { type: integer }
                        cid: { type: string, nullable: true, description: Bluesky content identifier }
                        subreddit: { type: string, nullable: true, description: Reddit subreddit name }
                  pagination:
                    type: object
                    properties:
                      hasMore: { type: boolean }
                      nextCursor: { type: string, nullable: true }
                  meta:
                    type: object
                    properties:
                      accountsQueried: { type: integer }
                      accountsFailed: { type: integer }
                      failedAccounts:
                        type: array
                        items:
                          type: object
                          properties:
                            accountId: { type: string }
                            accountUsername: { type: string, nullable: true }
                            platform: { type: string }
                            error: { type: string }
                            code: { type: string, nullable: true, description: Error code if available }
                            retryAfter: { type: integer, nullable: true, description: Seconds to wait before retry (rate limits) }
                      lastUpdated: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required

  /v1/inbox/comments/{postId}:
    get:
      operationId: getInboxPostComments
      summary: Get post comments
      description: Fetch comments for a specific post. Requires accountId query parameter.
      tags: [Comments]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: postId
          in: path
          required: true
          description: Zernio post ID or platform-specific post ID. Zernio IDs are auto-resolved. LinkedIn third-party posts accept full activity URN or numeric ID.
          schema: { type: string }
        - name: accountId
          in: query
          required: true
          schema: { type: string }
        - name: subreddit
          in: query
          schema: { type: string }
          description: (Reddit only) Subreddit name
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 25 }
          description: Maximum number of comments to return
        - name: cursor
          in: query
          schema: { type: string }
          description: Pagination cursor
        - name: commentId
          in: query
          schema: { type: string }
          description: (Reddit only) Get replies to a specific comment
      responses:
        '200':
          description: Comments for the post
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string }
                  comments:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        message: { type: string }
                        createdTime: { type: string, format: date-time }
                        from:
                          type: object
                          properties:
                            id: { type: string }
                            name: { type: string }
                            username: { type: string }
                            picture: { type: string, nullable: true }
                            isOwner: { type: boolean }
                            verifiedType:
                              type: string
                              nullable: true
                              enum: [blue, government, business, none]
                              description: X/Twitter verified badge type. Only present for Twitter/X comments.
                        likeCount: { type: integer }
                        replyCount: { type: integer }
                        platform: { type: string, description: The platform this comment is from }
                        url:
                          type: string
                          nullable: true
                          description: Direct link to the comment on the platform (if available)
                        replies:
                          type: array
                          items: { type: object }
                        canReply: { type: boolean }
                        canDelete: { type: boolean }
                        canHide: { type: boolean, description: Whether this comment can be hidden (Facebook, Instagram, Threads) }
                        canLike: { type: boolean, description: Whether this comment can be liked (Facebook, Twitter/X, Bluesky, Reddit) }
                        isHidden: { type: boolean, description: Whether the comment is currently hidden }
                        isLiked: { type: boolean, description: Whether the current user has liked this comment }
                        likeUri: { type: string, nullable: true, description: Bluesky like URI for unliking }
                        cid: { type: string, nullable: true, description: Bluesky content identifier }
                        parentId: { type: string, nullable: true, description: Parent comment ID for nested replies }
                        rootUri: { type: string, nullable: true, description: Bluesky root post URI }
                        rootCid: { type: string, nullable: true, description: Bluesky root post CID }
                  pagination:
                    type: object
                    properties:
                      hasMore: { type: boolean }
                      cursor: { type: string, nullable: true }
                  meta:
                    type: object
                    properties:
                      platform: { type: string }
                      postId: { type: string }
                      accountId: { type: string }
                      subreddit: { type: string, nullable: true, description: (Reddit only) Subreddit name }
                      lastUpdated: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required
    post:
      operationId: replyToInboxPost
      summary: Reply to comment
      description: Post a reply to a post or specific comment. Requires accountId in request body.
      tags: [Comments]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: postId
          in: path
          required: true
          description: Zernio post ID or platform-specific post ID. LinkedIn third-party posts accept full activity URN or numeric ID.
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId, message]
              properties:
                accountId: { type: string }
                message: { type: string }
                commentId: { type: string, description: Reply to specific comment (optional) }
                parentCid: { type: string, description: (Bluesky only) Parent content identifier }
                rootUri: { type: string, description: (Bluesky only) Root post URI }
                rootCid: { type: string, description: (Bluesky only) Root post CID }
      responses:
        '200':
          description: Reply posted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      commentId: { type: string }
                      isReply: { type: boolean }
                      cid: { type: string, nullable: true, description: Bluesky CID }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required
    delete:
      operationId: deleteInboxComment
      summary: Delete comment
      description: |
        Delete a comment on a post. Supported by Facebook, Instagram, Bluesky, Reddit, YouTube, and LinkedIn.
        Requires accountId and commentId query parameters.
      tags: [Comments]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: postId
          in: path
          required: true
          description: Zernio post ID or platform-specific post ID. LinkedIn third-party posts accept full activity URN or numeric ID.
          schema: { type: string }
        - name: accountId
          in: query
          required: true
          schema: { type: string }
        - name: commentId
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Comment deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  data:
                    type: object
                    properties:
                      message: { type: string }
        '400':
          description: Platform rejected the operation (e.g., comment already deleted, insufficient permissions on the video)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required

  /v1/inbox/comments/{postId}/{commentId}/hide:
    post:
      operationId: hideInboxComment
      summary: Hide comment
      description: |
        Hide a comment on a post. Supported by Facebook, Instagram, Threads, and X/Twitter.
        Hidden comments are only visible to the commenter and page admin.
        For X/Twitter, the reply must belong to a conversation started by the authenticated user.
      tags: [Comments]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: postId
          in: path
          required: true
          schema: { type: string }
        - name: commentId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId]
              properties:
                accountId: { type: string, description: The social account ID }
      responses:
        '200':
          description: Comment hidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string }
                  commentId: { type: string }
                  hidden: { type: boolean }
                  platform: { type: string }
        '400':
          description: Platform does not support hiding comments
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required
    delete:
      operationId: unhideInboxComment
      summary: Unhide comment
      description: |
        Unhide a previously hidden comment. Supported by Facebook, Instagram, Threads, and X/Twitter.
      tags: [Comments]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: postId
          in: path
          required: true
          schema: { type: string }
        - name: commentId
          in: path
          required: true
          schema: { type: string }
        - name: accountId
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Comment unhidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string }
                  commentId: { type: string }
                  hidden: { type: boolean }
                  platform: { type: string }
        '400':
          description: Platform does not support unhiding comments
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required

  /v1/inbox/comments/{postId}/{commentId}/like:
    post:
      operationId: likeInboxComment
      summary: Like comment
      description: |
        Like or upvote a comment on a post. Supported platforms: Facebook, Twitter/X, Bluesky, Reddit.
        For Bluesky, the cid (content identifier) is required in the request body.
      tags: [Comments]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: postId
          in: path
          required: true
          schema: { type: string }
        - name: commentId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId]
              properties:
                accountId: { type: string, description: The social account ID }
                cid: { type: string, description: (Bluesky only) Content identifier for the comment }
      responses:
        '200':
          description: Comment liked
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string }
                  commentId: { type: string }
                  liked: { type: boolean }
                  likeUri: { type: string, description: (Bluesky only) URI to use for unliking }
                  platform: { type: string }
        '400':
          description: Platform does not support liking comments
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required
    delete:
      operationId: unlikeInboxComment
      summary: Unlike comment
      description: |
        Remove a like from a comment. Supported platforms: Facebook, Twitter/X, Bluesky, Reddit.
        For Bluesky, the likeUri query parameter is required.
      tags: [Comments]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: postId
          in: path
          required: true
          schema: { type: string }
        - name: commentId
          in: path
          required: true
          schema: { type: string }
        - name: accountId
          in: query
          required: true
          schema: { type: string }
        - name: likeUri
          in: query
          schema: { type: string }
          description: (Bluesky only) The like URI returned when liking
      responses:
        '200':
          description: Comment unliked
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string }
                  commentId: { type: string }
                  liked: { type: boolean }
                  platform: { type: string }
        '400':
          description: Platform does not support unliking comments
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required

  /v1/inbox/comments/{postId}/{commentId}/private-reply:
    post:
      operationId: sendPrivateReplyToComment
      summary: Send private reply
      description: Send a private message to the author of a comment. Supported on Instagram and Facebook only. One reply per comment, must be sent within 7 days, text only.
      tags: [Comments]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: postId
          in: path
          required: true
          schema: { type: string }
          description: The media/post ID (Instagram media ID or Facebook post ID)
        - name: commentId
          in: path
          required: true
          schema: { type: string }
          description: The comment ID to send a private reply to
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId, message]
              properties:
                accountId:
                  type: string
                  description: The social account ID (Instagram or Facebook)
                message:
                  type: string
                  description: The message text to send as a private DM
            example:
              accountId: "507f1f77bcf86cd799439011"
              message: "Hi! Thanks for your comment. I wanted to reach out privately to help with your question."
      responses:
        '200':
          description: Private reply sent successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  messageId:
                    type: string
                    description: The ID of the sent message
                  commentId:
                    type: string
                    description: The comment ID that was replied to
                  platform:
                    type: string
                    enum: [instagram, facebook]
                    example: instagram
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                    enum: [PLATFORM_LIMITATION]
              examples:
                platformNotSupported:
                  summary: Platform not supported
                  value:
                    error: "Private replies to comments are only supported on Instagram and Facebook."
                    code: "PLATFORM_LIMITATION"
                alreadyReplied:
                  summary: Already sent a private reply
                  value:
                    error: "A private reply has already been sent to this comment, or the 7-day reply window has expired. Only one private reply per comment is allowed within 7 days."
                commentTooOld:
                  summary: Comment older than 7 days
                  value:
                    error: "The comment is older than 7 days. Private replies can only be sent within 7 days of the comment being posted."
                missingMessage:
                  summary: Missing message
                  value:
                    error: "message is required and must be a non-empty string"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required
        '404':
          description: Account not found

  /v1/twitter/retweet:
    post:
      operationId: retweetPost
      summary: Retweet a post
      description: |
        Retweet (repost) a tweet by ID.
        Rate limit: 50 requests per 15-min window. Shares the 300/3hr creation limit with tweet creation.
      tags: [Twitter Engagement]
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId, tweetId]
              properties:
                accountId: { type: string, description: The social account ID }
                tweetId: { type: string, description: The ID of the tweet to retweet }
      responses:
        '200':
          description: Tweet retweeted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, example: success }
                  tweetId: { type: string }
                  retweeted: { type: boolean }
                  platform: { type: string, example: twitter }
        '400': { description: Bad request or platform limitation }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }
    delete:
      operationId: undoRetweet
      summary: Undo retweet
      description: |
        Undo a retweet (un-repost a tweet).
      tags: [Twitter Engagement]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: accountId
          in: query
          required: true
          schema: { type: string }
        - name: tweetId
          in: query
          required: true
          schema: { type: string }
          description: The ID of the original tweet to un-retweet
      responses:
        '200':
          description: Retweet undone
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, example: success }
                  tweetId: { type: string }
                  retweeted: { type: boolean, example: false }
                  platform: { type: string, example: twitter }
        '400': { description: Bad request }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }

  /v1/twitter/bookmark:
    post:
      operationId: bookmarkPost
      summary: Bookmark a tweet
      description: |
        Bookmark a tweet by ID.
        Requires the bookmark.write OAuth scope.
        Rate limit: 50 requests per 15-min window.
      tags: [Twitter Engagement]
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId, tweetId]
              properties:
                accountId: { type: string, description: The social account ID }
                tweetId: { type: string, description: The ID of the tweet to bookmark }
      responses:
        '200':
          description: Tweet bookmarked
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, example: success }
                  tweetId: { type: string }
                  bookmarked: { type: boolean }
                  platform: { type: string, example: twitter }
        '400': { description: Bad request or platform limitation }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }
    delete:
      operationId: removeBookmark
      summary: Remove bookmark
      description: |
        Remove a bookmark from a tweet.
      tags: [Twitter Engagement]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: accountId
          in: query
          required: true
          schema: { type: string }
        - name: tweetId
          in: query
          required: true
          schema: { type: string }
          description: The ID of the tweet to unbookmark
      responses:
        '200':
          description: Bookmark removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, example: success }
                  tweetId: { type: string }
                  bookmarked: { type: boolean, example: false }
                  platform: { type: string, example: twitter }
        '400': { description: Bad request }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }

  /v1/twitter/follow:
    post:
      operationId: followUser
      summary: Follow a user
      description: |
        Follow a user on X/Twitter.
        Requires the follows.write OAuth scope.
        For protected accounts, a follow request is sent instead (pending_follow will be true).
      tags: [Twitter Engagement]
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId, targetUserId]
              properties:
                accountId: { type: string, description: The social account ID }
                targetUserId: { type: string, description: The Twitter ID of the user to follow }
      responses:
        '200':
          description: User followed or follow request sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, example: success }
                  targetUserId: { type: string }
                  following: { type: boolean }
                  pending_follow: { type: boolean, description: True if the target account is protected and a follow request was sent }
                  platform: { type: string, example: twitter }
        '400': { description: Bad request or platform limitation }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }
    delete:
      operationId: unfollowUser
      summary: Unfollow a user
      description: |
        Unfollow a user on X/Twitter.
      tags: [Twitter Engagement]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: accountId
          in: query
          required: true
          schema: { type: string }
        - name: targetUserId
          in: query
          required: true
          schema: { type: string }
          description: The Twitter ID of the user to unfollow
      responses:
        '200':
          description: User unfollowed
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string, example: success }
                  targetUserId: { type: string }
                  following: { type: boolean, example: false }
                  platform: { type: string, example: twitter }
        '400': { description: Bad request }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Account not found }

  /v1/inbox/reviews:
    get:
      operationId: listInboxReviews
      summary: List reviews
      description: |
        Fetch reviews from all connected Facebook Pages and Google Business accounts. Aggregates data with filtering and sorting options.
        Supported platforms: Facebook, Google Business.
      tags: [Reviews]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: profileId
          in: query
          schema: { type: string }
        - name: platform
          in: query
          schema: { type: string, enum: [facebook, googlebusiness] }
        - name: minRating
          in: query
          schema: { type: integer, minimum: 1, maximum: 5 }
        - name: maxRating
          in: query
          schema: { type: integer, minimum: 1, maximum: 5 }
        - name: hasReply
          in: query
          schema: { type: boolean }
          description: Filter by reply status
        - name: sortBy
          in: query
          schema: { type: string, enum: [date, rating], default: date }
        - name: sortOrder
          in: query
          schema: { type: string, enum: [asc, desc], default: desc }
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 50, default: 25 }
        - name: cursor
          in: query
          schema: { type: string }
        - name: accountId
          in: query
          schema: { type: string }
          description: Filter by specific social account ID
      responses:
        '200':
          description: Aggregated reviews
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string }
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        platform: { type: string }
                        accountId: { type: string }
                        accountUsername: { type: string }
                        reviewer:
                          type: object
                          properties:
                            id: { type: string, nullable: true }
                            name: { type: string }
                            profileImage: { type: string, nullable: true }
                        rating: { type: integer }
                        text: { type: string }
                        created: { type: string, format: date-time }
                        hasReply: { type: boolean }
                        reply:
                          type: object
                          nullable: true
                          properties:
                            id: { type: string }
                            text: { type: string }
                            created: { type: string, format: date-time }
                        reviewUrl: { type: string, nullable: true }
                  pagination:
                    type: object
                    properties:
                      hasMore: { type: boolean }
                      nextCursor: { type: string, nullable: true }
                  meta:
                    type: object
                    properties:
                      accountsQueried: { type: integer }
                      accountsFailed: { type: integer }
                      failedAccounts:
                        type: array
                        items:
                          type: object
                          properties:
                            accountId: { type: string }
                            accountUsername: { type: string, nullable: true }
                            platform: { type: string }
                            error: { type: string }
                            code: { type: string, nullable: true, description: Error code if available }
                            retryAfter: { type: integer, nullable: true, description: Seconds to wait before retry (rate limits) }
                      lastUpdated: { type: string, format: date-time }
                  summary:
                    type: object
                    properties:
                      totalReviews: { type: integer }
                      averageRating: { type: number, nullable: true }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required

  /v1/inbox/reviews/{reviewId}/reply:
    post:
      operationId: replyToInboxReview
      summary: Reply to review
      description: Post a reply to a review. Requires accountId in request body.
      tags: [Reviews]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: reviewId
          in: path
          required: true
          schema: { type: string }
          description: Review ID (URL-encoded for Google Business)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId, message]
              properties:
                accountId: { type: string }
                message: { type: string }
      responses:
        '200':
          description: Reply posted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string }
                  reply:
                    type: object
                    properties:
                      id: { type: string }
                      text: { type: string }
                      created: { type: string, format: date-time }
                  platform: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required
    delete:
      operationId: deleteInboxReviewReply
      summary: Delete review reply
      description: Delete a reply to a review (Google Business only). Requires accountId in request body.
      tags: [Reviews]
      security: [{ bearerAuth: [] }]
      parameters:
        - name: reviewId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId]
              properties:
                accountId: { type: string }
      responses:
        '200':
          description: Reply deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: { type: string }
                  message: { type: string }
                  platform: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Inbox addon required
  # ──────────────────────────────────────────────────────────────────────────
  # WHATSAPP-SPECIFIC ENDPOINTS
  # Contacts, broadcasts, groups: DEPRECATED (use cross-platform endpoints)
  # Templates, business profile, phone numbers: ACTIVE (no equivalent)
  # ──────────────────────────────────────────────────────────────────────────

  # ── BULK SEND ──────────────────────────────────────────────────────────

  /v1/whatsapp/bulk:
    post:
      operationId: sendWhatsAppBulk
      deprecated: true
      tags: [WhatsApp]
      summary: Bulk send template messages
      description: |
        **Deprecated.** Use `POST /v1/broadcasts` to create a broadcast, `POST /v1/broadcasts/{id}/recipients` to add recipients, then `POST /v1/broadcasts/{id}/send` to send.
        Send a template message to multiple recipients in a single request. Maximum 100 recipients per request.
        Only template messages are supported for bulk sending (not free-form text).

        Each recipient can have optional per-recipient template variables for personalization.
        Returns detailed results for each recipient.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - accountId
                - recipients
                - template
              properties:
                accountId:
                  type: string
                  description: WhatsApp social account ID
                recipients:
                  type: array
                  maxItems: 100
                  description: List of recipients (max 100)
                  items:
                    type: object
                    required:
                      - phone
                    properties:
                      phone:
                        type: string
                        description: Recipient phone number in E.164 format
                      variables:
                        type: object
                        additionalProperties: { type: string }
                        description: Per-recipient template variables keyed by index (e.g., "1", "2")
                template:
                  type: object
                  required:
                    - name
                    - language
                  properties:
                    name:
                      type: string
                      description: Template name
                    language:
                      type: string
                      description: Template language code
                    components:
                      type: array
                      description: Base template components
                      items:
                        type: object
            example:
              accountId: "507f1f77bcf86cd799439011"
              recipients:
                - phone: "+1234567890"
                  variables: { "1": "John" }
                - phone: "+0987654321"
                  variables: { "1": "Jane" }
              template:
                name: "welcome_message"
                language: "en_US"
      responses:
        '200':
          description: Bulk send completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  summary:
                    type: object
                    properties:
                      total: { type: integer }
                      sent: { type: integer }
                      failed: { type: integer }
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        phone: { type: string }
                        success: { type: boolean }
                        messageId: { type: string }
                        error: { type: string }
        '400': { description: Validation error (missing fields, too many recipients, etc.) }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }

  # ──────────────────────────────────────────────────────────────────────────
  # CONTACTS
  # ──────────────────────────────────────────────────────────────────────────

  /v1/whatsapp/contacts:
    get:
      operationId: getWhatsAppContacts
      deprecated: true
      tags: [WhatsApp]
      summary: List contacts
      description: |
        **Deprecated.** Use `GET /v1/contacts?profileId={profileId}` instead.
        List WhatsApp contacts for an account. Supports filtering by tags, groups, opt-in status,
        and text search. Returns contacts sorted by name with available filter options.
      security:
        - bearerAuth: []
      parameters:
        - name: accountId
          in: query
          required: true
          description: WhatsApp social account ID
          schema:
            type: string
        - name: search
          in: query
          required: false
          description: Search contacts by name, phone, email, or company
          schema:
            type: string
        - name: tag
          in: query
          required: false
          description: Filter by tag
          schema:
            type: string
        - name: group
          in: query
          required: false
          description: Filter by group
          schema:
            type: string
        - name: optedIn
          in: query
          required: false
          description: Filter by opt-in status
          schema:
            type: string
            enum: ["true", "false"]
        - name: limit
          in: query
          required: false
          description: Maximum results (default 50)
          schema:
            type: integer
            default: 50
        - name: skip
          in: query
          required: false
          description: Offset for pagination
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Contacts retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  contacts:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        phone: { type: string }
                        waId: { type: string }
                        name: { type: string }
                        email: { type: string }
                        company: { type: string }
                        tags:
                          type: array
                          items: { type: string }
                        groups:
                          type: array
                          items: { type: string }
                        isOptedIn: { type: boolean }
                        lastMessageSentAt: { type: string, format: date-time }
                        lastMessageReceivedAt: { type: string, format: date-time }
                        messagesSentCount: { type: integer }
                        messagesReceivedCount: { type: integer }
                        customFields: { type: object }
                        notes: { type: string }
                        createdAt: { type: string, format: date-time }
                  filters:
                    type: object
                    properties:
                      tags:
                        type: array
                        items: { type: string }
                      groups:
                        type: array
                        items: { type: string }
                  pagination:
                    type: object
                    properties:
                      total: { type: integer }
                      limit: { type: integer }
                      skip: { type: integer }
                      hasMore: { type: boolean }
        '400': { description: accountId is required }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }
    post:
      operationId: createWhatsAppContact
      deprecated: true
      tags: [WhatsApp]
      summary: Create contact
      description: |
        **Deprecated.** Use `POST /v1/contacts` instead.
        Create a new WhatsApp contact. Phone number must be unique per account
        and in E.164 format (e.g., +1234567890).
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - accountId
                - phone
                - name
              properties:
                accountId:
                  type: string
                  description: WhatsApp social account ID
                phone:
                  type: string
                  description: Phone number in E.164 format
                name:
                  type: string
                  description: Contact name
                email:
                  type: string
                  description: Contact email
                company:
                  type: string
                  description: Company name
                tags:
                  type: array
                  items: { type: string }
                  description: Tags for categorization
                groups:
                  type: array
                  items: { type: string }
                  description: Groups the contact belongs to
                isOptedIn:
                  type: boolean
                  default: true
                  description: Whether the contact has opted in to receive messages
                customFields:
                  type: object
                  additionalProperties: { type: string }
                  description: Custom key-value fields
                notes:
                  type: string
                  description: Notes about the contact
            example:
              accountId: "507f1f77bcf86cd799439011"
              phone: "+1234567890"
              name: "John Doe"
              email: "john@example.com"
              tags: ["vip", "newsletter"]
              groups: ["customers"]
      responses:
        '200':
          description: Contact created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  contact:
                    type: object
                    properties:
                      id: { type: string }
                      phone: { type: string }
                      name: { type: string }
                      email: { type: string }
                      company: { type: string }
                      tags:
                        type: array
                        items: { type: string }
                      groups:
                        type: array
                        items: { type: string }
                      isOptedIn: { type: boolean }
                      createdAt: { type: string, format: date-time }
        '400': { description: Validation error (missing fields, invalid phone number) }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }
        '409': { description: Contact with this phone number already exists }

  /v1/whatsapp/contacts/{contactId}:
    get:
      operationId: getWhatsAppContact
      deprecated: true
      tags: [WhatsApp]
      summary: Get contact
      description: |
        **Deprecated.** Use `GET /v1/contacts/{id}` instead.
        Retrieve a single WhatsApp contact by ID with full details.
      security:
        - bearerAuth: []
      parameters:
        - name: contactId
          in: path
          required: true
          description: Contact ID
          schema:
            type: string
      responses:
        '200':
          description: Contact retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  contact:
                    type: object
                    properties:
                      id: { type: string }
                      phone: { type: string }
                      waId: { type: string }
                      name: { type: string }
                      email: { type: string }
                      company: { type: string }
                      tags:
                        type: array
                        items: { type: string }
                      groups:
                        type: array
                        items: { type: string }
                      isOptedIn: { type: boolean }
                      optInDate: { type: string, format: date-time }
                      optOutDate: { type: string, format: date-time }
                      isBlocked: { type: boolean }
                      lastMessageSentAt: { type: string, format: date-time }
                      lastMessageReceivedAt: { type: string, format: date-time }
                      messagesSentCount: { type: integer }
                      messagesReceivedCount: { type: integer }
                      customFields: { type: object }
                      notes: { type: string }
                      createdAt: { type: string, format: date-time }
                      updatedAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    put:
      operationId: updateWhatsAppContact
      deprecated: true
      tags: [WhatsApp]
      summary: Update contact
      description: |
        **Deprecated.** Use `PATCH /v1/contacts/{id}` instead.
        Update an existing WhatsApp contact. All fields are optional; only provided fields will be updated.
        Custom fields are merged with existing values. Set a custom field to null to remove it.
      security:
        - bearerAuth: []
      parameters:
        - name: contactId
          in: path
          required: true
          description: Contact ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Contact name
                email:
                  type: string
                  description: Contact email
                company:
                  type: string
                  description: Company name
                tags:
                  type: array
                  items: { type: string }
                  description: Tags (replaces existing)
                groups:
                  type: array
                  items: { type: string }
                  description: Groups (replaces existing)
                isOptedIn:
                  type: boolean
                  description: Opt-in status (changes are timestamped)
                isBlocked:
                  type: boolean
                  description: Block status
                customFields:
                  type: object
                  additionalProperties: { type: string, nullable: true }
                  description: Custom fields to merge (set value to null to remove a field)
                notes:
                  type: string
                  description: Notes about the contact
            example:
              name: "John Doe Updated"
              tags: ["vip", "premium"]
              customFields: { "plan": "enterprise", "remove_me": null }
      responses:
        '200':
          description: Contact updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  contact:
                    type: object
                    properties:
                      id: { type: string }
                      phone: { type: string }
                      name: { type: string }
                      email: { type: string }
                      company: { type: string }
                      tags:
                        type: array
                        items: { type: string }
                      groups:
                        type: array
                        items: { type: string }
                      isOptedIn: { type: boolean }
                      isBlocked: { type: boolean }
                      customFields: { type: object }
                      notes: { type: string }
                      updatedAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: deleteWhatsAppContact
      deprecated: true
      tags: [WhatsApp]
      summary: Delete contact
      description: |
        **Deprecated.** Use `DELETE /v1/contacts/{id}` instead.
        Permanently delete a WhatsApp contact.
      security:
        - bearerAuth: []
      parameters:
        - name: contactId
          in: path
          required: true
          description: Contact ID
          schema:
            type: string
      responses:
        '200':
          description: Contact deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
              example:
                success: true
                message: "Contact deleted successfully"
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/whatsapp/contacts/import:
    post:
      operationId: importWhatsAppContacts
      deprecated: true
      tags: [WhatsApp]
      summary: Bulk import contacts
      description: |
        **Deprecated.** Use `POST /v1/contacts/bulk` instead.
        Import up to 1000 contacts at once. Each contact requires a phone number and name.
        Duplicates are skipped by default. Supports default tags and groups applied to all imported contacts.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - accountId
                - contacts
              properties:
                accountId:
                  type: string
                  description: WhatsApp social account ID
                contacts:
                  type: array
                  maxItems: 1000
                  description: Contacts to import (max 1000)
                  items:
                    type: object
                    required:
                      - phone
                      - name
                    properties:
                      phone:
                        type: string
                        description: Phone number in E.164 format
                      name:
                        type: string
                        description: Contact name
                      email:
                        type: string
                      company:
                        type: string
                      tags:
                        type: array
                        items: { type: string }
                      groups:
                        type: array
                        items: { type: string }
                      customFields:
                        type: object
                        additionalProperties: { type: string }
                      notes:
                        type: string
                defaultTags:
                  type: array
                  items: { type: string }
                  description: Tags applied to all imported contacts
                defaultGroups:
                  type: array
                  items: { type: string }
                  description: Groups applied to all imported contacts
                skipDuplicates:
                  type: boolean
                  default: true
                  description: Skip contacts with existing phone numbers
            example:
              accountId: "507f1f77bcf86cd799439011"
              contacts:
                - phone: "+1234567890"
                  name: "John Doe"
                  email: "john@example.com"
                - phone: "+0987654321"
                  name: "Jane Smith"
              defaultTags: ["imported"]
              defaultGroups: ["new-leads"]
      responses:
        '200':
          description: Import completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  summary:
                    type: object
                    properties:
                      total: { type: integer }
                      created: { type: integer }
                      skipped: { type: integer }
                      failed: { type: integer }
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        phone: { type: string }
                        name: { type: string }
                        success: { type: boolean }
                        contactId: { type: string }
                        error: { type: string }
        '400': { description: Validation error (missing fields, too many contacts) }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }

  /v1/whatsapp/contacts/bulk:
    post:
      operationId: bulkUpdateWhatsAppContacts
      deprecated: true
      tags: [WhatsApp]
      summary: Bulk update contacts
      description: |
        **Deprecated.** Use `PATCH /v1/contacts/{id}` for individual updates instead.
        Perform bulk operations on multiple contacts (max 500 per request). Supported actions:
        addTags, removeTags, addGroups, removeGroups, optIn, optOut, block, unblock.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - action
                - contactIds
              properties:
                action:
                  type: string
                  enum: [addTags, removeTags, addGroups, removeGroups, optIn, optOut, block, unblock]
                  description: Bulk action to perform
                contactIds:
                  type: array
                  maxItems: 500
                  items: { type: string }
                  description: Contact IDs to update (max 500)
                tags:
                  type: array
                  items: { type: string }
                  description: Tags to add or remove (required for addTags/removeTags)
                groups:
                  type: array
                  items: { type: string }
                  description: Groups to add or remove (required for addGroups/removeGroups)
            examples:
              addTags:
                summary: Add tags to contacts
                value:
                  action: "addTags"
                  contactIds: ["507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012"]
                  tags: ["vip", "priority"]
              optOut:
                summary: Opt out contacts
                value:
                  action: "optOut"
                  contactIds: ["507f1f77bcf86cd799439011"]
      responses:
        '200':
          description: Bulk update completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  action: { type: string }
                  modified: { type: integer, description: Number of contacts modified }
                  matched: { type: integer, description: Number of contacts matched }
        '400': { description: Validation error (invalid action, missing required fields) }
        '401': { $ref: '#/components/responses/Unauthorized' }
    delete:
      operationId: bulkDeleteWhatsAppContacts
      deprecated: true
      tags: [WhatsApp]
      summary: Bulk delete contacts
      description: |
        **Deprecated.** Use `DELETE /v1/contacts/{id}` for individual deletes instead.
        Permanently delete multiple contacts at once (max 500 per request).
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - contactIds
              properties:
                contactIds:
                  type: array
                  maxItems: 500
                  items: { type: string }
                  description: Contact IDs to delete (max 500)
            example:
              contactIds: ["507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012"]
      responses:
        '200':
          description: Bulk delete completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  deleted: { type: integer, description: Number of contacts deleted }
        '400': { description: contactIds array is required }
        '401': { $ref: '#/components/responses/Unauthorized' }

  # ──────────────────────────────────────────────────────────────────────────
  # GROUPS
  # ──────────────────────────────────────────────────────────────────────────

  /v1/whatsapp/groups:
    get:
      operationId: getWhatsAppGroups
      deprecated: true
      tags: [WhatsApp]
      summary: List contact groups
      description: |
        **Deprecated.** Use contact tags via `GET /v1/contacts` for grouping instead. WhatsApp groups have no cross-platform equivalent.
        List all contact groups for a WhatsApp account with contact counts.
        Groups are derived from the groups field on contacts, not stored as separate documents.
      security:
        - bearerAuth: []
      parameters:
        - name: accountId
          in: query
          required: true
          description: WhatsApp social account ID
          schema:
            type: string
      responses:
        '200':
          description: Groups retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  groups:
                    type: array
                    items:
                      type: object
                      properties:
                        name: { type: string }
                        totalCount: { type: integer, description: Total contacts in this group }
                        optedInCount: { type: integer, description: Opted-in contacts in this group }
                  summary:
                    type: object
                    properties:
                      totalContacts: { type: integer }
                      optedInContacts: { type: integer }
                      groupCount: { type: integer }
        '400': { description: accountId is required }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }
    post:
      operationId: renameWhatsAppGroup
      deprecated: true
      tags: [WhatsApp]
      summary: Rename group
      description: |
        **Deprecated.** Use contact tags via `PATCH /v1/contacts/{id}` instead.
        Rename a contact group. This updates the group name on all contacts that belong to the group.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - accountId
                - oldName
                - newName
              properties:
                accountId:
                  type: string
                  description: WhatsApp social account ID
                oldName:
                  type: string
                  description: Current group name
                newName:
                  type: string
                  description: New group name
            example:
              accountId: "507f1f77bcf86cd799439011"
              oldName: "customers"
              newName: "active-customers"
      responses:
        '200':
          description: Group renamed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
                  modified: { type: integer, description: Number of contacts updated }
        '400': { description: Validation error (missing fields, same name) }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }
    delete:
      operationId: deleteWhatsAppGroup
      deprecated: true
      tags: [WhatsApp]
      summary: Delete group
      description: |
        **Deprecated.** Use contact tags via `PATCH /v1/contacts/{id}` instead.
        Delete a contact group. This removes the group from all contacts but does not delete the contacts themselves.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - accountId
                - groupName
              properties:
                accountId:
                  type: string
                  description: WhatsApp social account ID
                groupName:
                  type: string
                  description: Group name to delete
            example:
              accountId: "507f1f77bcf86cd799439011"
              groupName: "old-leads"
      responses:
        '200':
          description: Group deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
                  modified: { type: integer, description: Number of contacts updated }
        '400': { description: Validation error (missing fields) }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }

  # ──────────────────────────────────────────────────────────────────────────
  # TEMPLATES
  # ──────────────────────────────────────────────────────────────────────────

  /v1/whatsapp/templates:
    get:
      operationId: getWhatsAppTemplates
      tags: [WhatsApp]
      summary: List templates
      description: |
        List all message templates for the WhatsApp Business Account (WABA) associated with the given account.
        Templates are fetched directly from the WhatsApp Cloud API.
      security:
        - bearerAuth: []
      parameters:
        - name: accountId
          in: query
          required: true
          description: WhatsApp social account ID
          schema:
            type: string
      responses:
        '200':
          description: Templates retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  templates:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, description: WhatsApp template ID }
                        name: { type: string }
                        status: { type: string, enum: [APPROVED, PENDING, REJECTED] }
                        category: { type: string, enum: [AUTHENTICATION, MARKETING, UTILITY] }
                        language: { type: string }
                        components:
                          type: array
                          items:
                            type: object
        '400': { description: accountId is required or WABA ID not found }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }
    post:
      operationId: createWhatsAppTemplate
      tags: [WhatsApp]
      summary: Create template
      description: |
        Create a new message template. Supports two modes:

        **Custom template:** Provide `components` with your own content. Submitted to Meta for review (can take up to 24h).

        **Library template:** Provide `library_template_name` instead of `components` to use a pre-built template
        from Meta's template library. Library templates are **pre-approved** (no review wait). You can optionally
        customize parameters and buttons via `library_template_body_inputs` and `library_template_button_inputs`.

        Browse available library templates at: https://business.facebook.com/wa/manage/message-templates/
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - accountId
                - name
                - category
                - language
              properties:
                accountId:
                  type: string
                  description: WhatsApp social account ID
                name:
                  type: string
                  pattern: "^[a-z][a-z0-9_]*$"
                  description: Template name (lowercase, letters/numbers/underscores, must start with a letter)
                category:
                  type: string
                  enum: [AUTHENTICATION, MARKETING, UTILITY]
                  description: Template category
                language:
                  type: string
                  description: Template language code (e.g., en_US)
                components:
                  type: array
                  description: "Template components (header, body, footer, buttons). Required for custom templates, omit when using library_template_name."
                  minItems: 1
                  items:
                    $ref: '#/components/schemas/WhatsAppTemplateComponent'
                library_template_name:
                  type: string
                  description: |
                    Name of a pre-built template from Meta's template library (e.g., "appointment_reminder",
                    "auto_pay_reminder_1", "address_update"). When provided, the template is pre-approved
                    by Meta with no review wait. Omit `components` when using this field.
                library_template_body_inputs:
                  type: object
                  description: |
                    Optional body customizations for library templates. Available options depend on the
                    template (e.g., add_contact_number, add_learn_more_link, add_security_recommendation,
                    add_track_package_link, code_expiration_minutes).
                library_template_button_inputs:
                  type: array
                  description: |
                    Optional button customizations for library templates. Each item specifies button type
                    and configuration (e.g., URL, phone number, quick reply).
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        enum: [quick_reply, url, phone_number]
                      url:
                        type: object
                        properties:
                          base_url: { type: string }
                      phone_number:
                        type: string
            examples:
              custom:
                summary: Custom template (requires review)
                value:
                  accountId: "507f1f77bcf86cd799439011"
                  name: "order_confirmation"
                  category: "UTILITY"
                  language: "en_US"
                  components:
                    - type: "header"
                      format: "image"
                      example:
                        header_handle: ["https://example.com/header.jpg"]
                    - type: "body"
                      text: "Your order {{1}} has been confirmed. Expected delivery: {{2}}"
                      example:
                        body_text: [["ORD-12345", "March 31"]]
                    - type: "footer"
                      text: "Thank you for your purchase"
                    - type: "buttons"
                      buttons:
                        - type: "quick_reply"
                          text: "Track Order"
              library:
                summary: Library template (pre-approved, no review)
                value:
                  accountId: "507f1f77bcf86cd799439011"
                  name: "my_appointment_reminder"
                  category: "UTILITY"
                  language: "en_US"
                  library_template_name: "appointment_reminder"
                  library_template_button_inputs:
                    - type: "url"
                      url:
                        base_url: "https://myapp.com/appointments/{{1}}"
      responses:
        '200':
          description: Template created (pre-approved for library templates, pending review for custom)
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  template:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      status: { type: string, description: "APPROVED for library templates, PENDING for custom" }
                      category: { type: string }
                      language: { type: string }
        '400': { description: Validation error (invalid name format, missing fields, invalid category) }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }

  /v1/whatsapp/templates/{templateName}:
    get:
      operationId: getWhatsAppTemplate
      tags: [WhatsApp]
      summary: Get template
      description: |
        Retrieve a single message template by name.
      security:
        - bearerAuth: []
      parameters:
        - name: templateName
          in: path
          required: true
          description: Template name
          schema:
            type: string
        - name: accountId
          in: query
          required: true
          description: WhatsApp social account ID
          schema:
            type: string
      responses:
        '200':
          description: Template retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  template:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      status: { type: string }
                      category: { type: string }
                      language: { type: string }
                      components:
                        type: array
                        items:
                          type: object
        '400': { description: accountId is required }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      operationId: updateWhatsAppTemplate
      tags: [WhatsApp]
      summary: Update template
      description: |
        Update a message template's components. Only certain fields can be updated depending on
        the template's current approval state. Approved templates can only have components updated.
      security:
        - bearerAuth: []
      parameters:
        - name: templateName
          in: path
          required: true
          description: Template name
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - accountId
                - components
              properties:
                accountId:
                  type: string
                  description: WhatsApp social account ID
                components:
                  type: array
                  description: Updated template components
                  minItems: 1
                  items:
                    $ref: '#/components/schemas/WhatsAppTemplateComponent'
            example:
              accountId: "507f1f77bcf86cd799439011"
              components:
                - type: "body"
                  text: "Updated: Your order {{1}} is confirmed. Delivery by {{2}}"
                  example:
                    body_text: [["ORD-12345", "April 1"]]
                - type: "buttons"
                  buttons:
                    - type: "quick_reply"
                      text: "Track Order"
      responses:
        '200':
          description: Template updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  template:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      status: { type: string }
        '400': { description: Validation error (missing fields) }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: deleteWhatsAppTemplate
      tags: [WhatsApp]
      summary: Delete template
      description: |
        Permanently delete a message template by name.
      security:
        - bearerAuth: []
      parameters:
        - name: templateName
          in: path
          required: true
          description: Template name
          schema:
            type: string
        - name: accountId
          in: query
          required: true
          description: WhatsApp social account ID
          schema:
            type: string
      responses:
        '200':
          description: Template deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
              example:
                success: true
                message: "Template \"order_confirmation\" deleted successfully"
        '400': { description: accountId or template name is required }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  # ──────────────────────────────────────────────────────────────────────────
  # BROADCASTS
  # ──────────────────────────────────────────────────────────────────────────

  /v1/whatsapp/broadcasts:
    get:
      operationId: getWhatsAppBroadcasts
      deprecated: true
      tags: [WhatsApp]
      summary: List broadcasts
      description: |
        **Deprecated.** Use `GET /v1/broadcasts?profileId={profileId}` instead.
        List all WhatsApp broadcasts for an account. Returns broadcasts sorted by creation date
        (newest first) without the full recipients list for performance.
      security:
        - bearerAuth: []
      parameters:
        - name: accountId
          in: query
          required: true
          description: WhatsApp social account ID
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Filter by broadcast status
          schema:
            type: string
            enum: [draft, scheduled, sending, completed, failed, cancelled]
        - name: limit
          in: query
          required: false
          description: Maximum results (default 50)
          schema:
            type: integer
            default: 50
        - name: skip
          in: query
          required: false
          description: Offset for pagination
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Broadcasts retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  broadcasts:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        name: { type: string }
                        description: { type: string }
                        template:
                          type: object
                          properties:
                            name: { type: string }
                            language: { type: string }
                        status: { type: string, enum: [draft, scheduled, sending, completed, failed, cancelled] }
                        messagePreview: { type: string, description: Template name or message text snippet }
                        recipientCount: { type: integer }
                        scheduledAt: { type: string, format: date-time }
                        startedAt: { type: string, format: date-time }
                        completedAt: { type: string, format: date-time }
                        sentCount: { type: integer }
                        deliveredCount: { type: integer }
                        readCount: { type: integer }
                        failedCount: { type: integer }
                        createdAt: { type: string, format: date-time }
                  pagination:
                    type: object
                    properties:
                      total: { type: integer }
                      limit: { type: integer }
                      skip: { type: integer }
                      hasMore: { type: boolean }
        '400': { description: accountId is required }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }
    post:
      operationId: createWhatsAppBroadcast
      deprecated: true
      tags: [WhatsApp]
      summary: Create broadcast
      description: |
        **Deprecated.** Use `POST /v1/broadcasts` instead.
        Create a new draft broadcast. Optionally include initial recipients.
        After creation, add recipients and then send or schedule the broadcast.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - accountId
                - name
                - template
              properties:
                accountId:
                  type: string
                  description: WhatsApp social account ID
                name:
                  type: string
                  description: Broadcast name
                description:
                  type: string
                  description: Broadcast description
                template:
                  type: object
                  required:
                    - name
                    - language
                  properties:
                    name:
                      type: string
                      description: Template name
                    language:
                      type: string
                      description: Template language code
                    components:
                      type: array
                      description: Base template components
                      items:
                        type: object
                recipients:
                  type: array
                  description: Initial recipients (optional)
                  items:
                    type: object
                    required:
                      - phone
                    properties:
                      phone:
                        type: string
                        description: Phone number in E.164 format
                      name:
                        type: string
                      variables:
                        type: object
                        additionalProperties: { type: string }
                        description: Per-recipient template variables
            example:
              accountId: "507f1f77bcf86cd799439011"
              name: "Weekly Newsletter"
              description: "Weekly product updates"
              template:
                name: "weekly_update"
                language: "en_US"
              recipients:
                - phone: "+1234567890"
                  name: "John"
                  variables: { "1": "John" }
      responses:
        '200':
          description: Broadcast created as draft
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  broadcast:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      description: { type: string }
                      template: { type: object }
                      status: { type: string, description: Always "draft" for new broadcasts }
                      recipientCount: { type: integer }
                      createdAt: { type: string, format: date-time }
        '400': { description: Validation error (missing name, template, etc.) }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }

  /v1/whatsapp/broadcasts/{broadcastId}:
    get:
      operationId: getWhatsAppBroadcast
      deprecated: true
      tags: [WhatsApp]
      summary: Get broadcast
      description: |
        **Deprecated.** Use `GET /v1/broadcasts/{id}` instead.
        Retrieve detailed information about a single broadcast including delivery statistics.
      security:
        - bearerAuth: []
      parameters:
        - name: broadcastId
          in: path
          required: true
          description: Broadcast ID
          schema:
            type: string
      responses:
        '200':
          description: Broadcast retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  broadcast:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      description: { type: string }
                      template: { type: object }
                      status: { type: string, enum: [draft, scheduled, sending, completed, failed, cancelled] }
                      recipientCount: { type: integer }
                      scheduledAt: { type: string, format: date-time }
                      startedAt: { type: string, format: date-time }
                      completedAt: { type: string, format: date-time }
                      sentCount: { type: integer }
                      deliveredCount: { type: integer }
                      readCount: { type: integer }
                      failedCount: { type: integer }
                      createdAt: { type: string, format: date-time }
                      updatedAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: deleteWhatsAppBroadcast
      deprecated: true
      tags: [WhatsApp]
      summary: Delete broadcast
      description: |
        **Deprecated.** Use `DELETE /v1/broadcasts/{id}` instead.
        Delete a broadcast. Only draft or cancelled broadcasts can be deleted.
      security:
        - bearerAuth: []
      parameters:
        - name: broadcastId
          in: path
          required: true
          description: Broadcast ID
          schema:
            type: string
      responses:
        '200':
          description: Broadcast deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
              example:
                success: true
                message: "Broadcast deleted successfully"
        '400': { description: Can only delete draft or cancelled broadcasts }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/whatsapp/broadcasts/{broadcastId}/send:
    post:
      operationId: sendWhatsAppBroadcast
      deprecated: true
      tags: [WhatsApp]
      summary: Send broadcast
      description: |
        **Deprecated.** Use `POST /v1/broadcasts/{id}/send` instead.
        Start sending a broadcast immediately. The broadcast must be in draft or scheduled status
        and have at least one recipient. Messages are sent sequentially with rate limiting.
      security:
        - bearerAuth: []
      parameters:
        - name: broadcastId
          in: path
          required: true
          description: Broadcast ID
          schema:
            type: string
      responses:
        '200':
          description: Broadcast send completed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  status: { type: string, enum: [completed, failed], description: Final broadcast status }
                  sent: { type: integer, description: Number of messages sent successfully }
                  failed: { type: integer, description: Number of messages that failed }
                  total: { type: integer, description: Total recipient count }
              example:
                success: true
                status: "completed"
                sent: 95
                failed: 5
                total: 100
        '400': { description: Invalid broadcast status or no recipients }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/whatsapp/broadcasts/{broadcastId}/schedule:
    post:
      operationId: scheduleWhatsAppBroadcast
      deprecated: true
      tags: [WhatsApp]
      summary: Schedule broadcast
      description: |
        **Deprecated.** Use `POST /v1/broadcasts/{id}/schedule` instead.
        Schedule a draft broadcast for future sending. The scheduled time must be in the future
        and no more than 30 days in advance. The broadcast must be in draft status and have recipients.
      security:
        - bearerAuth: []
      parameters:
        - name: broadcastId
          in: path
          required: true
          description: Broadcast ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - scheduledAt
              properties:
                scheduledAt:
                  type: string
                  format: date-time
                  description: ISO 8601 date-time for sending (must be in the future, max 30 days)
            example:
              scheduledAt: "2026-03-15T10:00:00Z"
      responses:
        '200':
          description: Broadcast scheduled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  broadcast:
                    type: object
                    properties:
                      id: { type: string }
                      status: { type: string, description: "\"scheduled\"" }
                      scheduledAt: { type: string, format: date-time }
        '400': { description: Invalid schedule time or broadcast not in draft status }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: cancelWhatsAppBroadcastSchedule
      deprecated: true
      tags: [WhatsApp]
      summary: Cancel scheduled broadcast
      description: |
        **Deprecated.** Use `POST /v1/broadcasts/{id}/cancel` instead.
        Cancel a scheduled broadcast and return it to draft status. Only broadcasts in
        scheduled status can be cancelled.
      security:
        - bearerAuth: []
      parameters:
        - name: broadcastId
          in: path
          required: true
          description: Broadcast ID
          schema:
            type: string
      responses:
        '200':
          description: Schedule cancelled, broadcast returned to draft
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  broadcast:
                    type: object
                    properties:
                      id: { type: string }
                      status: { type: string, description: "\"draft\"" }
                  message: { type: string }
              example:
                success: true
                broadcast:
                  id: "507f1f77bcf86cd799439011"
                  status: "draft"
                message: "Broadcast returned to draft status"
        '400': { description: Broadcast is not scheduled }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/whatsapp/broadcasts/{broadcastId}/recipients:
    get:
      operationId: getWhatsAppBroadcastRecipients
      deprecated: true
      tags: [WhatsApp]
      summary: List recipients
      description: |
        **Deprecated.** Use `GET /v1/broadcasts/{id}/recipients` instead.
        List recipients of a broadcast with their delivery status. Supports filtering
        by delivery status and pagination.
      security:
        - bearerAuth: []
      parameters:
        - name: broadcastId
          in: path
          required: true
          description: Broadcast ID
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Filter by recipient delivery status
          schema:
            type: string
            enum: [pending, sent, delivered, read, failed]
        - name: limit
          in: query
          required: false
          description: Maximum results (default 100)
          schema:
            type: integer
            default: 100
        - name: skip
          in: query
          required: false
          description: Offset for pagination
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Recipients retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  recipients:
                    type: array
                    items:
                      type: object
                      properties:
                        phone: { type: string }
                        name: { type: string }
                        variables: { type: object }
                        status: { type: string, enum: [pending, sent, delivered, read, failed] }
                        messageId: { type: string }
                        error: { type: string }
                        sentAt: { type: string, format: date-time }
                        deliveredAt: { type: string, format: date-time }
                        readAt: { type: string, format: date-time }
                  pagination:
                    type: object
                    properties:
                      total: { type: integer }
                      limit: { type: integer }
                      skip: { type: integer }
                      hasMore: { type: boolean }
                  summary:
                    type: object
                    properties:
                      total: { type: integer }
                      pending: { type: integer }
                      sent: { type: integer }
                      delivered: { type: integer }
                      read: { type: integer }
                      failed: { type: integer }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      operationId: addWhatsAppBroadcastRecipients
      deprecated: true
      tags: [WhatsApp]
      summary: Add recipients
      description: |
        **Deprecated.** Use `POST /v1/broadcasts/{id}/recipients` instead.
        Add recipients to a draft broadcast. Maximum 1000 recipients per request.
        Duplicate phone numbers are automatically skipped.
      security:
        - bearerAuth: []
      parameters:
        - name: broadcastId
          in: path
          required: true
          description: Broadcast ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - recipients
              properties:
                recipients:
                  type: array
                  maxItems: 1000
                  description: Recipients to add (max 1000)
                  items:
                    type: object
                    required:
                      - phone
                    properties:
                      phone:
                        type: string
                        description: Phone number in E.164 format
                      name:
                        type: string
                      variables:
                        type: object
                        additionalProperties: { type: string }
            example:
              recipients:
                - phone: "+1234567890"
                  name: "John"
                  variables: { "1": "John" }
                - phone: "+0987654321"
                  name: "Jane"
      responses:
        '200':
          description: Recipients added successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  added: { type: integer, description: Number of new recipients added }
                  duplicates: { type: integer, description: Number of duplicate phone numbers skipped }
                  totalRecipients: { type: integer, description: Total recipient count after addition }
        '400': { description: Validation error or broadcast not in draft status }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: removeWhatsAppBroadcastRecipients
      deprecated: true
      tags: [WhatsApp]
      summary: Remove recipients
      description: |
        **Deprecated.** Use `POST /v1/broadcasts/{id}/recipients` with removal flag instead.
        Remove recipients from a draft broadcast by phone number.
      security:
        - bearerAuth: []
      parameters:
        - name: broadcastId
          in: path
          required: true
          description: Broadcast ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - phones
              properties:
                phones:
                  type: array
                  items: { type: string }
                  description: Phone numbers to remove
            example:
              phones: ["+1234567890", "+0987654321"]
      responses:
        '200':
          description: Recipients removed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  removed: { type: integer, description: Number of recipients removed }
                  totalRecipients: { type: integer, description: Remaining recipient count }
        '400': { description: Validation error or broadcast not in draft status }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  # ──────────────────────────────────────────────────────────────────────────
  # BUSINESS PROFILE
  # ──────────────────────────────────────────────────────────────────────────

  /v1/whatsapp/business-profile:
    get:
      operationId: getWhatsAppBusinessProfile
      tags: [WhatsApp]
      summary: Get business profile
      description: |
        Retrieve the WhatsApp Business profile for the account (about, address, description, email, websites, etc.).
      security:
        - bearerAuth: []
      parameters:
        - name: accountId
          in: query
          required: true
          description: WhatsApp social account ID
          schema:
            type: string
      responses:
        '200':
          description: Business profile retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  businessProfile:
                    type: object
                    properties:
                      about: { type: string, description: Short description (max 139 chars) }
                      address: { type: string }
                      description: { type: string, description: Full description (max 512 chars) }
                      email: { type: string }
                      profilePictureUrl: { type: string, format: uri }
                      websites:
                        type: array
                        items: { type: string }
                        maxItems: 2
                      vertical: { type: string, description: Business category }
        '400': { description: accountId is required or phone number ID not found }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }
    post:
      operationId: updateWhatsAppBusinessProfile
      tags: [WhatsApp]
      summary: Update business profile
      description: |
        Update the WhatsApp Business profile. All fields are optional; only provided fields will be updated.
        Constraints: about max 139 chars, description max 512 chars, max 2 websites.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - accountId
              properties:
                accountId:
                  type: string
                  description: WhatsApp social account ID
                about:
                  type: string
                  maxLength: 139
                  description: Short business description (max 139 characters)
                address:
                  type: string
                  description: Business address
                description:
                  type: string
                  maxLength: 512
                  description: Full business description (max 512 characters)
                email:
                  type: string
                  format: email
                  description: Business email
                websites:
                  type: array
                  maxItems: 2
                  items: { type: string, format: uri }
                  description: Business websites (max 2)
                vertical:
                  type: string
                  description: Business category (e.g., RETAIL, ENTERTAINMENT, etc.)
                profilePictureHandle:
                  type: string
                  description: Handle from resumable upload for profile picture
            example:
              accountId: "507f1f77bcf86cd799439011"
              about: "We help businesses grow"
              description: "Premium business solutions for startups and enterprises"
              email: "hello@example.com"
              websites: ["https://example.com"]
      responses:
        '200':
          description: Business profile updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
              example:
                success: true
                message: "Business profile updated successfully"
        '400': { description: Validation error (field too long, too many websites, etc.) }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }

  /v1/whatsapp/business-profile/photo:
    post:
      operationId: uploadWhatsAppProfilePhoto
      tags: [WhatsApp]
      summary: Upload profile picture
      description: |
        Upload a new profile picture for the WhatsApp Business Profile.
        Uses Meta's resumable upload API under the hood: creates an upload session,
        uploads the image bytes, then updates the business profile with the resulting handle.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [accountId, file]
              properties:
                accountId:
                  type: string
                  description: WhatsApp social account ID
                file:
                  type: string
                  format: binary
                  description: Image file (JPEG or PNG, max 5MB, recommended 640x640)
      responses:
        '200':
          description: Profile picture updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
        '400': { description: Invalid file type, file too large, or missing parameters }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }

  /v1/whatsapp/business-profile/display-name:
    get:
      operationId: getWhatsAppDisplayName
      tags: [WhatsApp]
      summary: Get display name and review status
      description: |
        Fetch the current display name and its Meta review status for a WhatsApp Business account.
        Display name changes require Meta approval and can take 1-3 business days.
      security:
        - bearerAuth: []
      parameters:
        - name: accountId
          in: query
          required: true
          description: WhatsApp social account ID
          schema:
            type: string
      responses:
        '200':
          description: Display name info retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  displayName:
                    type: object
                    properties:
                      name: { type: string, description: Current verified display name }
                      status:
                        type: string
                        enum: [APPROVED, PENDING_REVIEW, DECLINED, NONE]
                        description: Meta review status for the display name
                      phoneNumber: { type: string, description: Display phone number }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }
    post:
      operationId: updateWhatsAppDisplayName
      tags: [WhatsApp]
      summary: Request display name change
      description: |
        Submit a display name change request for the WhatsApp Business account.
        The new name must follow WhatsApp naming guidelines (3-512 characters, must represent your business).
        Changes require Meta review and approval, which typically takes 1-3 business days.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId, displayName]
              properties:
                accountId:
                  type: string
                  description: WhatsApp social account ID
                displayName:
                  type: string
                  minLength: 3
                  maxLength: 512
                  description: New display name (must follow WhatsApp naming guidelines)
            example:
              accountId: "507f1f77bcf86cd799439011"
              displayName: "My Business Name"
      responses:
        '200':
          description: Display name change submitted for review
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
                  displayName:
                    type: object
                    properties:
                      name: { type: string }
                      status: { type: string, enum: [PENDING_REVIEW] }
        '400': { description: Invalid display name (too short, too long, or missing) }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }

  # ──────────────────────────────────────────────────────────────────────────
  # PHONE NUMBERS
  # ──────────────────────────────────────────────────────────────────────────

  /v1/whatsapp/phone-numbers:
    get:
      operationId: getWhatsAppPhoneNumbers
      tags: [WhatsApp Phone Numbers]
      summary: List phone numbers
      description: |
        List all WhatsApp phone numbers purchased by the authenticated user.
        By default, released numbers are excluded.
      security:
        - bearerAuth: []
      parameters:
        - name: status
          in: query
          required: false
          description: Filter by status (by default excludes released numbers)
          schema:
            type: string
            enum: [provisioning, active, suspended, releasing, released]
        - name: profileId
          in: query
          required: false
          description: Filter by profile
          schema:
            type: string
      responses:
        '200':
          description: Phone numbers retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  numbers:
                    type: array
                    items:
                      type: object
                      properties:
                        _id: { type: string }
                        phoneNumber: { type: string }
                        country: { type: string }
                        status: { type: string, enum: [pending_payment, provisioning, active, suspended, releasing, released] }
                        profileId: { type: object }
                        provisionedAt: { type: string, format: date-time }
                        metaPreverifiedId: { type: string }
                        metaVerificationStatus: { type: string }
                        createdAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/whatsapp/phone-numbers/purchase:
    post:
      operationId: purchaseWhatsAppPhoneNumber
      tags: [WhatsApp Phone Numbers]
      summary: Purchase phone number
      description: |
        Initiate purchasing a WhatsApp phone number. Payment-first flow: the user does not pick
        a specific number. The system either creates a Stripe Checkout Session (first number)
        or increments the existing subscription quantity and provisions inline (subsequent numbers).

        Requires a paid plan. The maximum number of phone numbers is determined by the user's plan.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - profileId
              properties:
                profileId:
                  type: string
                  description: Profile to associate the number with
            example:
              profileId: "507f1f77bcf86cd799439011"
      responses:
        '200':
          description: |
            Either a checkout URL (first number) or the provisioned phone number (subsequent numbers).
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    description: Checkout session created (first number)
                    properties:
                      message: { type: string }
                      checkoutUrl: { type: string, format: uri }
                  - type: object
                    description: Phone number provisioned inline (subsequent numbers)
                    properties:
                      message: { type: string }
                      phoneNumber:
                        type: object
                        properties:
                          id: { type: string }
                          phoneNumber: { type: string }
                          status: { type: string }
                          country: { type: string }
                          provisionedAt: { type: string, format: date-time }
                          metaPreverifiedId: { type: string }
                          metaVerificationStatus: { type: string }
        '400': { description: Plan limit reached or profileId required }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { description: A paid plan is required }

  /v1/whatsapp/phone-numbers/{phoneNumberId}:
    get:
      operationId: getWhatsAppPhoneNumber
      tags: [WhatsApp Phone Numbers]
      summary: Get phone number
      description: |
        Retrieve the current status of a purchased phone number. Used to poll for
        Meta pre-verification completion after purchase.
      security:
        - bearerAuth: []
      parameters:
        - name: phoneNumberId
          in: path
          required: true
          description: Phone number record ID
          schema:
            type: string
      responses:
        '200':
          description: Phone number retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  phoneNumber:
                    type: object
                    properties:
                      id: { type: string }
                      phoneNumber: { type: string }
                      status: { type: string, enum: [pending_payment, provisioning, active, suspended, releasing, released] }
                      country: { type: string }
                      metaPreverifiedId: { type: string }
                      metaVerificationStatus: { type: string }
                      provisionedAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: releaseWhatsAppPhoneNumber
      tags: [WhatsApp Phone Numbers]
      summary: Release phone number
      description: |
        Release a purchased phone number. This will:
        1. Disconnect any linked WhatsApp social account
        2. Decrement the Stripe subscription quantity (or cancel if last number)
        3. Release the number from Telnyx
        4. Mark the number as released
      security:
        - bearerAuth: []
      parameters:
        - name: phoneNumberId
          in: path
          required: true
          description: Phone number record ID
          schema:
            type: string
      responses:
        '200':
          description: Phone number released successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  phoneNumber:
                    type: object
                    properties:
                      id: { type: string }
                      phoneNumber: { type: string }
                      status: { type: string, description: "\"released\"" }
                      releasedAt: { type: string, format: date-time }
        '400': { description: Phone number is already released or being released }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  # ─── WhatsApp Group Chats (platform groups, not contact groups) ──

  /v1/whatsapp/wa-groups:
    get:
      operationId: listWhatsAppGroupChats
      tags: [WhatsApp]
      summary: List active groups
      description: |
        List active WhatsApp group chats for a business phone number.
        These are actual WhatsApp group conversations on the platform.
      security:
        - bearerAuth: []
      parameters:
        - { name: accountId, in: query, required: true, schema: { type: string }, description: WhatsApp social account ID }
        - { name: limit, in: query, schema: { type: integer, default: 25, maximum: 1024 }, description: Max groups to return }
        - { name: after, in: query, schema: { type: string }, description: Pagination cursor }
      responses:
        '200':
          description: List of active groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  groups:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, description: Group ID }
                        subject: { type: string, description: Group name }
                        createdAt: { type: string, description: Group creation timestamp }
                  paging:
                    type: object
                    properties:
                      cursors:
                        type: object
                        properties:
                          after: { type: string }
                          before: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      operationId: createWhatsAppGroupChat
      tags: [WhatsApp]
      summary: Create group
      description: |
        Create a new WhatsApp group chat. Returns the group ID and optionally an invite link.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId, subject]
              properties:
                accountId: { type: string, description: WhatsApp social account ID }
                subject: { type: string, maxLength: 128, description: Group name (max 128 characters) }
                description: { type: string, maxLength: 2048, description: Group description (max 2048 characters) }
                joinApprovalMode:
                  type: string
                  enum: [approval_required, auto_approve]
                  description: Whether users need approval to join via invite link
      responses:
        '201':
          description: Group created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  group:
                    type: object
                    properties:
                      groupId: { type: string }
                      inviteLink: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/whatsapp/wa-groups/{groupId}:
    get:
      operationId: getWhatsAppGroupChat
      tags: [WhatsApp]
      summary: Get group info
      description: |
        Retrieve metadata about a WhatsApp group including subject, description,
        participants, and settings.
      security:
        - bearerAuth: []
      parameters:
        - { name: groupId, in: path, required: true, schema: { type: string }, description: Group ID }
        - { name: accountId, in: query, required: true, schema: { type: string }, description: WhatsApp social account ID }
      responses:
        '200':
          description: Group info
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  group:
                    type: object
                    properties:
                      id: { type: string }
                      subject: { type: string }
                      description: { type: string }
                      joinApprovalMode: { type: string }
                      participants:
                        type: array
                        items:
                          type: object
                          properties:
                            user: { type: string, description: Phone number }
                            admin: { type: string }
                      participantCount: { type: integer }
                      createdAt: { type: integer, description: UNIX timestamp }
                      isSuspended: { type: boolean }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    post:
      operationId: updateWhatsAppGroupChat
      tags: [WhatsApp]
      summary: Update group settings
      description: |
        Update the subject, description, or join approval mode of a WhatsApp group.
      security:
        - bearerAuth: []
      parameters:
        - { name: groupId, in: path, required: true, schema: { type: string }, description: Group ID }
        - { name: accountId, in: query, required: true, schema: { type: string }, description: WhatsApp social account ID }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                subject: { type: string, maxLength: 128 }
                description: { type: string, maxLength: 2048 }
                joinApprovalMode: { type: string, enum: [approval_required, auto_approve] }
      responses:
        '200':
          description: Group updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: deleteWhatsAppGroupChat
      tags: [WhatsApp]
      summary: Delete group
      description: |
        Delete a WhatsApp group and remove all participants.
      security:
        - bearerAuth: []
      parameters:
        - { name: groupId, in: path, required: true, schema: { type: string }, description: Group ID }
        - { name: accountId, in: query, required: true, schema: { type: string }, description: WhatsApp social account ID }
      responses:
        '200':
          description: Group deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/whatsapp/wa-groups/{groupId}/participants:
    post:
      operationId: addWhatsAppGroupParticipants
      tags: [WhatsApp]
      summary: Add participants
      description: |
        Add participants to a WhatsApp group. Maximum 8 participants per request.
      security:
        - bearerAuth: []
      parameters:
        - { name: groupId, in: path, required: true, schema: { type: string }, description: Group ID }
        - { name: accountId, in: query, required: true, schema: { type: string }, description: WhatsApp social account ID }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [phoneNumbers]
              properties:
                phoneNumbers:
                  type: array
                  maxItems: 8
                  items: { type: string }
                  description: Phone numbers in E.164 format (max 8)
      responses:
        '200':
          description: Participants added
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
    delete:
      operationId: removeWhatsAppGroupParticipants
      tags: [WhatsApp]
      summary: Remove participants
      description: |
        Remove participants from a WhatsApp group.
      security:
        - bearerAuth: []
      parameters:
        - { name: groupId, in: path, required: true, schema: { type: string }, description: Group ID }
        - { name: accountId, in: query, required: true, schema: { type: string }, description: WhatsApp social account ID }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [phoneNumbers]
              properties:
                phoneNumbers:
                  type: array
                  items: { type: string }
                  description: Phone numbers to remove
      responses:
        '200':
          description: Participants removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/whatsapp/wa-groups/{groupId}/invite-link:
    post:
      operationId: createWhatsAppGroupInviteLink
      tags: [WhatsApp]
      summary: Create invite link
      description: |
        Create a new invite link for a WhatsApp group. The previous link is revoked.
      security:
        - bearerAuth: []
      parameters:
        - { name: groupId, in: path, required: true, schema: { type: string }, description: Group ID }
        - { name: accountId, in: query, required: true, schema: { type: string }, description: WhatsApp social account ID }
      responses:
        '200':
          description: Invite link created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  inviteLink: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/whatsapp/wa-groups/{groupId}/join-requests:
    get:
      operationId: listWhatsAppGroupJoinRequests
      tags: [WhatsApp]
      summary: List join requests
      description: |
        List pending join requests for a WhatsApp group (only for groups with approval_required mode).
      security:
        - bearerAuth: []
      parameters:
        - { name: groupId, in: path, required: true, schema: { type: string }, description: Group ID }
        - { name: accountId, in: query, required: true, schema: { type: string }, description: WhatsApp social account ID }
      responses:
        '200':
          description: Join requests
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  joinRequests:
                    type: array
                    items:
                      type: object
                      properties:
                        user: { type: string, description: Phone number }
                        timestamp: { type: integer, description: UNIX timestamp of request }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      operationId: approveWhatsAppGroupJoinRequests
      tags: [WhatsApp]
      summary: Approve join requests
      description: |
        Approve pending join requests for a WhatsApp group.
      security:
        - bearerAuth: []
      parameters:
        - { name: groupId, in: path, required: true, schema: { type: string }, description: Group ID }
        - { name: accountId, in: query, required: true, schema: { type: string }, description: WhatsApp social account ID }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [phoneNumbers]
              properties:
                phoneNumbers:
                  type: array
                  items: { type: string }
                  description: Phone numbers to approve
      responses:
        '200':
          description: Requests approved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
    delete:
      operationId: rejectWhatsAppGroupJoinRequests
      tags: [WhatsApp]
      summary: Reject join requests
      description: |
        Reject pending join requests for a WhatsApp group.
      security:
        - bearerAuth: []
      parameters:
        - { name: groupId, in: path, required: true, schema: { type: string }, description: Group ID }
        - { name: accountId, in: query, required: true, schema: { type: string }, description: WhatsApp social account ID }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [phoneNumbers]
              properties:
                phoneNumbers:
                  type: array
                  items: { type: string }
                  description: Phone numbers to reject
      responses:
        '200':
          description: Requests rejected
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }

  # ─── WhatsApp Flows ───────────────────────────────────────────────

  /v1/whatsapp/flows:
    get:
      operationId: listWhatsAppFlows
      tags: [WhatsApp Flows]
      summary: List flows
      description: |
        List all WhatsApp Flows for the Business Account (WABA) associated with the given account.
      security:
        - bearerAuth: []
      parameters:
        - { name: accountId, in: query, required: true, schema: { type: string }, description: WhatsApp social account ID }
      responses:
        '200':
          description: Flows retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  flows:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        name: { type: string }
                        status: { type: string, enum: [DRAFT, PUBLISHED, DEPRECATED, BLOCKED, THROTTLED] }
                        categories:
                          type: array
                          items: { type: string }
                        validation_errors:
                          type: array
                          items: { type: object }
        '400': { description: WABA ID not found on account }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }
    post:
      operationId: createWhatsAppFlow
      tags: [WhatsApp Flows]
      summary: Create flow
      description: |
        Create a new WhatsApp Flow in DRAFT status. Optionally clone an existing flow.
        After creating, upload a Flow JSON definition, then publish to make it sendable.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId, name, categories]
              properties:
                accountId: { type: string, description: WhatsApp social account ID }
                name: { type: string, maxLength: 128, description: Flow display name }
                categories:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    enum: [SIGN_UP, SIGN_IN, APPOINTMENT_BOOKING, LEAD_GENERATION, CONTACT_US, CUSTOMER_SUPPORT, SURVEY, OTHER]
                  description: Flow categories
                cloneFlowId: { type: string, description: "Optional: ID of an existing flow to clone" }
            examples:
              basic:
                summary: Create a lead generation flow
                value:
                  accountId: "507f1f77bcf86cd799439011"
                  name: "lead_capture_form"
                  categories: ["LEAD_GENERATION"]
      responses:
        '200':
          description: Flow created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  flow:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      status: { type: string, example: DRAFT }
                      categories:
                        type: array
                        items: { type: string }
        '400': { description: Validation error }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }

  /v1/whatsapp/flows/{flowId}:
    get:
      operationId: getWhatsAppFlow
      tags: [WhatsApp Flows]
      summary: Get flow
      description: |
        Get details for a specific flow, including status, categories, validation errors, and preview URL.
      security:
        - bearerAuth: []
      parameters:
        - { name: flowId, in: path, required: true, schema: { type: string }, description: Flow ID }
        - { name: accountId, in: query, required: true, schema: { type: string }, description: WhatsApp social account ID }
        - { name: fields, in: query, schema: { type: string }, description: "Comma-separated fields to return (default: id,name,status,categories,validation_errors,json_version,preview,data_api_version,endpoint_uri)" }
      responses:
        '200':
          description: Flow details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  flow:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      status: { type: string }
                      categories:
                        type: array
                        items: { type: string }
                      validation_errors:
                        type: array
                        items: { type: object }
                      json_version: { type: string }
                      preview:
                        type: object
                        properties:
                          preview_url: { type: string }
                          expires_at: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: Flow or account not found }
    patch:
      operationId: updateWhatsAppFlow
      tags: [WhatsApp Flows]
      summary: Update flow
      description: |
        Update metadata (name, categories) of a DRAFT flow. Published flows are immutable.
      security:
        - bearerAuth: []
      parameters:
        - { name: flowId, in: path, required: true, schema: { type: string }, description: Flow ID }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId]
              properties:
                accountId: { type: string, description: WhatsApp social account ID }
                name: { type: string, maxLength: 128, description: New flow name }
                categories:
                  type: array
                  minItems: 1
                  items:
                    type: string
                    enum: [SIGN_UP, SIGN_IN, APPOINTMENT_BOOKING, LEAD_GENERATION, CONTACT_US, CUSTOMER_SUPPORT, SURVEY, OTHER]
      responses:
        '200':
          description: Flow updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
        '400': { description: "At least one of name or categories is required, or flow is not in DRAFT status" }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account or flow not found }
    delete:
      operationId: deleteWhatsAppFlow
      tags: [WhatsApp Flows]
      summary: Delete flow
      description: |
        Delete a DRAFT flow. This is irreversible. Only flows in DRAFT status can be deleted.
      security:
        - bearerAuth: []
      parameters:
        - { name: flowId, in: path, required: true, schema: { type: string }, description: Flow ID }
        - { name: accountId, in: query, required: true, schema: { type: string }, description: WhatsApp social account ID }
      responses:
        '200':
          description: Flow deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
        '400': { description: Flow is not in DRAFT status }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account or flow not found }

  /v1/whatsapp/flows/{flowId}/json:
    get:
      operationId: getWhatsAppFlowJson
      tags: [WhatsApp Flows]
      summary: Get flow JSON asset
      description: |
        Get the flow JSON asset metadata, including a temporary download URL for the Flow JSON file.
      security:
        - bearerAuth: []
      parameters:
        - { name: flowId, in: path, required: true, schema: { type: string }, description: Flow ID }
        - { name: accountId, in: query, required: true, schema: { type: string }, description: WhatsApp social account ID }
      responses:
        '200':
          description: Flow JSON asset
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  assets:
                    type: array
                    items:
                      type: object
                      properties:
                        name: { type: string, example: flow.json }
                        asset_type: { type: string, example: FLOW_JSON }
                        download_url: { type: string, description: Temporary URL to download the flow JSON }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }
    put:
      operationId: uploadWhatsAppFlowJson
      tags: [WhatsApp Flows]
      summary: Upload flow JSON
      description: |
        Upload or update the Flow JSON for a DRAFT flow. The Flow JSON defines all screens,
        components (text inputs, dropdowns, date pickers, etc.), and navigation.

        Meta validates the JSON on upload and returns any validation errors.
        See: https://developers.facebook.com/docs/whatsapp/flows/reference/flowjson
      security:
        - bearerAuth: []
      parameters:
        - { name: flowId, in: path, required: true, schema: { type: string }, description: Flow ID }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId, flow_json]
              properties:
                accountId: { type: string, description: WhatsApp social account ID }
                flow_json:
                  description: "The Flow JSON content. Pass as a JSON object or a JSON string."
                  oneOf:
                    - type: object
                    - type: string
            examples:
              simple_form:
                summary: Simple lead capture form
                value:
                  accountId: "507f1f77bcf86cd799439011"
                  flow_json:
                    version: "6.0"
                    screens:
                      - id: "LEAD_FORM"
                        title: "Get a Quote"
                        terminal: true
                        success: true
                        layout:
                          type: "SingleColumnLayout"
                          children:
                            - type: "TextInput"
                              name: "full_name"
                              label: "Full Name"
                              required: true
                              input-type: "text"
                            - type: "TextInput"
                              name: "email"
                              label: "Email"
                              required: true
                              input-type: "email"
                            - type: "Footer"
                              label: "Submit"
                              on-click-action:
                                name: "complete"
                                payload:
                                  full_name: "${form.full_name}"
                                  email: "${form.email}"
      responses:
        '200':
          description: Flow JSON uploaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  validation_errors:
                    type: array
                    description: "Empty array if valid; otherwise, contains validation error details from Meta"
                    items:
                      type: object
                      properties:
                        error: { type: string }
                        error_type: { type: string }
                        message: { type: string }
                        line_start: { type: integer }
                        line_end: { type: integer }
                        column_start: { type: integer }
                        column_end: { type: integer }
        '400': { description: Invalid JSON or flow is not in DRAFT status }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }

  /v1/whatsapp/flows/{flowId}/publish:
    post:
      operationId: publishWhatsAppFlow
      tags: [WhatsApp Flows]
      summary: Publish flow
      description: |
        Publish a DRAFT flow. **This is irreversible.** Once published, the flow and its JSON
        become immutable and the flow can be sent to users. To update a published flow,
        create a new flow (optionally cloning this one via `cloneFlowId`).
      security:
        - bearerAuth: []
      parameters:
        - { name: flowId, in: path, required: true, schema: { type: string }, description: Flow ID }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId]
              properties:
                accountId: { type: string, description: WhatsApp social account ID }
      responses:
        '200':
          description: Flow published
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
        '400': { description: Flow is not in DRAFT status or has validation errors }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }

  /v1/whatsapp/flows/{flowId}/deprecate:
    post:
      operationId: deprecateWhatsAppFlow
      tags: [WhatsApp Flows]
      summary: Deprecate flow
      description: |
        Deprecate a PUBLISHED flow. **This is irreversible.** Deprecated flows cannot be sent
        or opened, but existing active sessions may continue until they complete.
      security:
        - bearerAuth: []
      parameters:
        - { name: flowId, in: path, required: true, schema: { type: string }, description: Flow ID }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId]
              properties:
                accountId: { type: string, description: WhatsApp social account ID }
      responses:
        '200':
          description: Flow deprecated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
        '400': { description: Flow is not in PUBLISHED status }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }

  /v1/whatsapp/flows/send:
    post:
      operationId: sendWhatsAppFlowMessage
      tags: [WhatsApp Flows]
      summary: Send flow message
      description: |
        Send a published flow as an interactive message with a CTA button.
        When the recipient taps the button, the flow opens natively in WhatsApp.
        Flow responses are received via webhooks.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId, to, flow_id, flow_cta, body]
              properties:
                accountId: { type: string, description: WhatsApp social account ID }
                to: { type: string, description: "Recipient phone number (E.164 format, e.g. +1234567890)" }
                flow_id: { type: string, description: Published flow ID }
                flow_cta: { type: string, maxLength: 20, description: "CTA button text (e.g. 'Book Now', 'Sign Up')" }
                flow_action:
                  type: string
                  enum: [navigate, data_exchange]
                  default: navigate
                  description: "Action type: navigate opens a screen directly, data_exchange hits your endpoint first"
                flow_token: { type: string, maxLength: 200, description: "Unique token to correlate responses. Auto-generated UUID if omitted." }
                flow_action_payload:
                  type: object
                  properties:
                    screen: { type: string, description: First screen ID to navigate to }
                    data:
                      type: object
                      description: Optional data to pass to the screen
                body: { type: string, description: Message body text }
                header:
                  type: object
                  properties:
                    type: { type: string, enum: [text] }
                    text: { type: string }
                footer: { type: string, description: Optional footer text }
                draft: { type: boolean, description: "Set true to test an unpublished (DRAFT) flow" }
            examples:
              basic:
                summary: Send a lead capture flow
                value:
                  accountId: "507f1f77bcf86cd799439011"
                  to: "+1234567890"
                  flow_id: "1234567890"
                  flow_cta: "Get a Quote"
                  flow_action: "navigate"
                  flow_action_payload:
                    screen: "LEAD_FORM"
                  body: "Hi! Fill out this quick form to get a personalized quote."
      responses:
        '200':
          description: Flow message sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  messageId: { type: string, description: WhatsApp message ID (WAMID) }
        '400': { description: Validation error or missing phone number ID }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { description: WhatsApp account not found }

  # ─── Contacts ─────────────────────────────────────────────────────

  /v1/contacts:
    get:
      operationId: listContacts
      summary: List contacts
      description: List and search contacts for a profile. Supports filtering by tags, platform, subscription status, and full-text search.
      tags: [Contacts]
      parameters:
        - { name: profileId, in: query, schema: { type: string }, description: Filter by profile. Omit to list across all profiles }
        - { name: search, in: query, schema: { type: string } }
        - { name: tag, in: query, schema: { type: string } }
        - { name: platform, in: query, schema: { type: string, enum: [instagram, facebook, telegram, twitter, bluesky, reddit, whatsapp] } }
        - { name: isSubscribed, in: query, schema: { type: string, enum: ['true', 'false'] } }
        - { name: limit, in: query, schema: { type: integer, default: 50, maximum: 200 } }
        - { name: skip, in: query, schema: { type: integer, default: 0 } }
      responses:
        '200':
          description: Contacts list with pagination and filter metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  contacts:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        name: { type: string }
                        email: { type: string }
                        company: { type: string }
                        avatarUrl: { type: string }
                        tags: { type: array, items: { type: string } }
                        isSubscribed: { type: boolean }
                        isBlocked: { type: boolean }
                        lastMessageSentAt: { type: string, format: date-time }
                        lastMessageReceivedAt: { type: string, format: date-time }
                        messagesSentCount: { type: integer }
                        messagesReceivedCount: { type: integer }
                        customFields: { type: object }
                        notes: { type: string }
                        createdAt: { type: string, format: date-time }
                        platform: { type: string }
                        platformIdentifier: { type: string }
                        displayIdentifier: { type: string }
                  filters:
                    type: object
                    properties:
                      tags: { type: array, items: { type: string } }
                  pagination:
                    type: object
                    properties:
                      total: { type: integer }
                      limit: { type: integer }
                      skip: { type: integer }
                      hasMore: { type: boolean }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      operationId: createContact
      summary: Create a contact
      description: Create a new contact. Optionally create a platform channel in the same request by providing accountId, platform, and platformIdentifier.
      tags: [Contacts]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [profileId, name]
              properties:
                profileId: { type: string }
                name: { type: string }
                email: { type: string }
                company: { type: string }
                tags: { type: array, items: { type: string } }
                isSubscribed: { type: boolean, default: true }
                notes: { type: string }
                accountId: { type: string, description: Optional. Creates a channel if provided with platform + platformIdentifier }
                platform: { type: string }
                platformIdentifier: { type: string }
                displayIdentifier: { type: string }
      responses:
        '200':
          description: Contact created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  contact:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      email: { type: string }
                      company: { type: string }
                      tags: { type: array, items: { type: string } }
                      isSubscribed: { type: boolean }
                      isBlocked: { type: boolean }
                      customFields: { type: object }
                      notes: { type: string }
                      createdAt: { type: string, format: date-time }
                  channel:
                    type: object
                    description: Created when accountId, platform, and platformIdentifier are provided
                    properties:
                      id: { type: string }
                      platform: { type: string }
                      platformIdentifier: { type: string }
                      displayIdentifier: { type: string }
                  warning: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '409': { description: Duplicate contact }

  /v1/contacts/{contactId}:
    get:
      operationId: getContact
      summary: Get contact with channels
      tags: [Contacts]
      parameters:
        - { name: contactId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Contact with channels
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  contact:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      email: { type: string }
                      company: { type: string }
                      avatarUrl: { type: string }
                      tags: { type: array, items: { type: string } }
                      isSubscribed: { type: boolean }
                      isBlocked: { type: boolean }
                      customFields: { type: object }
                      notes: { type: string }
                      conversationIds: { type: array, items: { type: string } }
                      createdAt: { type: string, format: date-time }
                      updatedAt: { type: string, format: date-time }
                  channels:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        accountId: { type: string }
                        platform: { type: string }
                        platformIdentifier: { type: string }
                        displayIdentifier: { type: string }
                        isSubscribed: { type: boolean }
                        conversationId: { type: string }
                        createdAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      operationId: updateContact
      summary: Update a contact
      tags: [Contacts]
      parameters:
        - { name: contactId, in: path, required: true, schema: { type: string } }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                email: { type: string }
                company: { type: string }
                avatarUrl: { type: string }
                tags: { type: array, items: { type: string } }
                isSubscribed: { type: boolean }
                isBlocked: { type: boolean }
                notes: { type: string }
      responses:
        '200':
          description: Contact updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  contact:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      email: { type: string }
                      company: { type: string }
                      avatarUrl: { type: string }
                      tags: { type: array, items: { type: string } }
                      isSubscribed: { type: boolean }
                      isBlocked: { type: boolean }
                      notes: { type: string }
                      updatedAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: deleteContact
      summary: Delete a contact
      tags: [Contacts]
      parameters:
        - { name: contactId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Contact deleted }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/contacts/{contactId}/channels:
    get:
      operationId: getContactChannels
      summary: List channels for a contact
      tags: [Contacts]
      parameters:
        - { name: contactId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: List of contact channels
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  channels:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        accountId: { type: string }
                        platform: { type: string }
                        platformIdentifier: { type: string }
                        displayIdentifier: { type: string }
                        isSubscribed: { type: boolean }
                        conversationId: { type: string }
                        metadata: { type: object }
                        createdAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/contacts/bulk:
    post:
      operationId: bulkCreateContacts
      summary: Bulk create contacts
      description: Import up to 1000 contacts at a time. Skips duplicates.
      tags: [Contacts]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [profileId, accountId, platform, contacts]
              properties:
                profileId: { type: string }
                accountId: { type: string }
                platform: { type: string }
                contacts:
                  type: array
                  maxItems: 1000
                  items:
                    type: object
                    required: [name, platformIdentifier]
                    properties:
                      name: { type: string }
                      platformIdentifier: { type: string }
                      displayIdentifier: { type: string }
                      email: { type: string }
                      company: { type: string }
                      tags: { type: array, items: { type: string } }
      responses:
        '200':
          description: Bulk import results
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  created: { type: integer }
                  skipped: { type: integer }
                  errors: { type: array, items: { type: object } }
                  total: { type: integer }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/contacts/{contactId}/fields/{slug}:
    put:
      operationId: setContactFieldValue
      summary: Set a custom field value
      tags: [Custom Fields]
      parameters:
        - { name: contactId, in: path, required: true, schema: { type: string } }
        - { name: slug, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [value]
              properties:
                value: { description: Field value (type depends on field definition) }
      responses:
        '200': { description: Field value set }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: clearContactFieldValue
      summary: Clear a custom field value
      tags: [Custom Fields]
      parameters:
        - { name: contactId, in: path, required: true, schema: { type: string } }
        - { name: slug, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Field value cleared }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  # ─── Custom Fields ────────────────────────────────────────────────

  /v1/custom-fields:
    get:
      operationId: listCustomFields
      summary: List custom field definitions
      tags: [Custom Fields]
      parameters:
        - { name: profileId, in: query, schema: { type: string }, description: Filter by profile. Omit to list across all profiles }
      responses:
        '200':
          description: List of custom field definitions
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  fields:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        name: { type: string }
                        slug: { type: string }
                        type: { type: string, enum: [text, number, date, boolean, select] }
                        options: { type: array, items: { type: string } }
                        createdAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      operationId: createCustomField
      summary: Create a custom field definition
      tags: [Custom Fields]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [profileId, name, type]
              properties:
                profileId: { type: string }
                name: { type: string }
                slug: { type: string, description: Auto-generated from name if not provided }
                type: { type: string, enum: [text, number, date, boolean, select] }
                options: { type: array, items: { type: string }, description: Required for select type }
      responses:
        '200':
          description: Custom field created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  field:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      slug: { type: string }
                      type: { type: string, enum: [text, number, date, boolean, select] }
                      options: { type: array, items: { type: string } }
                      createdAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '409': { description: Duplicate slug }

  /v1/custom-fields/{fieldId}:
    patch:
      operationId: updateCustomField
      summary: Update a custom field definition
      tags: [Custom Fields]
      parameters:
        - { name: fieldId, in: path, required: true, schema: { type: string } }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                options: { type: array, items: { type: string } }
      responses:
        '200':
          description: Custom field updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  field:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      slug: { type: string }
                      type: { type: string }
                      options: { type: array, items: { type: string } }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: deleteCustomField
      summary: Delete a custom field definition
      tags: [Custom Fields]
      parameters:
        - { name: fieldId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Custom field deleted }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  # ─── Broadcasts ───────────────────────────────────────────────────

  /v1/broadcasts:
    get:
      operationId: listBroadcasts
      summary: List broadcasts
      tags: [Broadcasts]
      parameters:
        - { name: profileId, in: query, schema: { type: string }, description: Filter by profile. Omit to list across all profiles }
        - { name: status, in: query, schema: { type: string, enum: [draft, scheduled, sending, completed, failed, cancelled] } }
        - { name: platform, in: query, schema: { type: string } }
        - { name: limit, in: query, schema: { type: integer, default: 50 } }
        - { name: skip, in: query, schema: { type: integer, default: 0 } }
      responses:
        '200':
          description: Broadcasts list
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  broadcasts:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        name: { type: string }
                        description: { type: string }
                        platform: { type: string }
                        accountId: { type: string }
                        accountName: { type: string, description: Display name of the sending account }
                        status: { type: string, enum: [draft, scheduled, sending, completed, failed, cancelled] }
                        messagePreview: { type: string, description: Template name or message text snippet }
                        scheduledAt: { type: string, format: date-time }
                        startedAt: { type: string, format: date-time }
                        completedAt: { type: string, format: date-time }
                        recipientCount: { type: integer }
                        sentCount: { type: integer }
                        deliveredCount: { type: integer }
                        readCount: { type: integer }
                        failedCount: { type: integer }
                        createdAt: { type: string, format: date-time }
                  pagination:
                    type: object
                    properties:
                      total: { type: integer }
                      limit: { type: integer }
                      skip: { type: integer }
                      hasMore: { type: boolean }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      operationId: createBroadcast
      summary: Create a broadcast draft
      tags: [Broadcasts]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [profileId, accountId, platform, name]
              properties:
                profileId: { type: string }
                accountId: { type: string }
                platform: { type: string, enum: [instagram, facebook, telegram, twitter, bluesky, reddit, whatsapp] }
                name: { type: string }
                description: { type: string }
                message:
                  type: object
                  properties:
                    text: { type: string }
                    attachments: { type: array, items: { type: object, properties: { type: { type: string }, url: { type: string }, filename: { type: string } } } }
                template:
                  type: object
                  description: WhatsApp template (required when platform is whatsapp)
                  properties:
                    name: { type: string }
                    language: { type: string }
                    components: { type: array }
                segmentFilters:
                  type: object
                  properties:
                    tags: { type: array, items: { type: string } }
                    isSubscribed: { type: boolean }
      responses:
        '200':
          description: Broadcast created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  broadcast:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      description: { type: string }
                      platform: { type: string }
                      accountId: { type: string }
                      status: { type: string }
                      createdAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/broadcasts/{broadcastId}:
    get:
      operationId: getBroadcast
      summary: Get broadcast details
      tags: [Broadcasts]
      parameters:
        - { name: broadcastId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Broadcast details with stats
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  broadcast:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      description: { type: string }
                      platform: { type: string }
                      accountId: { type: string }
                      message: { type: object, properties: { text: { type: string } } }
                      template: { type: object, properties: { name: { type: string }, language: { type: string } } }
                      segmentFilters: { type: object, properties: { tags: { type: array, items: { type: string } } } }
                      status: { type: string, enum: [draft, scheduled, sending, completed, failed, cancelled] }
                      scheduledAt: { type: string, format: date-time }
                      startedAt: { type: string, format: date-time }
                      completedAt: { type: string, format: date-time }
                      recipientCount: { type: integer }
                      sentCount: { type: integer }
                      deliveredCount: { type: integer }
                      readCount: { type: integer }
                      failedCount: { type: integer }
                      createdAt: { type: string, format: date-time }
                      updatedAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      operationId: updateBroadcast
      summary: Update a broadcast
      tags: [Broadcasts]
      parameters:
        - { name: broadcastId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Broadcast updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  broadcast:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      description: { type: string }
                      status: { type: string }
                      updatedAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: deleteBroadcast
      summary: Delete a broadcast (draft only)
      tags: [Broadcasts]
      parameters:
        - { name: broadcastId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Broadcast deleted }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/broadcasts/{broadcastId}/send:
    post:
      operationId: sendBroadcast
      summary: Trigger immediate send
      tags: [Broadcasts]
      parameters:
        - { name: broadcastId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Broadcast sending started
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  status: { type: string, enum: [sending, completed, failed], description: Current broadcast status after processing first batch }
                  sent: { type: integer, description: Recipients sent in this batch }
                  failed: { type: integer, description: Recipients failed in this batch }
                  recipientCount: { type: integer, description: Total recipient count }
        '400': { description: Invalid status or no recipients }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/broadcasts/{broadcastId}/schedule:
    post:
      operationId: scheduleBroadcast
      summary: Schedule broadcast for later
      tags: [Broadcasts]
      parameters:
        - { name: broadcastId, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [scheduledAt]
              properties:
                scheduledAt: { type: string, format: date-time }
      responses:
        '200':
          description: Broadcast scheduled
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  broadcast:
                    type: object
                    properties:
                      id: { type: string }
                      status: { type: string }
                      scheduledAt: { type: string, format: date-time }
        '400': { description: Invalid date or status }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/broadcasts/{broadcastId}/cancel:
    post:
      operationId: cancelBroadcast
      summary: Cancel a broadcast
      tags: [Broadcasts]
      parameters:
        - { name: broadcastId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Broadcast cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  broadcast:
                    type: object
                    properties:
                      id: { type: string }
                      status: { type: string }
        '400': { description: Cannot cancel in current status }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/broadcasts/{broadcastId}/recipients:
    get:
      operationId: listBroadcastRecipients
      summary: List broadcast recipients
      tags: [Broadcasts]
      parameters:
        - { name: broadcastId, in: path, required: true, schema: { type: string } }
        - { name: status, in: query, schema: { type: string, enum: [pending, sent, delivered, read, failed] } }
        - { name: limit, in: query, schema: { type: integer, default: 50 } }
        - { name: skip, in: query, schema: { type: integer, default: 0 } }
      responses:
        '200':
          description: Recipients list with delivery status
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  recipients:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        contactId: { type: string }
                        channelId: { type: string }
                        platformIdentifier: { type: string }
                        contactName: { type: string }
                        status: { type: string, enum: [pending, sent, delivered, read, failed] }
                        messageId: { type: string }
                        error: { type: string }
                        sentAt: { type: string, format: date-time }
                        deliveredAt: { type: string, format: date-time }
                        readAt: { type: string, format: date-time }
                  pagination:
                    type: object
                    properties:
                      total: { type: integer }
                      limit: { type: integer }
                      skip: { type: integer }
                      hasMore: { type: boolean }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    post:
      operationId: addBroadcastRecipients
      summary: Add recipients to a broadcast
      tags: [Broadcasts]
      parameters:
        - { name: broadcastId, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contactIds: { type: array, items: { type: string }, description: Specific contact IDs to add }
                phones: { type: array, items: { type: string }, description: Raw phone numbers (auto-creates contacts). Useful for WhatsApp/Telegram manual entry }
                useSegment: { type: boolean, description: Auto-populate from broadcast segment filters }
      responses:
        '200':
          description: Recipients added
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  added: { type: integer, description: Number of recipients successfully added }
                  skipped: { type: integer, description: Number skipped (duplicates or missing channels) }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  # ─── Sequences ────────────────────────────────────────────────────

  /v1/sequences:
    get:
      operationId: listSequences
      summary: List sequences
      tags: [Sequences]
      parameters:
        - { name: profileId, in: query, schema: { type: string }, description: Filter by profile. Omit to list across all profiles }
        - { name: status, in: query, schema: { type: string, enum: [draft, active, paused] } }
        - { name: limit, in: query, schema: { type: integer, default: 50 } }
        - { name: skip, in: query, schema: { type: integer, default: 0 } }
      responses:
        '200':
          description: Sequences list
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  sequences:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        name: { type: string }
                        description: { type: string }
                        platform: { type: string }
                        accountId: { type: string }
                        accountName: { type: string, description: Display name of the sending account }
                        messagePreview: { type: string, description: First step template name or message text snippet }
                        status: { type: string, enum: [draft, active, paused] }
                        stepsCount: { type: integer }
                        exitOnReply: { type: boolean }
                        exitOnUnsubscribe: { type: boolean }
                        totalEnrolled: { type: integer }
                        totalCompleted: { type: integer }
                        totalExited: { type: integer }
                        createdAt: { type: string, format: date-time }
                  pagination:
                    type: object
                    properties:
                      total: { type: integer }
                      limit: { type: integer }
                      skip: { type: integer }
                      hasMore: { type: boolean }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      operationId: createSequence
      summary: Create a sequence
      tags: [Sequences]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [profileId, accountId, platform, name]
              properties:
                profileId: { type: string }
                accountId: { type: string }
                platform: { type: string, enum: [instagram, facebook, telegram, twitter, bluesky, reddit, whatsapp] }
                name: { type: string }
                description: { type: string }
                steps:
                  type: array
                  items:
                    type: object
                    required: [order, delayMinutes]
                    properties:
                      order: { type: integer }
                      delayMinutes: { type: integer }
                      message: { type: object, properties: { text: { type: string } } }
                      template:
                        type: object
                        properties:
                          name: { type: string }
                          language: { type: string }
                          variableMapping:
                            type: object
                            description: Maps template variable positions to contact fields. Keys are position strings ("1", "2"), values are objects with field and optional customValue
                            additionalProperties:
                              type: object
                              properties:
                                field: { type: string, enum: [name, phone, email, company, custom] }
                                customValue: { type: string, description: Static value when field is "custom" }
                exitOnReply: { type: boolean, default: true }
                exitOnUnsubscribe: { type: boolean, default: true }
      responses:
        '200':
          description: Sequence created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  sequence:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      description: { type: string }
                      platform: { type: string }
                      status: { type: string }
                      stepsCount: { type: integer }
                      createdAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }

  /v1/sequences/{sequenceId}:
    get:
      operationId: getSequence
      summary: Get sequence with steps
      tags: [Sequences]
      parameters:
        - { name: sequenceId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Sequence details with steps
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  sequence:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      description: { type: string }
                      platform: { type: string }
                      accountId: { type: string }
                      status: { type: string, enum: [draft, active, paused] }
                      steps:
                        type: array
                        items:
                          type: object
                          properties:
                            order: { type: integer }
                            delayMinutes: { type: integer }
                            message: { type: object, properties: { text: { type: string } } }
                            template: { type: object, properties: { name: { type: string }, language: { type: string }, variableMapping: { type: object } } }
                      exitOnReply: { type: boolean }
                      exitOnUnsubscribe: { type: boolean }
                      totalEnrolled: { type: integer }
                      totalCompleted: { type: integer }
                      totalExited: { type: integer }
                      createdAt: { type: string, format: date-time }
                      updatedAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      operationId: updateSequence
      summary: Update a sequence
      tags: [Sequences]
      parameters:
        - { name: sequenceId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Sequence updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  sequence:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      description: { type: string }
                      status: { type: string }
                      steps: { type: array, items: { type: object } }
                      exitOnReply: { type: boolean }
                      exitOnUnsubscribe: { type: boolean }
                      updatedAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: deleteSequence
      summary: Delete a sequence
      tags: [Sequences]
      parameters:
        - { name: sequenceId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Sequence deleted }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/sequences/{sequenceId}/activate:
    post:
      operationId: activateSequence
      summary: Activate a sequence
      tags: [Sequences]
      parameters:
        - { name: sequenceId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Sequence activated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  sequence:
                    type: object
                    properties:
                      id: { type: string }
                      status: { type: string }
        '400': { description: Invalid status or no steps }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/sequences/{sequenceId}/pause:
    post:
      operationId: pauseSequence
      summary: Pause a sequence
      tags: [Sequences]
      parameters:
        - { name: sequenceId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Sequence paused
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  sequence:
                    type: object
                    properties:
                      id: { type: string }
                      status: { type: string }
        '400': { description: Sequence is not active }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/sequences/{sequenceId}/enroll:
    post:
      operationId: enrollContacts
      summary: Enroll contacts in a sequence
      tags: [Sequences]
      parameters:
        - { name: sequenceId, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [contactIds]
              properties:
                contactIds: { type: array, items: { type: string } }
                channelIds: { type: array, items: { type: string }, description: Optional. Auto-detected if not provided. }
      responses:
        '200':
          description: Enrollment results
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  enrolled: { type: integer, description: Number of contacts successfully enrolled }
                  skipped: { type: integer, description: Number skipped (already enrolled or missing channel) }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/sequences/{sequenceId}/enroll/{contactId}:
    delete:
      operationId: unenrollContact
      summary: Unenroll a contact from a sequence
      tags: [Sequences]
      parameters:
        - { name: sequenceId, in: path, required: true, schema: { type: string } }
        - { name: contactId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Contact unenrolled }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/sequences/{sequenceId}/enrollments:
    get:
      operationId: listSequenceEnrollments
      summary: List enrollments for a sequence
      tags: [Sequences]
      parameters:
        - { name: sequenceId, in: path, required: true, schema: { type: string } }
        - { name: status, in: query, schema: { type: string, enum: [active, completed, exited, paused] } }
        - { name: limit, in: query, schema: { type: integer, default: 50 } }
        - { name: skip, in: query, schema: { type: integer, default: 0 } }
      responses:
        '200':
          description: Enrollments list with progress
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  enrollments:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        contactId: { type: string }
                        channelId: { type: string }
                        platformIdentifier: { type: string }
                        contactName: { type: string }
                        currentStepIndex: { type: integer }
                        status: { type: string, enum: [active, completed, exited, paused] }
                        exitReason: { type: string }
                        nextStepAt: { type: string, format: date-time }
                        stepsSent: { type: integer }
                        lastStepSentAt: { type: string, format: date-time }
                        createdAt: { type: string, format: date-time }
                  pagination:
                    type: object
                    properties:
                      total: { type: integer }
                      limit: { type: integer }
                      skip: { type: integer }
                      hasMore: { type: boolean }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  # ──────────────────────────────────────────────────────────────────────────
  # COMMENT AUTOMATIONS (Comment-to-DM)
  # ──────────────────────────────────────────────────────────────────────────

  /v1/comment-automations:
    get:
      operationId: listCommentAutomations
      tags: [Comment Automations]
      summary: List comment-to-DM automations
      description: List all comment-to-DM automations for a profile. Returns automations with their stats.
      security:
        - bearerAuth: []
      parameters:
        - { name: profileId, in: query, schema: { type: string }, description: Filter by profile. Omit to list across all profiles }
      responses:
        '200':
          description: Automations list
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  automations:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        name: { type: string }
                        platform: { type: string, enum: [instagram, facebook] }
                        accountId: { type: string }
                        platformPostId: { type: string }
                        postTitle: { type: string }
                        keywords: { type: array, items: { type: string } }
                        matchMode: { type: string, enum: [exact, contains] }
                        dmMessage: { type: string }
                        commentReply: { type: string }
                        isActive: { type: boolean }
                        stats:
                          type: object
                          properties:
                            triggered: { type: integer }
                            dmsSent: { type: integer }
                            dmsFailed: { type: integer }
                            uniqueContacts: { type: integer }
                        createdAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      operationId: createCommentAutomation
      tags: [Comment Automations]
      summary: Create a comment-to-DM automation
      description: |
        Create a keyword-triggered DM automation on an Instagram or Facebook post.
        When someone comments a matching keyword, they automatically receive a DM.
        Only one active automation per post is allowed.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [profileId, accountId, platformPostId, name, dmMessage]
              properties:
                profileId: { type: string }
                accountId: { type: string, description: Instagram or Facebook account ID }
                platformPostId: { type: string, description: Platform media/post ID }
                postId: { type: string, description: Zernio post ID (optional) }
                postTitle: { type: string, description: Post content snippet for display }
                name: { type: string, description: Automation label }
                keywords:
                  type: array
                  items: { type: string }
                  description: Trigger keywords (empty = any comment triggers)
                matchMode: { type: string, enum: [exact, contains], default: contains }
                dmMessage: { type: string, description: DM text to send to commenter }
                commentReply: { type: string, description: Optional public reply to the comment }
      responses:
        '200':
          description: Automation created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  automation:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      platform: { type: string }
                      platformPostId: { type: string }
                      keywords: { type: array, items: { type: string } }
                      matchMode: { type: string, enum: [exact, contains] }
                      dmMessage: { type: string }
                      commentReply: { type: string }
                      isActive: { type: boolean }
                      stats: { type: object, properties: { totalTriggered: { type: integer }, totalSent: { type: integer }, totalFailed: { type: integer } } }
                      createdAt: { type: string, format: date-time }
        '400': { description: Validation error }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '409': { description: Active automation already exists for this post }

  /v1/comment-automations/{automationId}:
    get:
      operationId: getCommentAutomation
      tags: [Comment Automations]
      summary: Get automation details with recent logs
      security:
        - bearerAuth: []
      parameters:
        - { name: automationId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Automation details with stats and recent trigger logs
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  automation:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      platform: { type: string }
                      accountId: { type: string }
                      platformPostId: { type: string }
                      postId: { type: string }
                      postTitle: { type: string }
                      keywords: { type: array, items: { type: string } }
                      matchMode: { type: string, enum: [exact, contains] }
                      dmMessage: { type: string }
                      commentReply: { type: string }
                      isActive: { type: boolean }
                      stats: { type: object, properties: { totalTriggered: { type: integer }, totalSent: { type: integer }, totalFailed: { type: integer } } }
                      createdAt: { type: string, format: date-time }
                      updatedAt: { type: string, format: date-time }
                  logs:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        commentId: { type: string }
                        commenterId: { type: string }
                        commenterName: { type: string }
                        commentText: { type: string }
                        status: { type: string, enum: [sent, failed, skipped] }
                        error: { type: string }
                        createdAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      operationId: updateCommentAutomation
      tags: [Comment Automations]
      summary: Update automation settings
      security:
        - bearerAuth: []
      parameters:
        - { name: automationId, in: path, required: true, schema: { type: string } }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                keywords: { type: array, items: { type: string } }
                matchMode: { type: string, enum: [exact, contains] }
                dmMessage: { type: string }
                commentReply: { type: string }
                isActive: { type: boolean }
      responses:
        '200':
          description: Automation updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  automation:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      keywords: { type: array, items: { type: string } }
                      matchMode: { type: string, enum: [exact, contains] }
                      dmMessage: { type: string }
                      commentReply: { type: string }
                      isActive: { type: boolean }
                      updatedAt: { type: string, format: date-time }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: deleteCommentAutomation
      tags: [Comment Automations]
      summary: Delete automation and all logs
      security:
        - bearerAuth: []
      parameters:
        - { name: automationId, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: Automation deleted }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/comment-automations/{automationId}/logs:
    get:
      operationId: listCommentAutomationLogs
      tags: [Comment Automations]
      summary: List trigger logs for an automation
      description: Paginated list of every comment that triggered this automation, with send status and commenter info.
      security:
        - bearerAuth: []
      parameters:
        - { name: automationId, in: path, required: true, schema: { type: string } }
        - { name: status, in: query, schema: { type: string, enum: [sent, failed, skipped] }, description: Filter by result status }
        - { name: limit, in: query, schema: { type: integer, default: 50 } }
        - { name: skip, in: query, schema: { type: integer, default: 0 } }
      responses:
        '200':
          description: Trigger logs with pagination
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: boolean }
                  logs:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        commentId: { type: string }
                        commenterId: { type: string }
                        commenterName: { type: string }
                        commentText: { type: string }
                        status: { type: string, enum: [sent, failed, skipped] }
                        error: { type: string }
                        createdAt: { type: string, format: date-time }
                  pagination:
                    type: object
                    properties:
                      total: { type: integer }
                      limit: { type: integer }
                      skip: { type: integer }
                      hasMore: { type: boolean }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  # ── Ads ──────────────────────────────────────────────────────────────────

  /v1/ads:
    get:
      operationId: listAds
      tags: [Ads]
      summary: List ads
      description: |
        Returns a paginated list of ads with metrics computed over an optional date range.
        Use `source=all` to include externally-synced ads from platform ad managers.
        If no date range is provided, defaults to the last 90 days. Date range is capped at 90 days max.
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 500, default: 50 } }
        - { name: source, in: query, schema: { type: string, enum: [zernio, all], default: zernio }, description: "zernio = Zernio-created only, all = include external ads" }
        - { name: status, in: query, schema: { type: string, enum: [active, paused, pending_review, rejected, completed, cancelled, error] } }
        - { name: platform, in: query, schema: { type: string, enum: [facebook, instagram, tiktok, linkedin, pinterest, google, twitter] } }
        - { name: accountId, in: query, schema: { type: string }, description: Social account ID }
        - { name: profileId, in: query, schema: { type: string }, description: Profile ID }
        - { name: campaignId, in: query, schema: { type: string }, description: Platform campaign ID (filter ads within a campaign) }
        - { name: fromDate, in: query, schema: { type: string, format: date }, description: "Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago." }
        - { name: toDate, in: query, schema: { type: string, format: date }, description: "End of metrics date range (YYYY-MM-DD). Defaults to today. Max 90-day range." }
      responses:
        '200':
          description: Paginated ads
          content:
            application/json:
              schema:
                type: object
                properties:
                  ads:
                    type: array
                    items: { $ref: '#/components/schemas/Ad' }
                  pagination: { $ref: '#/components/schemas/Pagination' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Ads add-on required

  /v1/ads/campaigns:
    get:
      operationId: listAdCampaigns
      tags: [Ad Campaigns]
      summary: List campaigns with aggregate metrics
      description: |
        Returns campaigns as virtual aggregations over ad documents grouped by platform campaign ID.
        Metrics (spend, impressions, clicks, etc.) are summed across all ads in each campaign.
        Campaign status is derived from child ad statuses (active > pending_review > paused > error > completed > cancelled > rejected).
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } }
        - { name: source, in: query, schema: { type: string, enum: [zernio, all], default: zernio } }
        - { name: platform, in: query, schema: { type: string, enum: [facebook, instagram, tiktok, linkedin, pinterest, google, twitter] } }
        - { name: status, in: query, schema: { type: string, enum: [active, paused, pending_review, rejected, completed, cancelled, error] }, description: Filter by derived campaign status (post-aggregation) }
        - { name: adAccountId, in: query, schema: { type: string }, description: Platform ad account ID (e.g. act_123 for Meta) }
        - { name: accountId, in: query, schema: { type: string }, description: Social account ID }
        - { name: profileId, in: query, schema: { type: string }, description: Profile ID }
      responses:
        '200':
          description: Paginated campaigns
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaigns:
                    type: array
                    items: { $ref: '#/components/schemas/AdCampaign' }
                  pagination: { $ref: '#/components/schemas/Pagination' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Ads add-on required

  /v1/ads/campaigns/{campaignId}/status:
    put:
      operationId: updateAdCampaignStatus
      tags: [Ad Campaigns]
      summary: Pause or resume a campaign
      description: |
        Updates the status of all ads in a campaign. Makes one platform API call (not per-ad) since status cascades through the campaign hierarchy.
        Ads in terminal statuses (rejected, completed, cancelled) are automatically skipped.
      security:
        - bearerAuth: []
      parameters:
        - { name: campaignId, in: path, required: true, schema: { type: string }, description: Platform campaign ID }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status, platform]
              properties:
                status: { type: string, enum: [active, paused] }
                platform: { type: string, enum: [facebook, instagram, tiktok, linkedin, pinterest, google, twitter] }
      responses:
        '200':
          description: Campaign status updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  updated: { type: integer, description: Number of ads updated }
                  skipped: { type: integer, description: Number of ads skipped }
                  skippedReasons: { type: array, items: { type: string } }
                  message: { type: string, description: Human-readable summary (present when no ads were actionable) }
        '400':
          description: Invalid input or campaign spans multiple social accounts
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404':
          description: No ads found for this campaign

  /v1/ads/tree:
    get:
      operationId: getAdTree
      tags: [Ad Campaigns]
      summary: Get nested campaign/ad-set/ad tree
      description: |
        Returns a nested Campaign > Ad Set > Ad hierarchy with rolled-up metrics at each level.
        Uses a two-stage aggregation: ads are grouped into ad sets, then ad sets into campaigns.
        Metrics are computed over an optional date range, then rolled up from ad level to ad set
        and campaign levels. Pagination is at the campaign level. Ads without a campaign or ad set
        ID are grouped into synthetic "Ungrouped" buckets.
        If no date range is provided, defaults to the last 90 days. Date range is capped at 90 days max.
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 }, description: Campaigns per page }
        - { name: source, in: query, schema: { type: string, enum: [zernio, all], default: zernio } }
        - { name: platform, in: query, schema: { type: string, enum: [facebook, instagram, tiktok, linkedin, pinterest, google, twitter] } }
        - { name: status, in: query, schema: { type: string, enum: [active, paused, pending_review, rejected, completed, cancelled, error] }, description: Filter by derived campaign status (post-aggregation) }
        - { name: adAccountId, in: query, schema: { type: string }, description: Platform ad account ID }
        - { name: accountId, in: query, schema: { type: string }, description: Social account ID }
        - { name: profileId, in: query, schema: { type: string }, description: Profile ID }
        - { name: fromDate, in: query, schema: { type: string, format: date }, description: "Start of metrics date range (YYYY-MM-DD). Defaults to 90 days ago." }
        - { name: toDate, in: query, schema: { type: string, format: date }, description: "End of metrics date range (YYYY-MM-DD). Defaults to today. Max 90-day range." }
      responses:
        '200':
          description: Nested campaign tree with pagination
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaigns:
                    type: array
                    items: { $ref: '#/components/schemas/AdTreeCampaign' }
                  pagination: { $ref: '#/components/schemas/Pagination' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Ads add-on required

  /v1/ads/{adId}:
    get:
      operationId: getAd
      tags: [Ads]
      summary: Get ad details
      security:
        - bearerAuth: []
      parameters:
        - { name: adId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Ad details
          content:
            application/json:
              schema:
                type: object
                properties:
                  ad: { $ref: '#/components/schemas/Ad' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    put:
      operationId: updateAd
      tags: [Ads]
      summary: Update ad (pause/resume, budget, targeting, name)
      description: Update one or more fields on an ad. Status changes and budget updates are propagated to the platform. Targeting updates are Meta-only.
      security:
        - bearerAuth: []
      parameters:
        - { name: adId, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status: { type: string, enum: [active, paused] }
                budget:
                  type: object
                  properties:
                    amount: { type: number, description: "Minimum varies by platform: TikTok=$20, Pinterest=$5, others=$1" }
                    type: { type: string, enum: [daily, lifetime] }
                targeting:
                  type: object
                  description: Meta-only. Targeting updates for other platforms are not supported after creation.
                  properties:
                    ageMin: { type: integer, minimum: 13, maximum: 65 }
                    ageMax: { type: integer, minimum: 13, maximum: 65 }
                    countries: { type: array, items: { type: string } }
                    interests: { type: array, items: { type: string } }
                name: { type: string }
      responses:
        '200':
          description: Ad updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  ad: { $ref: '#/components/schemas/Ad' }
                  message: { type: string }
        '400':
          description: Invalid status transition or budget below minimum
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: deleteAd
      tags: [Ads]
      summary: Cancel an ad
      description: Cancels the ad on the platform and marks it as cancelled in the database. The ad is preserved for history.
      security:
        - bearerAuth: []
      parameters:
        - { name: adId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Ad cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/ads/{adId}/analytics:
    get:
      operationId: getAdAnalytics
      tags: [Ads]
      summary: Get ad analytics with daily breakdown
      description: |
        Returns detailed performance analytics for an ad. Includes summary metrics, a daily timeline
        over the requested date range, and optional demographic breakdowns (Meta and TikTok only).
        If no date range is provided, defaults to the last 90 days. Date range is capped at 90 days max.
      security:
        - bearerAuth: []
      parameters:
        - { name: adId, in: path, required: true, schema: { type: string } }
        - { name: fromDate, in: query, schema: { type: string, format: date }, description: "Start of date range (YYYY-MM-DD). Defaults to 90 days ago." }
        - { name: toDate, in: query, schema: { type: string, format: date }, description: "End of date range (YYYY-MM-DD). Defaults to today. Max 90-day range." }
        - name: breakdowns
          in: query
          schema: { type: string }
          description: "Comma-separated breakdown dimensions. Meta: age, gender, country, publisher_platform, device_platform, region. TikTok: gender, age, country_code, platform, ac, language."
      responses:
        '200':
          description: Ad analytics
          content:
            application/json:
              schema:
                type: object
                properties:
                  ad:
                    type: object
                    properties:
                      id: { type: string }
                      name: { type: string }
                      platform: { type: string }
                      status: { type: string }
                  analytics:
                    type: object
                    properties:
                      summary: { $ref: '#/components/schemas/AdMetrics' }
                      daily:
                        type: array
                        items:
                          allOf:
                            - { $ref: '#/components/schemas/AdMetrics' }
                            - type: object
                              properties:
                                date: { type: string, format: date }
                      breakdowns:
                        type: object
                        additionalProperties:
                          type: array
                          items: { type: object }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Ads add-on required
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/ads/accounts:
    get:
      operationId: listAdAccounts
      tags: [Ads]
      summary: List ad accounts for a social account
      description: Returns the platform ad accounts available for the given social account (e.g. Meta ad accounts, TikTok advertiser IDs, Google Ads customer IDs).
      security:
        - bearerAuth: []
      parameters:
        - { name: accountId, in: query, required: true, schema: { type: string }, description: Social account ID }
      responses:
        '200':
          description: Ad accounts
          content:
            application/json:
              schema:
                type: object
                properties:
                  accounts:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, description: "Platform ad account ID (e.g. act_123)" }
                        name: { type: string }
                        currency: { type: string }
                        status: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '422':
          description: Platform ads connection required (TikTok Ads, X Ads) or Instagram missing linked Facebook account

  /v1/ads/boost:
    post:
      operationId: boostPost
      tags: [Ads]
      summary: Boost an existing post as a paid ad
      description: Creates a paid ad campaign from an existing published post. Creates the full platform campaign hierarchy (campaign, ad set, ad).
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId, adAccountId, name, goal, budget]
              properties:
                postId: { type: string, description: Zernio post ID (provide this or platformPostId) }
                platformPostId: { type: string, description: Platform post ID (alternative to postId) }
                accountId: { type: string, description: Social account ID }
                adAccountId: { type: string, description: Platform ad account ID }
                name: { type: string, maxLength: 255 }
                goal: { type: string, enum: [engagement, traffic, awareness, video_views] }
                budget:
                  type: object
                  required: [amount, type]
                  properties:
                    amount: { type: number, description: "Minimum varies: TikTok=$20, Pinterest=$5, others=$1" }
                    type: { type: string, enum: [daily, lifetime] }
                currency: { type: string, example: USD }
                schedule:
                  type: object
                  properties:
                    startDate: { type: string, format: date-time }
                    endDate: { type: string, format: date-time, description: Required for lifetime budgets }
                targeting:
                  type: object
                  properties:
                    ageMin: { type: integer, minimum: 13, maximum: 65 }
                    ageMax: { type: integer, minimum: 13, maximum: 65 }
                    countries: { type: array, items: { type: string } }
                    interests: { type: array, items: { type: string } }
                bidAmount: { type: number, description: "Max bid cap (Meta only)" }
                tracking:
                  type: object
                  description: "Meta only. Tracking specs (pixel, URL tags)."
                  properties:
                    pixelId: { type: string }
                    urlTags: { type: string }
                specialAdCategories:
                  type: array
                  description: "Meta only. Required for housing, employment, credit, or political ads."
                  items: { type: string, enum: [HOUSING, EMPLOYMENT, CREDIT, ISSUES_ELECTIONS_POLITICS] }
      responses:
        '201':
          description: Ad created
          content:
            application/json:
              schema:
                type: object
                properties:
                  ad: { $ref: '#/components/schemas/Ad' }
                  message: { type: string }
        '400':
          description: Missing required fields or invalid values
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Ads add-on required
        '422':
          description: Platform ads connection required (TikTok Ads, X Ads) or missing linked account

  /v1/ads/create:
    post:
      operationId: createStandaloneAd
      tags: [Ads]
      summary: Create a standalone ad with custom creative
      description: Creates a paid ad with custom creative (headline, body, image/video, link). Creates the full platform campaign hierarchy.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId, adAccountId, name, goal, budgetAmount, budgetType, body]
              properties:
                accountId: { type: string }
                adAccountId: { type: string }
                name: { type: string, maxLength: 255 }
                goal: { type: string, enum: [engagement, traffic, awareness, video_views] }
                budgetAmount: { type: number }
                budgetType: { type: string, enum: [daily, lifetime] }
                currency: { type: string }
                headline: { type: string, description: "Required for most platforms. Max: Meta=255, Google=30, Pinterest=100" }
                longHeadline: { type: string, maxLength: 90, description: "Google Display only" }
                body: { type: string, description: "Max: Google=90, Pinterest=500" }
                callToAction: { type: string, enum: [LEARN_MORE, SHOP_NOW, SIGN_UP, BOOK_TRAVEL, CONTACT_US, DOWNLOAD, GET_OFFER, GET_QUOTE, SUBSCRIBE, WATCH_MORE], description: Meta only }
                linkUrl: { type: string, format: uri }
                imageUrl: { type: string, format: uri, description: "Image URL (or video URL for TikTok). Not required for Google Search campaigns." }
                businessName: { type: string, maxLength: 25, description: "Google Display only" }
                boardId: { type: string, description: "Pinterest only. Board ID (auto-creates if not provided)." }
                countries: { type: array, items: { type: string } }
                ageMin: { type: integer, minimum: 13, maximum: 65 }
                ageMax: { type: integer, minimum: 13, maximum: 65 }
                interests: { type: array, items: { type: string } }
                endDate: { type: string, format: date-time, description: Required for lifetime budgets }
                audienceId: { type: string, description: Custom audience ID for targeting }
                campaignType: { type: string, enum: [display, search], default: display, description: Google only }
                keywords: { type: array, items: { type: string }, description: Google Search only }
                additionalHeadlines: { type: array, items: { type: string }, description: "Google Search RSA only. Extra headlines." }
                additionalDescriptions: { type: array, items: { type: string }, description: "Google Search RSA only. Extra descriptions." }
      responses:
        '201':
          description: Ad created
          content:
            application/json:
              schema:
                type: object
                properties:
                  ad: { $ref: '#/components/schemas/Ad' }
                  message: { type: string }
        '400':
          description: Missing required fields or invalid values
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Ads add-on required
        '422':
          description: Platform ads connection required (TikTok Ads, X Ads) or missing linked account

  /v1/ads/interests:
    get:
      operationId: searchAdInterests
      tags: [Ads]
      summary: Search targeting interests
      description: Search for interest-based targeting options available on the platform.
      security:
        - bearerAuth: []
      parameters:
        - { name: q, in: query, required: true, schema: { type: string }, description: Search query }
        - { name: accountId, in: query, required: true, schema: { type: string }, description: Social account ID }
      responses:
        '200':
          description: Matching interests
          content:
            application/json:
              schema:
                type: object
                properties:
                  interests:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        name: { type: string }
                        category: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Ads add-on required

  /v1/ads/audiences:
    get:
      operationId: listAdAudiences
      tags: [Ad Audiences]
      summary: List custom audiences
      description: Returns custom audiences for the given ad account. Supports Meta, Google, TikTok, and Pinterest.
      security:
        - bearerAuth: []
      parameters:
        - { name: accountId, in: query, required: true, schema: { type: string }, description: Social account ID }
        - { name: adAccountId, in: query, required: true, schema: { type: string }, description: Platform ad account ID }
        - { name: platform, in: query, schema: { type: string, enum: [facebook, instagram, googleads, tiktok, pinterest] } }
      responses:
        '200':
          description: Audiences
          content:
            application/json:
              schema:
                type: object
                properties:
                  audiences:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string, nullable: true }
                        platformAudienceId: { type: string }
                        name: { type: string }
                        description: { type: string }
                        type: { type: string, enum: [customer_list, website, lookalike] }
                        platform: { type: string }
                        size: { type: integer }
                        status: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Ads add-on required
    post:
      operationId: createAdAudience
      tags: [Ad Audiences]
      summary: Create a custom audience (Meta only)
      description: Create a customer list, website retargeting, or lookalike audience on Meta (Facebook/Instagram).
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [accountId, adAccountId, name, type]
              properties:
                accountId: { type: string }
                adAccountId: { type: string, description: "Must start with act_" }
                name: { type: string, maxLength: 255 }
                description: { type: string }
                type: { type: string, enum: [customer_list, website, lookalike] }
                pixelId: { type: string, description: Required for website audiences }
                retentionDays: { type: integer, minimum: 1, maximum: 180, description: Required for website audiences }
                sourceAudienceId: { type: string, description: Required for lookalike audiences }
                country: { type: string, description: "2-letter code, required for lookalike audiences" }
                ratio: { type: number, minimum: 0.01, maximum: 0.20, description: Required for lookalike audiences }
                rule: { type: object, description: "Pixel event rule for website audiences (optional)" }
                customerFileSource: { type: string, description: "Data source declaration for GDPR compliance (customer_list only)" }
      responses:
        '201':
          description: Audience created
          content:
            application/json:
              schema:
                type: object
                properties:
                  audience: { type: object }
                  message: { type: string }
        '400':
          description: Missing required fields
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Ads add-on required

  /v1/ads/audiences/{audienceId}:
    get:
      operationId: getAdAudience
      tags: [Ad Audiences]
      summary: Get audience details
      description: Returns the local audience record and fresh data from Meta (if available).
      security:
        - bearerAuth: []
      parameters:
        - { name: audienceId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Audience details
          content:
            application/json:
              schema:
                type: object
                properties:
                  audience: { type: object }
                  metaData: { type: object, nullable: true, description: Fresh data from Meta API }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Ads add-on required
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      operationId: deleteAdAudience
      tags: [Ad Audiences]
      summary: Delete a custom audience
      description: Deletes the audience from both Meta and the local database.
      security:
        - bearerAuth: []
      parameters:
        - { name: audienceId, in: path, required: true, schema: { type: string } }
      responses:
        '200':
          description: Audience deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Ads add-on required
        '404': { $ref: '#/components/responses/NotFound' }

  /v1/ads/audiences/{audienceId}/users:
    post:
      operationId: addUsersToAdAudience
      tags: [Ad Audiences]
      summary: Add users to a customer list audience
      description: Upload user data (emails and/or phone numbers) to a customer_list audience. Data is SHA256-hashed server-side before sending to Meta. Max 10,000 users per request.
      security:
        - bearerAuth: []
      parameters:
        - { name: audienceId, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [users]
              properties:
                users:
                  type: array
                  maxItems: 10000
                  items:
                    type: object
                    properties:
                      email: { type: string, format: email }
                      phone: { type: string }
                    description: Each user must have at least email or phone
      responses:
        '200':
          description: Users added
          content:
            application/json:
              schema:
                type: object
                properties:
                  message: { type: string }
                  numReceived: { type: integer }
                  numInvalid: { type: integer }
        '400':
          description: Invalid input (empty users array, missing email/phone)
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403':
          description: Ads add-on required
        '404': { $ref: '#/components/responses/NotFound' }
        '422':
          description: Audience is not a customer_list type or has no platform ID yet