openapi: 3.2.0
info:
  title: GPT Backend External Platform API
  version: 0.1.0
servers:
- url: https://api.usepomo.ai
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: external-platform
paths:
  /api/external-platform/instagram/auth:
    get:
      tags:
      - external-platform
      summary: Instagram Auth
      description: "Generate an OAuth URL for user authentication.\n\nArgs:\n    login_type: The type of login flow to use. Defaults to \"instagram\".\n               Set to \"facebook\" to use Facebook login instead.\n    db: Database session\n    company_profile: Current company profile (injected via dependency)\n\nReturns:\n    InstagramAuthResponseModel: Response with authentication URL"
      operationId: instagram_auth_api_external_platform_instagram_auth_get
      security:
      - HTTPBearer: []
      parameters:
      - name: login_type
        in: query
        required: false
        schema:
          type: string
          default: instagram
          title: Login Type
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstagramAuthResponseModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/instagram/callback:
    get:
      tags:
      - external-platform
      summary: Instagram Callback
      description: "Handle Instagram OAuth callback.\n\nArgs:\n    code: Authorization code from OAuth provider\n    state: State parameter containing user ID and login type\n    error: Error code if authorization failed\n    error_reason: Reason for error if authorization failed\n    error_description: Detailed error description if authorization failed\n    db: Database session\n    \nReturns:\n    RedirectResponse: Redirect to frontend with success or error"
      operationId: instagram_callback_api_external_platform_instagram_callback_get
      parameters:
      - name: code
        in: query
        required: false
        schema:
          type: string
          title: Code
      - name: state
        in: query
        required: false
        schema:
          type: string
          title: State
      - name: error
        in: query
        required: false
        schema:
          type: string
          title: Error
      - name: error_reason
        in: query
        required: false
        schema:
          type: string
          title: Error Reason
      - name: error_description
        in: query
        required: false
        schema:
          type: string
          title: Error Description
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/instagram/disconnect:
    post:
      tags:
      - external-platform
      summary: Disconnect Instagram
      operationId: disconnect_instagram_api_external_platform_instagram_disconnect_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/instagram/create-post:
    post:
      tags:
      - external-platform
      summary: Create Instagram Post
      description: "Create an Instagram post with an image.\n\nThis endpoint creates a standalone Instagram post not associated with a campaign.\nIt handles authentication, validates the token, and posts content to Instagram.\n\nArgs:\n    post_data: Post content and account details\n    db: Database session\n    company_profile: Current company profile (injected via dependency)\n\nReturns:\n    PostResponseModel: Response with post ID"
      operationId: create_instagram_post_api_external_platform_instagram_create_post_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePostRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostResponseModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/instagram/delete-post:
    post:
      tags:
      - external-platform
      summary: Delete Instagram Post
      description: "Delete an Instagram post by ID.\n\nThis endpoint deletes a post from Instagram and updates the corresponding\ndatabase records in the SocialPostCampaign table.\n\nArgs:\n    delete_data: Post ID to delete\n    db: Database session\n    company_profile: Current company profile (injected via dependency)\n\nReturns:\n    DeletePostResponseModel: Response with success status"
      operationId: delete_instagram_post_api_external_platform_instagram_delete_post_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeletePostRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletePostResponseModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/instagram/posts:
    get:
      tags:
      - external-platform
      summary: Get Instagram Posts
      description: "Get recent Instagram posts for a specific account.\n\nArgs:\n    instagram_account_id: Instagram business account ID\n    limit: Maximum number of posts to return\n    db: Database session\n    company_profile: Current company profile (injected via dependency)\n\nReturns:\n    dict: Response with list of posts"
      operationId: get_instagram_posts_api_external_platform_instagram_posts_get
      security:
      - HTTPBearer: []
      parameters:
      - name: instagram_account_id
        in: query
        required: true
        schema:
          type: string
          title: Instagram Account Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 25
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/instagram/post-metrics:
    post:
      tags:
      - external-platform
      summary: Get Post Metrics
      description: "Get metrics for a specific Instagram post.\n\nArgs:\n    metrics_data: Post ID and metrics to retrieve\n    db: Database session\n    company_profile: Current company profile (injected via dependency)\n\nReturns:\n    dict: Response with metrics data"
      operationId: get_post_metrics_api_external_platform_instagram_post_metrics_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostMetricsRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/instagram/batch-post-metrics:
    post:
      tags:
      - external-platform
      summary: Get Batch Post Metrics
      description: "Get metrics for multiple Instagram posts in a single request.\n\nArgs:\n    batch_data: Instagram account ID and list of post IDs\n    db: Database session\n    company_profile: Current company profile (injected via dependency)\n\nReturns:\n    dict: Response with metrics for all posts"
      operationId: get_batch_post_metrics_api_external_platform_instagram_batch_post_metrics_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchPostMetricsRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/instagram/accounts:
    get:
      tags:
      - external-platform
      summary: Get Instagram Accounts
      description: "Get a list of Instagram business accounts that the user has access to.\nThis endpoint handles both Instagram direct authentication and Facebook authentication.\n\nArgs:\n    db: Database session\n    company_profile: Current company profile (injected via dependency)\n\nReturns:\n    dict: Response with list of Instagram accounts and authentication method"
      operationId: get_instagram_accounts_api_external_platform_instagram_accounts_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/instagram/activation:
    get:
      tags:
      - external-platform
      summary: Get Instagram Activation
      operationId: get_instagram_activation_api_external_platform_instagram_activation_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/instagram/activate:
    post:
      tags:
      - external-platform
      summary: Activate Instagram Identity
      operationId: activate_instagram_identity_api_external_platform_instagram_activate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstagramActivateIdentityRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/instagram/post-campaign:
    post:
      tags:
      - external-platform
      summary: Post Campaign To Instagram
      description: "Post a campaign's content to Instagram.\n\nThis endpoint creates a post on Instagram using content from a SocialPostCampaign.\nIt supports both single image posts and carousel posts (multiple images).\n\nArgs:\n    post_data: Campaign and Instagram account info\n    db: Database session\n    company_profile: Current company profile (injected via dependency)\n\nReturns:\n    PostResponseModel: Response with post ID and status\n\nNotes:\n    - For carousel posts, multiple images must be provided in the campaign\n    - If posting a carousel, all images should have the same aspect ratio\n    - Carousel posts are limited to 10 images"
      operationId: post_campaign_to_instagram_api_external_platform_instagram_post_campaign_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InstagramPostCampaignRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostResponseModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/meta/campaign/{campaign_id}/status:
    get:
      tags:
      - external-platform
      summary: Get Meta Campaign Status
      description: Fetch real-time Meta campaign status (with optional adset/ad) and map to canonical states.
      operationId: get_meta_campaign_status_api_external_platform_meta_campaign__campaign_id__status_get
      security:
      - HTTPBearer: []
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          title: Campaign Id
      - name: adset_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Adset Id
      - name: ad_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Ad Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/meta/auth:
    get:
      tags:
      - external-platform
      summary: Meta Auth
      description: 'Get OAuth authorization URL.


        - auth_type = ''facebook'' returns Meta (Facebook) Ads auth URL and redirects to /meta/callback

        - auth_type = ''instagram'' returns Instagram auth URL and redirects to /instagram/callback (for social posting)'
      operationId: meta_auth_api_external_platform_meta_auth_get
      security:
      - HTTPBearer: []
      parameters:
      - name: auth_type
        in: query
        required: false
        schema:
          type: string
          description: '''facebook'' for Meta Ads; ''instagram'' for Instagram social'
          default: facebook
          title: Auth Type
        description: '''facebook'' for Meta Ads; ''instagram'' for Instagram social'
      - name: capability
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional incremental capability upgrade on the same Meta connection.
          title: Capability
        description: Optional incremental capability upgrade on the same Meta connection.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaAuthResponseModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/meta/callback:
    get:
      tags:
      - external-platform
      summary: Meta Callback
      description: 'Handle Meta (Facebook) OAuth callback for Ads connection and store tokens.


        Redirects to the frontend PlatformConnectSuccessPage with platform=meta.'
      operationId: meta_callback_api_external_platform_meta_callback_get
      parameters:
      - name: code
        in: query
        required: false
        schema:
          type: string
          title: Code
      - name: state
        in: query
        required: false
        schema:
          type: string
          title: State
      - name: error
        in: query
        required: false
        schema:
          type: string
          title: Error
      - name: error_description
        in: query
        required: false
        schema:
          type: string
          title: Error Description
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/meta/accounts:
    get:
      tags:
      - external-platform
      summary: Get Meta Accounts
      description: Get Meta Ad accounts and Facebook Pages for the authenticated user.
      operationId: get_meta_accounts_api_external_platform_meta_accounts_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetaAccountsResponseModel'
      security:
      - HTTPBearer: []
  /api/external-platform/meta/activation:
    get:
      tags:
      - external-platform
      summary: Get Meta Activation
      operationId: get_meta_activation_api_external_platform_meta_activation_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/meta/disconnect:
    post:
      tags:
      - external-platform
      summary: Disconnect Meta Ads
      operationId: disconnect_meta_ads_api_external_platform_meta_disconnect_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/meta/accounts/select:
    post:
      tags:
      - external-platform
      summary: Select Meta Ad Account
      description: Activate one Meta ad account for future launches.
      operationId: select_meta_ad_account_api_external_platform_meta_accounts_select_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetaSelectAdAccountRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/meta/activate:
    post:
      tags:
      - external-platform
      summary: Activate Meta Ad Account
      operationId: activate_meta_ad_account_api_external_platform_meta_activate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetaSelectAdAccountRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/meta/launch-ad-campaign:
    post:
      tags:
      - external-platform
      summary: Launch Meta Ad Campaign
      description: Queue a Meta ad campaign launch and return a job id for status polling.
      operationId: launch_meta_ad_campaign_api_external_platform_meta_launch_ad_campaign_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetaLaunchAdCampaignRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/meta/sync-ad-campaign/preview:
    post:
      tags:
      - external-platform
      summary: Preview Meta Sync
      description: Preview sync changes and billing impact for a Meta ad campaign.
      operationId: preview_meta_sync_api_external_platform_meta_sync_ad_campaign_preview_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetaSyncPreviewRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/meta/sync-ad-campaign:
    post:
      tags:
      - external-platform
      summary: Sync Meta Ad Campaign
      description: Queue a Meta ad sync and return a job id for status polling.
      operationId: sync_meta_ad_campaign_api_external_platform_meta_sync_ad_campaign_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetaSyncAdCampaignRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/meta/sync-job/{job_id}:
    get:
      tags:
      - external-platform
      summary: Get Sync Job Status
      operationId: get_sync_job_status_api_external_platform_meta_sync_job__job_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/meta/launch-job/{job_id}:
    get:
      tags:
      - external-platform
      summary: Get Launch Job Status
      operationId: get_launch_job_status_api_external_platform_meta_launch_job__job_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/meta/campaigns/{campaign_id}/activate:
    post:
      tags:
      - external-platform
      summary: Activate Meta Campaign
      description: Activate a paused Meta campaign
      operationId: activate_meta_campaign_api_external_platform_meta_campaigns__campaign_id__activate_post
      security:
      - HTTPBearer: []
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          title: Campaign Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/meta/adsets/{adset_id}/activate:
    post:
      tags:
      - external-platform
      summary: Activate Meta Adset
      description: Activate a paused Meta ad set
      operationId: activate_meta_adset_api_external_platform_meta_adsets__adset_id__activate_post
      security:
      - HTTPBearer: []
      parameters:
      - name: adset_id
        in: path
        required: true
        schema:
          type: string
          title: Adset Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/meta/ads/{ad_id}/activate:
    post:
      tags:
      - external-platform
      summary: Activate Meta Ad
      description: Activate a paused Meta ad
      operationId: activate_meta_ad_api_external_platform_meta_ads__ad_id__activate_post
      security:
      - HTTPBearer: []
      parameters:
      - name: ad_id
        in: path
        required: true
        schema:
          type: string
          title: Ad Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/meta/adsets/{adset_id}/pause:
    post:
      tags:
      - external-platform
      summary: Pause Meta Adset
      description: Pause an active Meta ad set
      operationId: pause_meta_adset_api_external_platform_meta_adsets__adset_id__pause_post
      security:
      - HTTPBearer: []
      parameters:
      - name: adset_id
        in: path
        required: true
        schema:
          type: string
          title: Adset Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/meta/ads/{ad_id}/pause:
    post:
      tags:
      - external-platform
      summary: Pause Meta Ad
      description: Pause an active Meta ad
      operationId: pause_meta_ad_api_external_platform_meta_ads__ad_id__pause_post
      security:
      - HTTPBearer: []
      parameters:
      - name: ad_id
        in: path
        required: true
        schema:
          type: string
          title: Ad Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/meta/campaigns/{campaign_id}/pause:
    post:
      tags:
      - external-platform
      summary: Pause Meta Campaign
      description: Pause an active Meta campaign
      operationId: pause_meta_campaign_api_external_platform_meta_campaigns__campaign_id__pause_post
      security:
      - HTTPBearer: []
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          title: Campaign Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/meta/campaigns/{campaign_id}/insights:
    get:
      tags:
      - external-platform
      summary: Get Meta Campaign Insights
      description: Get performance insights for a Meta campaign
      operationId: get_meta_campaign_insights_api_external_platform_meta_campaigns__campaign_id__insights_get
      security:
      - HTTPBearer: []
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          title: Campaign Id
      - name: date_preset
        in: query
        required: false
        schema:
          type: string
          default: last_7d
          title: Date Preset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/meta/campaign/action:
    post:
      tags:
      - external-platform
      summary: Meta Campaign Action
      operationId: meta_campaign_action_api_external_platform_meta_campaign_action_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetaCampaignActionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/meta/campaign/resume:
    post:
      tags:
      - external-platform
      summary: Meta Campaign Resume
      operationId: meta_campaign_resume_api_external_platform_meta_campaign_resume_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetaCampaignResumeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/google/auth:
    get:
      tags:
      - external-platform
      summary: Google Auth
      description: Get Google OAuth authorization URL for the current company profile.
      operationId: google_auth_api_external_platform_google_auth_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAuthResponseModel'
      security:
      - HTTPBearer: []
  /api/external-platform/google/callback:
    get:
      tags:
      - external-platform
      summary: Google Callback
      description: 'Handle Google OAuth callback and store tokens.

        Then redirect to the frontend application.'
      operationId: google_callback_api_external_platform_google_callback_get
      parameters:
      - name: code
        in: query
        required: true
        schema:
          type: string
          title: Code
      - name: state
        in: query
        required: true
        schema:
          type: string
          title: State
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/google/accounts:
    get:
      tags:
      - external-platform
      summary: Get Google Accounts
      description: Get Google Ads accounts for the authenticated user.
      operationId: get_google_accounts_api_external_platform_google_accounts_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAccountsResponseModel'
      security:
      - HTTPBearer: []
  /api/external-platform/google/activation:
    get:
      tags:
      - external-platform
      summary: Get Google Activation
      operationId: get_google_activation_api_external_platform_google_activation_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/google/activate:
    post:
      tags:
      - external-platform
      summary: Activate Google Ads Account
      operationId: activate_google_ads_account_api_external_platform_google_activate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleActivateAccountRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/google/disconnect:
    post:
      tags:
      - external-platform
      summary: Disconnect Google Ads
      operationId: disconnect_google_ads_api_external_platform_google_disconnect_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/google/campaigns:
    post:
      tags:
      - external-platform
      summary: Create Google Ad Campaign
      description: Create a new Google Ads campaign.
      operationId: create_google_ad_campaign_api_external_platform_google_campaigns_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleAdCampaignRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/google/ad-groups:
    post:
      tags:
      - external-platform
      summary: Create Google Ad Group
      description: Create a new Google Ads ad group.
      operationId: create_google_ad_group_api_external_platform_google_ad_groups_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleAdGroupRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/google/display-ads:
    post:
      tags:
      - external-platform
      summary: Create Google Display Ad
      description: Create a new Google Ads display ad.
      operationId: create_google_display_ad_api_external_platform_google_display_ads_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/routes__external_platform__google_action__GoogleDisplayAdRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/google/create-ad:
    post:
      tags:
      - external-platform
      summary: Create Ad From Campaign
      description: Reject the legacy social-post-to-paid-ad mutation path.
      operationId: create_ad_from_campaign_api_external_platform_google_create_ad_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleCreateAdFromCampaignRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/google/sync-ad-campaign/preview:
    post:
      tags:
      - external-platform
      summary: Preview Google Sync
      description: Preview sync changes and billing impact for a Google ad campaign.
      operationId: preview_google_sync_api_external_platform_google_sync_ad_campaign_preview_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleSyncPreviewRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/google/sync-ad-campaign:
    post:
      tags:
      - external-platform
      summary: Sync Ad Campaign
      description: Sync an online ad campaign to Google Ads asynchronously via the agent job system.
      operationId: sync_ad_campaign_api_external_platform_google_sync_ad_campaign_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleSyncAdCampaignRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/google/launch-ad-campaign:
    post:
      tags:
      - external-platform
      summary: Launch Ad Campaign
      description: Launch an online ad campaign to Google Ads asynchronously via the agent job system.
      operationId: launch_ad_campaign_api_external_platform_google_launch_ad_campaign_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleLaunchAdCampaignRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/google/campaign/action:
    post:
      tags:
      - external-platform
      summary: Google Campaign Action
      operationId: google_campaign_action_api_external_platform_google_campaign_action_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleCampaignActionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/google/campaign/resume:
    post:
      tags:
      - external-platform
      summary: Google Campaign Resume
      operationId: google_campaign_resume_api_external_platform_google_campaign_resume_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleCampaignActionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/google/campaign/{campaign_id}/status:
    get:
      tags:
      - external-platform
      summary: Get Google Campaign Status
      description: "Fetch real-time campaign status from Google Ads API\n\nArgs:\n    campaign_id: Google campaign ID\n    google_account_id: Google Ads account ID\n\nReturns:\n    Campaign status information"
      operationId: get_google_campaign_status_api_external_platform_google_campaign__campaign_id__status_get
      security:
      - HTTPBearer: []
      parameters:
      - name: campaign_id
        in: path
        required: true
        schema:
          type: string
          title: Campaign Id
      - name: google_account_id
        in: query
        required: true
        schema:
          type: string
          title: Google Account Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/amazon/auth:
    get:
      tags:
      - external-platform
      summary: Amazon Auth
      description: Get Amazon OAuth authorization URL for the current user.
      operationId: amazon_auth_api_external_platform_amazon_auth_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmazonAuthResponseModel'
      security:
      - HTTPBearer: []
  /api/external-platform/amazon/callback:
    get:
      tags:
      - external-platform
      summary: Amazon Callback
      description: Handle Amazon OAuth callback and store tokens.
      operationId: amazon_callback_api_external_platform_amazon_callback_get
      parameters:
      - name: code
        in: query
        required: true
        schema:
          type: string
          title: Code
      - name: state
        in: query
        required: true
        schema:
          type: string
          title: State
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/amazon/accounts:
    get:
      tags:
      - external-platform
      summary: Get Amazon Accounts
      description: 'Get available Amazon advertising accounts (profiles) for the current user.

        Returns empty list if user hasn''t connected their Amazon account yet.'
      operationId: get_amazon_accounts_api_external_platform_amazon_accounts_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AmazonAccountsResponseModel'
      security:
      - HTTPBearer: []
  /api/external-platform/amazon/campaigns:
    post:
      tags:
      - external-platform
      summary: Create Amazon Campaign
      description: Create a new Amazon advertising campaign.
      operationId: create_amazon_campaign_api_external_platform_amazon_campaigns_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AmazonCampaignRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/amazon/ad-groups:
    post:
      tags:
      - external-platform
      summary: Create Amazon Ad Group
      description: Create a new Amazon ad group.
      operationId: create_amazon_ad_group_api_external_platform_amazon_ad_groups_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AmazonAdGroupRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/amazon/product-ads:
    post:
      tags:
      - external-platform
      summary: Create Amazon Product Ad
      description: Create a new Amazon product ad.
      operationId: create_amazon_product_ad_api_external_platform_amazon_product_ads_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AmazonProductAdRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/amazon/keywords:
    post:
      tags:
      - external-platform
      summary: Add Amazon Keywords
      description: Add keywords to an Amazon ad group.
      operationId: add_amazon_keywords_api_external_platform_amazon_keywords_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AmazonKeywordsRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/amazon/campaigns/{profile_id}:
    get:
      tags:
      - external-platform
      summary: Get Amazon Campaigns
      description: Get Amazon campaigns for a specific profile.
      operationId: get_amazon_campaigns_api_external_platform_amazon_campaigns__profile_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: profile_id
        in: path
        required: true
        schema:
          type: string
          title: Profile Id
      - name: state_filter
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: State Filter
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/amazon/metrics:
    post:
      tags:
      - external-platform
      summary: Get Amazon Campaign Metrics
      description: Get performance metrics for Amazon campaigns.
      operationId: get_amazon_campaign_metrics_api_external_platform_amazon_metrics_post
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: true
              type: object
              title: Metrics Request
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/amazon/campaign/action:
    post:
      tags:
      - external-platform
      summary: Amazon Campaign Action
      description: 'Pause or delete an Amazon ad campaign.


        Actions:

        - pause: Pauses the campaign (can be resumed later)

        - delete: Archives the campaign (can be relaunched)'
      operationId: amazon_campaign_action_api_external_platform_amazon_campaign_action_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AmazonCampaignActionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/amazon/campaign/resume:
    post:
      tags:
      - external-platform
      summary: Amazon Campaign Resume
      description: Resume a paused Amazon ad campaign.
      operationId: amazon_campaign_resume_api_external_platform_amazon_campaign_resume_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AmazonCampaignActionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/tiktok/auth:
    get:
      tags:
      - external-platform
      summary: Tiktok Auth
      description: Get TikTok OAuth authorization URL for the current company profile.
      operationId: tiktok_auth_api_external_platform_tiktok_auth_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TikTokAuthResponseModel'
      security:
      - HTTPBearer: []
  /api/external-platform/tiktok/callback:
    get:
      tags:
      - external-platform
      summary: Tiktok Callback
      description: 'Handle TikTok OAuth callback and store tokens.

        Then redirect to the frontend application.'
      operationId: tiktok_callback_api_external_platform_tiktok_callback_get
      parameters:
      - name: code
        in: query
        required: true
        schema:
          type: string
          title: Code
      - name: state
        in: query
        required: true
        schema:
          type: string
          title: State
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/tiktok/accounts:
    get:
      tags:
      - external-platform
      summary: Get Tiktok Accounts
      description: Get TikTok advertiser accounts for the authenticated company profile.
      operationId: get_tiktok_accounts_api_external_platform_tiktok_accounts_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TikTokAccountsResponseModel'
      security:
      - HTTPBearer: []
  /api/external-platform/tiktok/activation:
    get:
      tags:
      - external-platform
      summary: Get Tiktok Activation
      operationId: get_tiktok_activation_api_external_platform_tiktok_activation_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/tiktok/activate:
    post:
      tags:
      - external-platform
      summary: Activate Tiktok Ads Account
      operationId: activate_tiktok_ads_account_api_external_platform_tiktok_activate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TikTokActivateAccountRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/tiktok/disconnect:
    post:
      tags:
      - external-platform
      summary: Disconnect Tiktok Ads
      operationId: disconnect_tiktok_ads_api_external_platform_tiktok_disconnect_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/tiktok/launch-video-ad:
    post:
      tags:
      - external-platform
      summary: Launch Tiktok Video Ad
      description: Start a TikTok launch job and return tracking info.
      operationId: launch_tiktok_video_ad_api_external_platform_tiktok_launch_video_ad_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TikTokLaunchVideoAdRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/tiktok/sync-ad-campaign/preview:
    post:
      tags:
      - external-platform
      summary: Preview Tiktok Sync
      description: Preview saved Pomo changes for a normalized TikTok video ad.
      operationId: preview_tiktok_sync_api_external_platform_tiktok_sync_ad_campaign_preview_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TikTokSyncPreviewRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/tiktok/sync-ad-campaign:
    post:
      tags:
      - external-platform
      summary: Sync Tiktok Ad Campaign
      description: Queue a normalized TikTok sync job and return tracking info.
      operationId: sync_tiktok_ad_campaign_api_external_platform_tiktok_sync_ad_campaign_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TikTokSyncAdRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/tiktok/ad/pause:
    post:
      tags:
      - external-platform
      summary: Pause Tiktok Ad
      operationId: pause_tiktok_ad_api_external_platform_tiktok_ad_pause_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TikTokAdPauseRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TikTokAdStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/tiktok/ad/resume:
    post:
      tags:
      - external-platform
      summary: Resume Tiktok Ad
      operationId: resume_tiktok_ad_api_external_platform_tiktok_ad_resume_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TikTokAdResumeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TikTokAdStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/tiktok-social/auth:
    get:
      tags:
      - external-platform
      summary: Tiktok Social Auth
      operationId: tiktok_social_auth_api_external_platform_tiktok_social_auth_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/tiktok-social/callback:
    get:
      tags:
      - external-platform
      summary: Tiktok Social Callback
      operationId: tiktok_social_callback_api_external_platform_tiktok_social_callback_get
      parameters:
      - name: code
        in: query
        required: false
        schema:
          type: string
          title: Code
      - name: state
        in: query
        required: false
        schema:
          type: string
          title: State
      - name: error
        in: query
        required: false
        schema:
          type: string
          title: Error
      - name: error_description
        in: query
        required: false
        schema:
          type: string
          title: Error Description
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/tiktok-social/status:
    get:
      tags:
      - external-platform
      summary: Tiktok Social Status
      operationId: tiktok_social_status_api_external_platform_tiktok_social_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/tiktok-social/accounts:
    get:
      tags:
      - external-platform
      summary: Tiktok Social Accounts
      operationId: tiktok_social_accounts_api_external_platform_tiktok_social_accounts_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/tiktok-social/creator-info:
    post:
      tags:
      - external-platform
      summary: Tiktok Social Creator Info
      operationId: tiktok_social_creator_info_api_external_platform_tiktok_social_creator_info_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/tiktok-social/publish-settings:
    post:
      tags:
      - external-platform
      summary: Save Tiktok Social Publish Settings
      operationId: save_tiktok_social_publish_settings_api_external_platform_tiktok_social_publish_settings_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TikTokSocialPublishSettingsRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/tiktok-social/post-campaign:
    post:
      tags:
      - external-platform
      summary: Post Campaign To Tiktok Social
      operationId: post_campaign_to_tiktok_social_api_external_platform_tiktok_social_post_campaign_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TikTokSocialPostCampaignRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/tiktok-social/publish-status/{publish_id}:
    get:
      tags:
      - external-platform
      summary: Tiktok Social Publish Status
      operationId: tiktok_social_publish_status_api_external_platform_tiktok_social_publish_status__publish_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: publish_id
        in: path
        required: true
        schema:
          type: string
          title: Publish Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/tiktok-social/disconnect:
    post:
      tags:
      - external-platform
      summary: Disconnect Tiktok Social
      operationId: disconnect_tiktok_social_api_external_platform_tiktok_social_disconnect_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/linkedin/auth:
    get:
      tags:
      - external-platform
      summary: Linkedin Auth
      operationId: linkedin_auth_api_external_platform_linkedin_auth_get
      security:
      - HTTPBearer: []
      parameters:
      - name: integration_type
        in: query
        required: false
        schema:
          type: string
          description: 'One of: ads, social'
          default: ads
          title: Integration Type
        description: 'One of: ads, social'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/linkedin/callback:
    get:
      tags:
      - external-platform
      summary: Linkedin Callback
      operationId: linkedin_callback_api_external_platform_linkedin_callback_get
      parameters:
      - name: code
        in: query
        required: false
        schema:
          type: string
          title: Code
      - name: state
        in: query
        required: false
        schema:
          type: string
          title: State
      - name: error
        in: query
        required: false
        schema:
          type: string
          title: Error
      - name: error_description
        in: query
        required: false
        schema:
          type: string
          title: Error Description
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/linkedin/accounts:
    get:
      tags:
      - external-platform
      summary: Get Linkedin Ad Accounts
      description: Get LinkedIn ad accounts for the connected Ads integration.
      operationId: get_linkedin_ad_accounts_api_external_platform_linkedin_accounts_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/linkedin/activation:
    get:
      tags:
      - external-platform
      summary: Get Linkedin Ads Activation
      description: Get LinkedIn Ads activation state and accessible ad accounts.
      operationId: get_linkedin_ads_activation_api_external_platform_linkedin_activation_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/linkedin/activate:
    post:
      tags:
      - external-platform
      summary: Activate Linkedin Ads Account
      description: Activate one LinkedIn ad account and organization for future launches.
      operationId: activate_linkedin_ads_account_api_external_platform_linkedin_activate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkedInActivateAccountRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/linkedin/campaign/action:
    post:
      tags:
      - external-platform
      summary: Linkedin Campaign Action
      operationId: linkedin_campaign_action_api_external_platform_linkedin_campaign_action_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkedInCampaignActionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/linkedin/campaign/resume:
    post:
      tags:
      - external-platform
      summary: Linkedin Campaign Resume
      operationId: linkedin_campaign_resume_api_external_platform_linkedin_campaign_resume_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkedInCampaignResumeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/linkedin/sync-ad-campaign/preview:
    post:
      tags:
      - external-platform
      summary: Preview Linkedin Sync
      operationId: preview_linkedin_sync_api_external_platform_linkedin_sync_ad_campaign_preview_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkedInSyncPreviewRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/linkedin/sync-ad-campaign:
    post:
      tags:
      - external-platform
      summary: Sync Linkedin Ad Campaign
      operationId: sync_linkedin_ad_campaign_api_external_platform_linkedin_sync_ad_campaign_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkedInSyncAdCampaignRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/linkedin/launch-image-ad:
    post:
      tags:
      - external-platform
      summary: Launch Linkedin Image Ad
      operationId: launch_linkedin_image_ad_api_external_platform_linkedin_launch_image_ad_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkedInLaunchImageAdRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/linkedin/launch-video-ad:
    post:
      tags:
      - external-platform
      summary: Launch Linkedin Video Ad
      operationId: launch_linkedin_video_ad_api_external_platform_linkedin_launch_video_ad_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkedInLaunchVideoAdRequest'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/linkedin/status:
    get:
      tags:
      - external-platform
      summary: Linkedin Ads Status
      description: 'Get LinkedIn Ads integration status.


        Note: the Integrations UI uses `/guided-workflow/check-integrations` for the

        Connected badge (same pattern as Google/Meta). This endpoint is kept for

        deeper validation and manual testing.'
      operationId: linkedin_ads_status_api_external_platform_linkedin_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/linkedin/disconnect:
    post:
      tags:
      - external-platform
      summary: Disconnect Linkedin Ads
      description: 'Disconnect LinkedIn Ads integration.


        Not currently exposed in production UI; kept for manual testing.'
      operationId: disconnect_linkedin_ads_api_external_platform_linkedin_disconnect_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/linkedin-social/auth:
    get:
      tags:
      - external-platform
      summary: Linkedin Social Auth
      description: 'Backward-compatible alias for starting LinkedIn OAuth for social posting.

        Prefer `/linkedin/auth?integration_type=social`.'
      operationId: linkedin_social_auth_api_external_platform_linkedin_social_auth_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/linkedin-social/status:
    get:
      tags:
      - external-platform
      summary: Linkedin Social Status
      description: Get LinkedIn social integration status.
      operationId: linkedin_social_status_api_external_platform_linkedin_social_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/linkedin-social/accounts:
    get:
      tags:
      - external-platform
      summary: Linkedin Social Accounts
      description: Get available LinkedIn posting identities (personal + organizations).
      operationId: linkedin_social_accounts_api_external_platform_linkedin_social_accounts_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/linkedin/post-campaign:
    post:
      tags:
      - external-platform
      summary: Post Campaign To Linkedin
      description: Publish a social post campaign to LinkedIn as a person or organization.
      operationId: post_campaign_to_linkedin_api_external_platform_linkedin_post_campaign_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkedInPostCampaignRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/linkedin/delete-campaign-post:
    post:
      tags:
      - external-platform
      summary: Delete Campaign Post From Linkedin
      description: Delete a published LinkedIn campaign post and update local status.
      operationId: delete_campaign_post_from_linkedin_api_external_platform_linkedin_delete_campaign_post_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkedInCampaignPostRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/linkedin/sync-post-status:
    post:
      tags:
      - external-platform
      summary: Sync Linkedin Campaign Post Status
      description: Refresh one LinkedIn post status from remote API.
      operationId: sync_linkedin_campaign_post_status_api_external_platform_linkedin_sync_post_status_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkedInCampaignPostRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/linkedin-social/disconnect:
    post:
      tags:
      - external-platform
      summary: Disconnect Linkedin Social
      description: Disconnect LinkedIn social integration.
      operationId: disconnect_linkedin_social_api_external_platform_linkedin_social_disconnect_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/shopify/callback:
    get:
      tags:
      - external-platform
      summary: Shopify Callback
      description: 'Handle Shopify OAuth callback and store tokens.


        Verifies HMAC signature and state token before processing.

        Stores credentials in data_source_integrations table.'
      operationId: shopify_callback_api_external_platform_shopify_callback_get
      parameters:
      - name: code
        in: query
        required: true
        schema:
          type: string
          title: Code
      - name: shop
        in: query
        required: true
        schema:
          type: string
          title: Shop
      - name: state
        in: query
        required: true
        schema:
          type: string
          title: State
      - name: hmac
        in: query
        required: true
        schema:
          type: string
          title: Hmac
      - name: timestamp
        in: query
        required: false
        schema:
          type: string
          title: Timestamp
      - name: host
        in: query
        required: false
        schema:
          type: string
          title: Host
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/shopify/install:
    get:
      tags:
      - external-platform
      summary: Shopify Install
      description: 'Shopify-initiated install entry — the app''s configured App URL.


        Verifies the install request HMAC over the raw query string, then redirects to

        Shopify''s OAuth grant. No Pomo profile is known yet; it is resolved after OAuth

        (see /shopify/install/resolve). Keeps installation initiated from a

        Shopify-owned surface with OAuth before any Pomo UI (2.3.1 / 2.3.2).'
      operationId: shopify_install_api_external_platform_shopify_install_get
      parameters:
      - name: shop
        in: query
        required: true
        schema:
          type: string
          title: Shop
      - name: hmac
        in: query
        required: false
        schema:
          type: string
          title: Hmac
      - name: host
        in: query
        required: false
        schema:
          type: string
          title: Host
      - name: timestamp
        in: query
        required: false
        schema:
          type: string
          title: Timestamp
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/shopify/install/launch:
    get:
      tags:
      - external-platform
      summary: Shopify Install Launch
      description: 'Top-level launch hop for embedded-initiated installs.


        The App Home''s begin-install runs inside the Admin iframe, where no cookie it

        sets would be visible to the new top-level tab. So begin-install returns THIS

        URL instead of the raw authorize URL: the new tab lands here first-party, gets

        the browser-binding OAuth-state cookie, and is bounced straight to Shopify''s

        grant. Token-gated (signed, 2-minute TTL, shop+origin baked in) — not authed,

        by design: it only starts an OAuth grant for the shop named in the token.'
      operationId: shopify_install_launch_api_external_platform_shopify_install_launch_get
      parameters:
      - name: token
        in: query
        required: true
        schema:
          type: string
          title: Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/shopify/connect/start:
    post:
      tags:
      - external-platform
      summary: Shopify Connect Start
      description: 'Pomo-initiated on-ramp. Stashes the pre-known binding intent (as a single-use

        connection request) and returns the App Store listing redirect — a

        Shopify-owned surface.


        The binding intent now travels server-side: a signed ``pomo_shopify_intent``

        cookie carries it across the single Shopify OAuth hop, where the callback

        embeds it into the Redis pending install (the object that follows the install

        to resolve from any tab). The returned ``intent_token`` is retained as a

        backward-compat carrier (older frontends; in-flight installs across the deploy)

        and its absence is now non-fatal. The install stays 2.3.1-compliant either way

        (no manual domain entry).'
      operationId: shopify_connect_start_api_external_platform_shopify_connect_start_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShopifyConnectStartRequestModel'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/shopify/install/resolve:
    post:
      tags:
      - external-platform
      summary: Shopify Install Resolve
      description: 'Post-OAuth resolution (authenticated). Claims the pending install for the user,

        then binds per the Pomo intent (if present) or the §7 matrix. Returns the

        resolved action + redirect, or a picker payload (needs_org / needs_profile).'
      operationId: shopify_install_resolve_api_external_platform_shopify_install_resolve_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShopifyInstallResolveRequestModel'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Shopify Install Resolve Api External Platform Shopify Install Resolve Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/shopify/privacy/webhooks:
    post:
      tags:
      - external-platform
      summary: Shopify Privacy Webhook
      description: 'Receive Shopify mandatory privacy compliance webhooks.


        The endpoint is intentionally unauthenticated because Shopify authenticates

        the delivery with X-Shopify-Hmac-SHA256 over the raw body.'
      operationId: shopify_privacy_webhook_api_external_platform_shopify_privacy_webhooks_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Shopify Privacy Webhook Api External Platform Shopify Privacy Webhooks Post
  /api/external-platform/shopify/webhooks/app-uninstalled:
    post:
      tags:
      - external-platform
      summary: Shopify App Uninstalled Webhook
      description: 'Handle Shopify''s app/uninstalled webhook.


        When a merchant removes the app, Shopify has already revoked the access

        token, so there is nothing to revoke provider-side — we just clear the

        now-dead local credentials. The endpoint is unauthenticated by design:

        Shopify authenticates delivery with X-Shopify-Hmac-SHA256 over the raw body.'
      operationId: shopify_app_uninstalled_webhook_api_external_platform_shopify_webhooks_app_uninstalled_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Shopify App Uninstalled Webhook Api External Platform Shopify Webhooks App Uninstalled Post
  /api/external-platform/shopify/shop:
    get:
      tags:
      - external-platform
      summary: Get Shopify Shop
      description: 'Get connected Shopify shop information.


        Returns connection status and shop details if connected.'
      operationId: get_shopify_shop_api_external_platform_shopify_shop_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopifyShopResponseModel'
      security:
      - HTTPBearer: []
  /api/external-platform/shopify/status:
    get:
      tags:
      - external-platform
      summary: Get Shopify Status
      description: "Get Shopify connection status with optional health check.\n\nShopify tokens expire roughly every 60 minutes. Use check_health=true to\nrefresh the stored access token if needed and then verify it with a live API\ncall. Refreshing from mf-core is safe because token refreshes are serialized\nwith the UDM pipeline via the shared per-integration advisory lock, so a\nrefresh here can no longer race the pipeline's rotation.\n\nArgs:\n    check_health: If true, refresh if needed and perform a live API call to\n        verify token validity"
      operationId: get_shopify_status_api_external_platform_shopify_status_get
      security:
      - HTTPBearer: []
      parameters:
      - name: check_health
        in: query
        required: false
        schema:
          type: boolean
          description: Perform live health check
          default: false
          title: Check Health
        description: Perform live health check
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopifyStatusResponseModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/shopify/orders:
    get:
      tags:
      - external-platform
      summary: Get Shopify Orders
      description: Get orders from connected Shopify store.
      operationId: get_shopify_orders_api_external_platform_shopify_orders_get
      security:
      - HTTPBearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 250
          minimum: 1
          default: 50
          title: Limit
      - name: status
        in: query
        required: false
        schema:
          type: string
          default: any
          title: Status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceOrdersResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/shopify/disconnect:
    delete:
      tags:
      - external-platform
      summary: Disconnect Shopify
      description: 'Disconnect Shopify integration.


        This uninstalls the app from Shopify before soft-deleting local credentials.'
      operationId: disconnect_shopify_api_external_platform_shopify_disconnect_delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceDisconnectResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/shopify/app-home:
    get:
      tags:
      - external-platform
      summary: Shopify App Home
      description: 'Serve the embedded App Home HTML shell with a shop-scoped framing policy.


        Not session-token authed: this serves the shell before App Bridge exists.

        The ``shop`` param is validated (SSRF-safe) and 400 on anything that is not a

        real myshopify domain.'
      operationId: shopify_app_home_api_external_platform_shopify_app_home_get
      parameters:
      - name: shop
        in: query
        required: true
        schema:
          type: string
          title: Shop
      - name: host
        in: query
        required: false
        schema:
          type: string
          default: ''
          title: Host
      responses:
        '200':
          description: Successful Response
          content:
            text/html:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/shopify/app/status:
    get:
      tags:
      - external-platform
      summary: Shopify App Status
      description: 'Return the App Home status for the session token''s shop.


        Always 200 for a valid token. Unbound shops yield ``bound=false`` with the

        shop domain still populated; every profile-related field is null.'
      operationId: shopify_app_status_api_external_platform_shopify_app_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppHomeStatusResponse'
  /api/external-platform/shopify/app/sync:
    post:
      tags:
      - external-platform
      summary: Shopify App Sync
      description: 'Re-run the catalog sync for the session token''s shop.


        409 when the shop is not bound to any Pomo profile (there is nothing to sync).'
      operationId: shopify_app_sync_api_external_platform_shopify_app_sync_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppHomeSyncResponse'
  /api/external-platform/shopify/app/begin-install:
    post:
      tags:
      - external-platform
      summary: Shopify App Begin Install
      description: 'Return the URL the embedded page opens (new tab) to (re)run the OAuth grant.


        Works for both bound and unbound shops — a bound shop may re-run OAuth on

        reinstall. The URL is the top-level /install/launch hop (NOT the raw Shopify

        authorize URL): this XHR runs inside the Admin iframe, where no cookie it set

        would be visible to the new tab, and the OAuth state must be browser-bound.

        The launch hop sets the OAuth-state cookie first-party and bounces to Shopify

        (state minted there with origin "app_home" — never inherits an intent cookie).'
      operationId: shopify_app_begin_install_api_external_platform_shopify_app_begin_install_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppHomeBeginInstallResponse'
  /api/external-platform/stripe/auth:
    get:
      tags:
      - external-platform
      summary: Stripe Auth
      description: Get Stripe Connect OAuth authorization URL.
      operationId: stripe_auth_api_external_platform_stripe_auth_get
      security:
      - HTTPBearer: []
      parameters:
      - name: write_access
        in: query
        required: false
        schema:
          type: boolean
          description: Request read_write access instead of read_only
          default: false
          title: Write Access
        description: Request read_write access instead of read_only
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceAuthResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/stripe/callback:
    get:
      tags:
      - external-platform
      summary: Stripe Callback
      description: 'Handle Stripe Connect OAuth callback and store tokens.


        CRITICAL: Authorization codes can only be used ONCE.

        The state verification also prevents replay attacks.

        Stores credentials in data_source_integrations table.'
      operationId: stripe_callback_api_external_platform_stripe_callback_get
      parameters:
      - name: code
        in: query
        required: false
        schema:
          type: string
          title: Code
      - name: state
        in: query
        required: true
        schema:
          type: string
          title: State
      - name: error
        in: query
        required: false
        schema:
          type: string
          title: Error
      - name: error_description
        in: query
        required: false
        schema:
          type: string
          title: Error Description
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/stripe/account:
    get:
      tags:
      - external-platform
      summary: Get Stripe Account
      description: 'Get connected Stripe account information.


        Returns connection status and account details if connected.'
      operationId: get_stripe_account_api_external_platform_stripe_account_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceAccountResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/stripe/status:
    get:
      tags:
      - external-platform
      summary: Get Stripe Status
      description: "Get Stripe connection status with optional health check.\n\nStripe tokens don't expire but can be revoked. Use check_health=true\nto verify the token is still valid by making a live API call.\n\nArgs:\n    check_health: If true, perform a live API call to verify token validity"
      operationId: get_stripe_status_api_external_platform_stripe_status_get
      security:
      - HTTPBearer: []
      parameters:
      - name: check_health
        in: query
        required: false
        schema:
          type: boolean
          description: Perform live health check
          default: false
          title: Check Health
        description: Perform live health check
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StripeStatusResponseModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/stripe/transactions:
    get:
      tags:
      - external-platform
      summary: Get Stripe Transactions
      description: Get balance transactions from connected Stripe account.
      operationId: get_stripe_transactions_api_external_platform_stripe_transactions_get
      security:
      - HTTPBearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 100
          title: Limit
      - name: starting_after
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Starting After
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceTransactionsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/stripe/disconnect:
    delete:
      tags:
      - external-platform
      summary: Disconnect Stripe
      description: 'Disconnect Stripe account.


        This deauthorizes on Stripe''s side before soft-deleting the local integration.'
      operationId: disconnect_stripe_api_external_platform_stripe_disconnect_delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceDisconnectResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/quickbooks/auth:
    get:
      tags:
      - external-platform
      summary: Quickbooks Auth
      description: Get QuickBooks Online OAuth authorization URL.
      operationId: quickbooks_auth_api_external_platform_quickbooks_auth_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceAuthResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/quickbooks/callback:
    get:
      tags:
      - external-platform
      summary: Quickbooks Callback
      description: 'Handle QuickBooks Online OAuth callback and store tokens.


        Intuit callback includes realmId which must be stored to call the Accounting API.'
      operationId: quickbooks_callback_api_external_platform_quickbooks_callback_get
      parameters:
      - name: code
        in: query
        required: false
        schema:
          type: string
          title: Code
      - name: realmId
        in: query
        required: false
        schema:
          type: string
          description: QuickBooks company ID (realmId)
          title: Realmid
        description: QuickBooks company ID (realmId)
      - name: state
        in: query
        required: true
        schema:
          type: string
          title: State
      - name: error
        in: query
        required: false
        schema:
          type: string
          title: Error
      - name: error_description
        in: query
        required: false
        schema:
          type: string
          title: Error Description
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/quickbooks/account:
    get:
      tags:
      - external-platform
      summary: Get Quickbooks Account
      description: Get connected QuickBooks account information (realm + company name if available).
      operationId: get_quickbooks_account_api_external_platform_quickbooks_account_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceAccountResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/quickbooks/status:
    get:
      tags:
      - external-platform
      summary: Get Quickbooks Status
      description: 'Get QuickBooks connection status with optional health check.


        When check_health=true, performs a lightweight CompanyInfo call only if the

        currently stored access token is still fresh. Databricks owns token refresh

        for UDM data-platform flows.'
      operationId: get_quickbooks_status_api_external_platform_quickbooks_status_get
      security:
      - HTTPBearer: []
      parameters:
      - name: check_health
        in: query
        required: false
        schema:
          type: boolean
          description: Perform live health check
          default: false
          title: Check Health
        description: Perform live health check
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuickBooksStatusResponseModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/quickbooks/disconnect:
    delete:
      tags:
      - external-platform
      summary: Disconnect Quickbooks
      description: Disconnect QuickBooks account after revoking provider-side tokens.
      operationId: disconnect_quickbooks_api_external_platform_quickbooks_disconnect_delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceDisconnectResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/quickbooks/initial-sync-status:
    get:
      tags:
      - external-platform
      summary: Get Initial Sync Status
      description: 'Get the status of the initial data sync triggered after OAuth connection.


        Returns the current sync status and, if still running, polls Databricks

        for the latest status.'
      operationId: get_initial_sync_status_api_external_platform_quickbooks_initial_sync_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitialSyncStatusResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/google-analytics/auth:
    get:
      tags:
      - external-platform
      summary: Google Analytics Auth
      description: Get Google Analytics OAuth authorization URL.
      operationId: google_analytics_auth_api_external_platform_google_analytics_auth_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceAuthResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/google-analytics/callback:
    get:
      tags:
      - external-platform
      summary: Google Analytics Callback
      description: Handle Google Analytics OAuth callback and store tokens.
      operationId: google_analytics_callback_api_external_platform_google_analytics_callback_get
      parameters:
      - name: code
        in: query
        required: false
        schema:
          type: string
          title: Code
      - name: state
        in: query
        required: true
        schema:
          type: string
          title: State
      - name: error
        in: query
        required: false
        schema:
          type: string
          title: Error
      - name: error_description
        in: query
        required: false
        schema:
          type: string
          title: Error Description
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/google-analytics/status:
    get:
      tags:
      - external-platform
      summary: Get Google Analytics Status
      description: Get Google Analytics connection status with optional live health check.
      operationId: get_google_analytics_status_api_external_platform_google_analytics_status_get
      security:
      - HTTPBearer: []
      parameters:
      - name: check_health
        in: query
        required: false
        schema:
          type: boolean
          description: Perform live health check
          default: false
          title: Check Health
        description: Perform live health check
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAnalyticsStatusResponseModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/google-analytics/properties:
    get:
      tags:
      - external-platform
      summary: Get Google Analytics Properties
      description: List accessible GA4 properties for the connected Google account.
      operationId: get_google_analytics_properties_api_external_platform_google_analytics_properties_get
      security:
      - HTTPBearer: []
      parameters:
      - name: refresh
        in: query
        required: false
        schema:
          type: boolean
          description: Refresh property list from Google
          default: false
          title: Refresh
        description: Refresh property list from Google
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAnalyticsPropertiesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/google-analytics/properties/select:
    post:
      tags:
      - external-platform
      summary: Select Google Analytics Property
      description: Select the GA4 property to sync into the UDM pipeline.
      operationId: select_google_analytics_property_api_external_platform_google_analytics_properties_select_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GoogleAnalyticsPropertySelectRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoogleAnalyticsPropertySelectResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/google-analytics/disconnect:
    delete:
      tags:
      - external-platform
      summary: Disconnect Google Analytics
      description: Disconnect Google Analytics after revoking the Google OAuth grant.
      operationId: disconnect_google_analytics_api_external_platform_google_analytics_disconnect_delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceDisconnectResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/google-analytics/initial-sync-status:
    get:
      tags:
      - external-platform
      summary: Get Google Analytics Initial Sync Status
      description: Get the status of the GA4 initial Databricks sync.
      operationId: get_google_analytics_initial_sync_status_api_external_platform_google_analytics_initial_sync_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitialSyncStatusResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/square/auth:
    get:
      tags:
      - external-platform
      summary: Square Auth
      description: Get Square OAuth authorization URL.
      operationId: square_auth_api_external_platform_square_auth_get
      security:
      - HTTPBearer: []
      parameters:
      - name: write_access
        in: query
        required: false
        schema:
          type: boolean
          description: Request write scopes for sandbox seeding or re-auth
          default: false
          title: Write Access
        description: Request write scopes for sandbox seeding or re-auth
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceAuthResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/square/callback:
    get:
      tags:
      - external-platform
      summary: Square Callback
      description: 'Handle Square OAuth callback and store tokens.


        Stores credentials in data_source_integrations table.'
      operationId: square_callback_api_external_platform_square_callback_get
      parameters:
      - name: code
        in: query
        required: false
        schema:
          type: string
          title: Code
      - name: state
        in: query
        required: true
        schema:
          type: string
          title: State
      - name: error
        in: query
        required: false
        schema:
          type: string
          title: Error
      - name: error_description
        in: query
        required: false
        schema:
          type: string
          title: Error Description
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/square/webhooks:
    post:
      tags:
      - external-platform
      summary: Square Webhook
      description: 'Receive Square lifecycle webhooks.


        The endpoint is unauthenticated because Square authenticates webhook

        delivery with x-square-hmacsha256-signature over the configured

        notification URL plus raw request body.'
      operationId: square_webhook_api_external_platform_square_webhooks_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Square Webhook Api External Platform Square Webhooks Post
  /api/external-platform/square/status:
    get:
      tags:
      - external-platform
      summary: Get Square Status
      description: "Get Square connection status with optional health check.\n\nArgs:\n    check_health: If true, perform a live API call to verify token validity"
      operationId: get_square_status_api_external_platform_square_status_get
      security:
      - HTTPBearer: []
      parameters:
      - name: check_health
        in: query
        required: false
        schema:
          type: boolean
          description: Perform live health check
          default: false
          title: Check Health
        description: Perform live health check
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SquareStatusResponseModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/square/accounts:
    get:
      tags:
      - external-platform
      summary: Get Square Accounts
      description: 'Get Square locations/accounts for the authenticated company.


        Returns locations as "accounts" to maintain consistency with other platforms.'
      operationId: get_square_accounts_api_external_platform_square_accounts_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceLocationsResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/square/disconnect:
    delete:
      tags:
      - external-platform
      summary: Disconnect Square
      description: 'Disconnect Square account.


        This revokes the Square OAuth authorization before soft-deleting the local integration.'
      operationId: disconnect_square_api_external_platform_square_disconnect_delete
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceDisconnectResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/klaviyo/auth:
    get:
      tags:
      - external-platform
      summary: Klaviyo Auth
      description: "Get Klaviyo OAuth authorization URL with PKCE for the current company profile.\n\nReturns:\n    KlaviyoAuthResponse with the OAuth authorization URL"
      operationId: klaviyo_auth_api_external_platform_klaviyo_auth_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KlaviyoAuthResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/klaviyo/callback:
    get:
      tags:
      - external-platform
      summary: Klaviyo Callback
      description: 'Handle Klaviyo OAuth callback with PKCE and store tokens.


        Stores credentials in data_source_integrations table.'
      operationId: klaviyo_callback_api_external_platform_klaviyo_callback_get
      parameters:
      - name: code
        in: query
        required: false
        schema:
          type: string
          title: Code
      - name: state
        in: query
        required: false
        schema:
          type: string
          title: State
      - name: error
        in: query
        required: false
        schema:
          type: string
          title: Error
      - name: error_description
        in: query
        required: false
        schema:
          type: string
          title: Error Description
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/klaviyo/accounts:
    get:
      tags:
      - external-platform
      summary: Get Klaviyo Accounts
      description: 'Get Klaviyo lists and segments for the authenticated company.


        Returns lists and segments as "accounts" to maintain consistency with other platforms.'
      operationId: get_klaviyo_accounts_api_external_platform_klaviyo_accounts_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KlaviyoAccountsResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/klaviyo/status:
    get:
      tags:
      - external-platform
      summary: Get Klaviyo Status
      description: Check Klaviyo integration status for the current company profile.
      operationId: get_klaviyo_status_api_external_platform_klaviyo_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KlaviyoStatusResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/klaviyo/health:
    get:
      tags:
      - external-platform
      summary: Get Klaviyo Health
      description: 'Get Klaviyo connection health status.


        Critical for monitoring 10-minute token expiry.'
      operationId: get_klaviyo_health_api_external_platform_klaviyo_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KlaviyoHealthResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/klaviyo/disconnect:
    post:
      tags:
      - external-platform
      summary: Disconnect Klaviyo
      description: Disconnect Klaviyo integration by revoking tokens and marking as inactive.
      operationId: disconnect_klaviyo_api_external_platform_klaviyo_disconnect_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/{platform}/initial-sync-status:
    get:
      tags:
      - external-platform
      summary: Get Provider Initial Sync Status
      description: Get initial Databricks sync status for a supported data-source provider.
      operationId: get_provider_initial_sync_status_api_external_platform__platform__initial_sync_status_get
      security:
      - HTTPBearer: []
      parameters:
      - name: platform
        in: path
        required: true
        schema:
          type: string
          title: Platform
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitialSyncStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/slack/auth:
    get:
      tags:
      - external-platform
      summary: Slack Auth
      operationId: slack_auth_api_external_platform_slack_auth_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceAuthResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/slack/callback:
    get:
      tags:
      - external-platform
      summary: Slack Callback
      operationId: slack_callback_api_external_platform_slack_callback_get
      parameters:
      - name: code
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
      - name: state
        in: query
        required: true
        schema:
          type: string
          title: State
      - name: error
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      - name: error_description
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Description
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/slack/status:
    get:
      tags:
      - external-platform
      summary: Slack Status
      operationId: slack_status_api_external_platform_slack_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackStatusResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/slack/channels:
    get:
      tags:
      - external-platform
      summary: List Slack Channels
      operationId: list_slack_channels_api_external_platform_slack_channels_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackChannelsListResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/slack/settings:
    patch:
      tags:
      - external-platform
      summary: Update Slack Settings
      operationId: update_slack_settings_api_external_platform_slack_settings_patch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlackSettingsUpdateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/slack/link:
    post:
      tags:
      - external-platform
      summary: Link Slack Identity
      operationId: link_slack_identity_api_external_platform_slack_link_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlackLinkRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlackLinkResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/slack/test-message:
    post:
      tags:
      - external-platform
      summary: Slack Test Message
      operationId: slack_test_message_api_external_platform_slack_test_message_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlackTestMessageRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/slack/campaign-card:
    post:
      tags:
      - external-platform
      summary: Slack Campaign Card
      operationId: slack_campaign_card_api_external_platform_slack_campaign_card_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SlackCampaignCardRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/slack/disconnect:
    post:
      tags:
      - external-platform
      summary: Slack Disconnect
      operationId: slack_disconnect_api_external_platform_slack_disconnect_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSourceDisconnectResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/slack/events:
    post:
      tags:
      - external-platform
      summary: Slack Events
      operationId: slack_events_api_external_platform_slack_events_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/external-platform/slack/interactions:
    post:
      tags:
      - external-platform
      summary: Slack Interactions
      operationId: slack_interactions_api_external_platform_slack_interactions_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/external-platform/slack/commands:
    post:
      tags:
      - external-platform
      summary: Slack Commands
      operationId: slack_commands_api_external_platform_slack_commands_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /api/external-platform/facebook-social/auth:
    get:
      tags:
      - external-platform
      summary: Facebook Social Auth
      operationId: facebook_social_auth_api_external_platform_facebook_social_auth_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/facebook-social/callback:
    get:
      tags:
      - external-platform
      summary: Facebook Social Callback
      operationId: facebook_social_callback_api_external_platform_facebook_social_callback_get
      parameters:
      - name: code
        in: query
        required: false
        schema:
          type: string
          title: Code
      - name: state
        in: query
        required: false
        schema:
          type: string
          title: State
      - name: error
        in: query
        required: false
        schema:
          type: string
          title: Error
      - name: error_description
        in: query
        required: false
        schema:
          type: string
          title: Error Description
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/facebook-social/status:
    get:
      tags:
      - external-platform
      summary: Facebook Social Status
      operationId: facebook_social_status_api_external_platform_facebook_social_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/facebook-social/pages:
    get:
      tags:
      - external-platform
      summary: Get Facebook Pages
      operationId: get_facebook_pages_api_external_platform_facebook_social_pages_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/facebook-social/activation:
    get:
      tags:
      - external-platform
      summary: Get Facebook Social Activation
      operationId: get_facebook_social_activation_api_external_platform_facebook_social_activation_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/facebook-social/activate:
    post:
      tags:
      - external-platform
      summary: Activate Facebook Social Page
      operationId: activate_facebook_social_page_api_external_platform_facebook_social_activate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FacebookSocialActivateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/facebook-social/disconnect:
    post:
      tags:
      - external-platform
      summary: Disconnect Facebook Social
      operationId: disconnect_facebook_social_api_external_platform_facebook_social_disconnect_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/facebook-social/post-campaign:
    post:
      tags:
      - external-platform
      summary: Post Campaign To Facebook
      operationId: post_campaign_to_facebook_api_external_platform_facebook_social_post_campaign_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FacebookPostCampaignRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostResponseModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/facebook-social/delete-post:
    post:
      tags:
      - external-platform
      summary: Delete Facebook Story Post
      operationId: delete_facebook_story_post_api_external_platform_facebook_social_delete_post_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeletePostRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletePostResponseModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/external-platform/hubspot/auth:
    get:
      tags:
      - external-platform
      summary: Hubspot Auth
      description: "Get the HubSpot OAuth authorization URL for the current company profile.\n\nReturns:\n    HubSpotAuthResponse with the OAuth authorization URL."
      operationId: hubspot_auth_api_external_platform_hubspot_auth_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubSpotAuthResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/hubspot/callback:
    get:
      tags:
      - external-platform
      summary: Hubspot Callback
      description: 'Handle the HubSpot OAuth callback and store tokens.


        Stores credentials in the data_source_integrations table.'
      operationId: hubspot_callback_api_external_platform_hubspot_callback_get
      parameters:
      - name: code
        in: query
        required: false
        schema:
          type: string
          title: Code
      - name: state
        in: query
        required: false
        schema:
          type: string
          title: State
      - name: error
        in: query
        required: false
        schema:
          type: string
          title: Error
      - name: error_description
        in: query
        required: false
        schema:
          type: string
          title: Error Description
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/external-platform/hubspot/status:
    get:
      tags:
      - external-platform
      summary: Get Hubspot Status
      description: Check HubSpot integration status for the current company profile.
      operationId: get_hubspot_status_api_external_platform_hubspot_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubSpotStatusResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/hubspot/health:
    get:
      tags:
      - external-platform
      summary: Get Hubspot Health
      description: Get HubSpot connection health status.
      operationId: get_hubspot_health_api_external_platform_hubspot_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubSpotHealthResponse'
      security:
      - HTTPBearer: []
  /api/external-platform/hubspot/disconnect:
    post:
      tags:
      - external-platform
      summary: Disconnect Hubspot
      description: Disconnect HubSpot by revoking tokens and marking the integration inactive.
      operationId: disconnect_hubspot_api_external_platform_hubspot_disconnect_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - HTTPBearer: []
  /api/external-platform/hubspot/initial-sync-status:
    get:
      tags:
      - external-platform
      summary: Hubspot Initial Sync Status
      description: Get the HubSpot initial Databricks sync status for the current profile.
      operationId: hubspot_initial_sync_status_api_external_platform_hubspot_initial_sync_status_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Hubspot Initial Sync Status Api External Platform Hubspot Initial Sync Status Get
      security:
      - HTTPBearer: []
components:
  schemas:
    SlackLinkResponse:
      properties:
        linked:
          type: boolean
          title: Linked
        slack_team_id:
          type: string
          title: Slack Team Id
        slack_user_id:
          type: string
          title: Slack User Id
      type: object
      required:
      - linked
      - slack_team_id
      - slack_user_id
      title: SlackLinkResponse
    TikTokAuthResponseModel:
      properties:
        auth_url:
          type: string
          title: Auth Url
      type: object
      required:
      - auth_url
      title: TikTokAuthResponseModel
    KlaviyoAccountsResponse:
      properties:
        accounts:
          items:
            $ref: '#/components/schemas/KlaviyoList'
          type: array
          title: Accounts
      type: object
      required:
      - accounts
      title: KlaviyoAccountsResponse
      description: Response model for Klaviyo lists/segments.
    MetaSyncPreviewRequest:
      properties:
        platform_type:
          type: string
          title: Platform Type
          description: meta_feed or meta_stories_reels
        ad_id:
          type: string
          title: Ad Id
          description: ID of the specific ad to sync (UUID string)
        ad_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Ad Account Id
          description: Meta Ad Account ID (optional override)
        force_sync_fields:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Force Sync Fields
          description: Optional field allowlist for pending edits that should be previewed.
        pending_update:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Pending Update
          description: Pending Pomo edit payload to preview without saving it.
      type: object
      required:
      - platform_type
      - ad_id
      title: MetaSyncPreviewRequest
      description: Request model for previewing a Meta sync and billing impact.
    SlackChannelResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        is_private:
          type: boolean
          title: Is Private
          default: false
        is_member:
          type: boolean
          title: Is Member
          default: false
      type: object
      required:
      - id
      - name
      title: SlackChannelResponse
    AmazonKeywordsRequest:
      properties:
        profile_id:
          type: string
          title: Profile Id
        ad_group_id:
          type: string
          title: Ad Group Id
        keywords:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Keywords
      type: object
      required:
      - profile_id
      - ad_group_id
      - keywords
      title: AmazonKeywordsRequest
    SquareStatusResponseModel:
      properties:
        connected:
          type: boolean
          title: Connected
          description: Whether the platform is connected
        healthy:
          type: boolean
          title: Healthy
          description: Whether the token is healthy (passed API check)
          default: false
        health_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Health Message
          description: Health check result message
        account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Id
          description: Platform-specific account identifier
        account_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Name
          description: Display name for the account
        token_expires_soon:
          type: boolean
          title: Token Expires Soon
          description: Whether token expires within buffer period
          default: false
        last_health_check:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Health Check
          description: ISO timestamp of last health check
        merchant_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Merchant Id
          description: Square merchant ID
        business_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Business Name
          description: Business name
        primary_location_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Primary Location Id
          description: Primary location ID
        locations_count:
          type: integer
          title: Locations Count
          description: Number of locations
          default: 0
        granted_scopes:
          items:
            type: string
          type: array
          title: Granted Scopes
          description: Granted Square OAuth scopes
        has_write_access:
          type: boolean
          title: Has Write Access
          description: Whether the current integration includes Square write scopes
          default: false
        write_access_missing_scopes:
          items:
            type: string
          type: array
          title: Write Access Missing Scopes
          description: Missing standard Square write scopes required for sandbox seeding
      type: object
      required:
      - connected
      title: SquareStatusResponseModel
      description: Response model for Square connection status with health check.
      example:
        account_id: shop_12345
        account_name: My Store
        connected: true
        health_message: Token is valid
        healthy: true
        last_health_check: '2024-01-15T10:30:00Z'
        token_expires_soon: false
    GoogleLaunchAdCampaignRequest:
      properties:
        platform_type:
          type: string
          title: Platform Type
          description: 'Type of ad platform: google_display or google_search'
        ad_id:
          type: string
          title: Ad Id
          description: Normalized platform ad ID to launch
        google_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Google Account Id
          description: Legacy Google Ads account ID; launches use the active account
        bid_only:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Bid Only
          description: Whether to use 'Observation' (True) or 'Targeting' (False) for audiences
          default: true
        youtube_logo_image_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Youtube Logo Image Url
          description: Optional square logo GCS URL for YouTube/Google Video
        google_lead_form_config:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Google Lead Form Config
          description: Google Lead Form configuration
      type: object
      required:
      - platform_type
      - ad_id
      title: GoogleLaunchAdCampaignRequest
      description: Request model for launching an online ad campaign to Google Ads.
    KlaviyoHealthResponse:
      properties:
        status:
          type: string
          title: Status
      type: object
      required:
      - status
      title: KlaviyoHealthResponse
      description: Response model for connection health status.
    GoogleAccountsResponseModel:
      properties:
        accounts:
          items:
            additionalProperties:
              anyOf:
              - type: string
              - type: integer
            type: object
          type: array
          title: Accounts
        activation_state:
          anyOf:
          - type: string
          - type: 'null'
          title: Activation State
        active_account:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Active Account
      type: object
      required:
      - accounts
      title: GoogleAccountsResponseModel
    MetaSyncAdCampaignRequest:
      properties:
        platform_type:
          type: string
          title: Platform Type
          description: meta_feed or meta_stories_reels
        ad_id:
          type: string
          title: Ad Id
          description: ID of the specific ad to sync (UUID string)
        ad_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Ad Account Id
          description: Meta Ad Account ID (optional override)
        force_sync_fields:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Force Sync Fields
          description: Optional field allowlist for pending edits that should be synced.
        pending_update:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Pending Update
          description: Pending Pomo edit payload to apply only after remote sync succeeds.
      type: object
      required:
      - platform_type
      - ad_id
      title: MetaSyncAdCampaignRequest
      description: Request model for syncing an online ad campaign to Meta.
    AmazonCampaignRequest:
      properties:
        profile_id:
          type: string
          title: Profile Id
        name:
          type: string
          title: Name
        campaign_type:
          type: string
          title: Campaign Type
          default: sponsoredProducts
        targeting_type:
          type: string
          title: Targeting Type
          default: manual
        daily_budget:
          type: number
          title: Daily Budget
          default: 10.0
        start_date:
          anyOf:
          - type: string
          - type: 'null'
          title: Start Date
        end_date:
          anyOf:
          - type: string
          - type: 'null'
          title: End Date
      type: object
      required:
      - profile_id
      - name
      title: AmazonCampaignRequest
    AmazonCampaignActionRequest:
      properties:
        platform_type:
          type: string
          title: Platform Type
          description: 'Type of ad platform: amazon_sponsored_products, amazon_sponsored_brands, or amazon_sponsored_display'
        ad_id:
          type: string
          title: Ad Id
          description: ID of the specific ad to act on
        profile_id:
          type: string
          title: Profile Id
          description: Amazon advertising profile ID
        action:
          type: string
          title: Action
          description: 'Action to perform: pause or delete'
      type: object
      required:
      - platform_type
      - ad_id
      - profile_id
      - action
      title: AmazonCampaignActionRequest
      description: Request model for pausing/deleting an Amazon campaign.
    InitialSyncStatusResponse:
      properties:
        status:
          type: string
          title: Status
          description: 'Current sync status: pending, running, completed, failed, skipped, not_started'
        run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Run Id
          description: Databricks job run ID
        triggered_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Triggered At
          description: When the sync was triggered (ISO format)
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if sync failed
        run_page_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Run Page Url
          description: URL to view the Databricks job run
      type: object
      required:
      - status
      title: InitialSyncStatusResponse
      description: 'Standard response for initial data-source sync status.


        Used by: GET /{platform}/initial-sync-status'
    routes__external_platform__google_action__GoogleDisplayAdRequest:
      properties:
        account_id:
          type: string
          title: Account Id
          description: Google Ads account ID
        ad_group_id:
          type: string
          title: Ad Group Id
          description: Ad group ID to create the ad in
        headline:
          type: string
          title: Headline
          description: Headline text for the ad
        long_headline:
          anyOf:
          - type: string
          - type: 'null'
          title: Long Headline
          description: Long headline for responsive display ads (max 90 characters)
        description:
          type: string
          title: Description
          description: Description text for the ad
        business_name:
          type: string
          title: Business Name
          description: Business name for the ad
        image_url:
          type: string
          title: Image Url
          description: URL of an image to use for the ad
        final_url:
          type: string
          title: Final Url
          description: Landing page URL for the ad
      type: object
      required:
      - account_id
      - ad_group_id
      - headline
      - description
      - business_name
      - image_url
      - final_url
      title: GoogleDisplayAdRequest
      description: Request model for creating a Google Display ad.
    StripeStatusResponseModel:
      properties:
        connected:
          type: boolean
          title: Connected
          description: Whether the platform is connected
        healthy:
          type: boolean
          title: Healthy
          description: Whether the token is healthy (passed API check)
          default: false
        health_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Health Message
          description: Health check result message
        account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Id
          description: Platform-specific account identifier
        account_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Name
          description: Display name for the account
        token_expires_soon:
          type: boolean
          title: Token Expires Soon
          description: Whether token expires within buffer period
          default: false
        last_health_check:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Health Check
          description: ISO timestamp of last health check
        business_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Business Name
          description: Business name
        livemode:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Livemode
          description: Whether Stripe is in live mode
        charges_enabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Charges Enabled
          description: Whether charges are enabled
      type: object
      required:
      - connected
      title: StripeStatusResponseModel
      description: Response model for connection status with health check.
      example:
        account_id: shop_12345
        account_name: My Store
        connected: true
        health_message: Token is valid
        healthy: true
        last_health_check: '2024-01-15T10:30:00Z'
        token_expires_soon: false
    MetaSelectAdAccountRequest:
      properties:
        ad_account_id:
          type: string
          title: Ad Account Id
          description: Meta Ad Account ID
        page_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Page Id
          description: Facebook Page ID to use as the ad identity
        instagram_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Instagram Account Id
          description: Optional Instagram business account ID linked to the Page
      type: object
      required:
      - ad_account_id
      title: MetaSelectAdAccountRequest
    DataSourceAuthResponse:
      properties:
        auth_url:
          type: string
          title: Auth Url
          description: OAuth authorization URL to redirect user to
      type: object
      required:
      - auth_url
      title: DataSourceAuthResponse
      description: 'Standard response for OAuth authorization URL endpoint.


        Used by: GET /{platform}/auth'
    GoogleAnalyticsPropertySelectResponse:
      properties:
        success:
          type: boolean
          title: Success
        property:
          $ref: '#/components/schemas/GoogleAnalyticsProperty'
        initial_sync:
          type: string
          title: Initial Sync
      type: object
      required:
      - success
      - property
      - initial_sync
      title: GoogleAnalyticsPropertySelectResponse
    DeletePostResponseModel:
      properties:
        success:
          type: boolean
          title: Success
      type: object
      required:
      - success
      title: DeletePostResponseModel
      description: Response model for Instagram post deletion.
    ShopifyConnectStartRequestModel:
      properties:
        mode:
          type: string
          title: Mode
          description: '''connect'' binds to the current profile; ''create'' makes a new profile from the store'
          default: create
      type: object
      title: ShopifyConnectStartRequestModel
      description: Pomo-initiated on-ramp request.
    TikTokSocialPostCampaignRequest:
      properties:
        campaign_id:
          type: string
          title: Campaign Id
        idea_number:
          type: integer
          title: Idea Number
        variation:
          type: integer
          title: Variation
          default: 0
        tiktok_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Tiktok Account Id
        settings:
          $ref: '#/components/schemas/TikTokSocialPublishSettings'
      type: object
      required:
      - campaign_id
      - idea_number
      - settings
      title: TikTokSocialPostCampaignRequest
    MetaAccountsResponseModel:
      properties:
        accounts:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Accounts
        pages:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Pages
        selected_ad_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Selected Ad Account Id
        activation_state:
          anyOf:
          - type: string
          - type: 'null'
          title: Activation State
        active_account:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Active Account
      type: object
      required:
      - accounts
      title: MetaAccountsResponseModel
    AppHomeSyncResponse:
      properties:
        sync_status:
          type: string
          title: Sync Status
          description: Result of trigger_initial_sync()
        message:
          type: string
          title: Message
          description: Human-readable status message
      type: object
      required:
      - sync_status
      - message
      title: AppHomeSyncResponse
      description: Result of a catalog re-sync triggered from the App Home.
    AmazonProductAdRequest:
      properties:
        profile_id:
          type: string
          title: Profile Id
        ad_group_id:
          type: string
          title: Ad Group Id
        asin:
          type: string
          title: Asin
      type: object
      required:
      - profile_id
      - ad_group_id
      - asin
      title: AmazonProductAdRequest
    DataSourceTransactionsResponse:
      properties:
        transactions:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Transactions
          description: List of transactions
        has_more:
          type: boolean
          title: Has More
          description: Whether more transactions are available
          default: false
        cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
          description: Cursor for pagination
      type: object
      title: DataSourceTransactionsResponse
      description: 'Response for transactions list endpoint.


        Used by: GET /stripe/transactions, GET /square/payments'
    KlaviyoAuthResponse:
      properties:
        auth_url:
          type: string
          title: Auth Url
      type: object
      required:
      - auth_url
      title: KlaviyoAuthResponse
      description: Response model for Klaviyo auth URL.
    AppHomeBeginInstallResponse:
      properties:
        authorize_url:
          type: string
          title: Authorize Url
          description: Shopify OAuth authorize URL for this shop
      type: object
      required:
      - authorize_url
      title: AppHomeBeginInstallResponse
      description: Shopify OAuth authorize URL for (re)running the install handshake.
    DataSourceLocationsResponse:
      properties:
        accounts:
          items:
            $ref: '#/components/schemas/DataSourceLocation'
          type: array
          title: Accounts
          description: List of locations/accounts
      type: object
      title: DataSourceLocationsResponse
      description: 'Response for locations/accounts list endpoint.


        Used by: GET /{platform}/accounts or GET /{platform}/locations'
    GoogleAnalyticsProperty:
      properties:
        account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Id
          description: Google Analytics account ID
        account_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Name
          description: Google Analytics account display name
        property_id:
          type: string
          title: Property Id
          description: GA4 numeric property ID
        property_resource_name:
          type: string
          title: Property Resource Name
          description: 'GA4 property resource name: properties/{id}'
        property_name:
          type: string
          title: Property Name
          description: GA4 property display name
        property_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Property Type
          description: GA4 property type
      type: object
      required:
      - property_id
      - property_resource_name
      - property_name
      title: GoogleAnalyticsProperty
    TikTokSyncPreviewRequest:
      properties:
        ad_id:
          type: string
          title: Ad Id
          description: Normalized platform ad UUID
        advertiser_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Advertiser Id
          description: TikTok advertiser ID
        pending_update:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Pending Update
          description: Pending Pomo edit payload to preview without saving it.
      type: object
      required:
      - ad_id
      title: TikTokSyncPreviewRequest
      description: Request model for previewing a TikTok normalized sync.
    LinkedInActivateAccountRequest:
      properties:
        account_id:
          type: string
          title: Account Id
        organization_urn:
          type: string
          title: Organization Urn
      type: object
      required:
      - account_id
      - organization_urn
      title: LinkedInActivateAccountRequest
    GoogleSyncAdCampaignRequest:
      properties:
        platform_type:
          type: string
          title: Platform Type
          description: google_search, google_display, or google_video
        ad_id:
          type: string
          title: Ad Id
          description: ID of the specific ad to sync
        google_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Google Account Id
          description: Google Ads account ID (optional override)
        force_sync_fields:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Force Sync Fields
          description: Optional fields to reconcile remotely even when the local diff is empty.
        pending_update:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Pending Update
          description: Pending Pomo edit payload to apply only after remote sync succeeds.
      type: object
      required:
      - platform_type
      - ad_id
      title: GoogleSyncAdCampaignRequest
      description: Request model for syncing an online ad campaign to Google Ads.
    DataSourceDisconnectResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether disconnect was successful
        message:
          type: string
          title: Message
          description: Result message
      type: object
      required:
      - success
      - message
      title: DataSourceDisconnectResponse
      description: 'Standard response for disconnect endpoint.


        Used by: DELETE /{platform}/disconnect or POST /{platform}/disconnect'
      example:
        message: Shopify account disconnected successfully
        success: true
    TikTokSyncAdRequest:
      properties:
        ad_id:
          type: string
          title: Ad Id
          description: Normalized platform ad UUID
        advertiser_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Advertiser Id
          description: TikTok advertiser ID
        pending_update:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Pending Update
          description: Pending Pomo edit payload to apply only after sync succeeds.
      type: object
      required:
      - ad_id
      title: TikTokSyncAdRequest
      description: Request model for syncing saved Pomo changes to a TikTok ad baseline.
    GoogleAnalyticsPropertySelectRequest:
      properties:
        property_resource_name:
          type: string
          title: Property Resource Name
          description: GA4 property resource name, e.g. properties/123456
      type: object
      required:
      - property_resource_name
      title: GoogleAnalyticsPropertySelectRequest
    JobResponse:
      properties:
        job_id:
          type: string
          title: Job Id
          description: Unique job identifier
        status:
          type: string
          title: Status
          description: Initial job status (typically 'running')
        stream_url:
          type: string
          title: Stream Url
          description: SSE endpoint for real-time progress
        poll_url:
          type: string
          title: Poll Url
          description: HTTP endpoint for polling status
      type: object
      required:
      - job_id
      - status
      - stream_url
      - poll_url
      title: JobResponse
      description: Response after submitting a job
      example:
        job_id: 987fcdeb-51a2-43f7-9876-543210987654
        poll_url: /api/chat/agentic/jobs/987fcdeb-51a2-43f7-9876-543210987654
        status: running
        stream_url: /api/chat/agentic/jobs/987fcdeb-51a2-43f7-9876-543210987654/stream
    FacebookSocialActivateRequest:
      properties:
        page_id:
          type: string
          title: Page Id
          description: Facebook Page ID to use for social publishing
      type: object
      required:
      - page_id
      title: FacebookSocialActivateRequest
    GoogleAuthResponseModel:
      properties:
        auth_url:
          type: string
          title: Auth Url
      type: object
      required:
      - auth_url
      title: GoogleAuthResponseModel
    TikTokAccountsResponseModel:
      properties:
        accounts:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Accounts
        activation_state:
          anyOf:
          - type: string
          - type: 'null'
          title: Activation State
        active_account:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Active Account
      type: object
      required:
      - accounts
      title: TikTokAccountsResponseModel
    HubSpotHealthResponse:
      properties:
        status:
          type: string
          title: Status
      type: object
      required:
      - status
      title: HubSpotHealthResponse
      description: Response model for the HubSpot connection health status.
    AppHomeStatusResponse:
      properties:
        bound:
          type: boolean
          title: Bound
          description: Whether the shop is bound to an active Pomo profile
        shop_domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Shop Domain
          description: The shop's myshopify.com domain from the session token
        shop_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Shop Name
          description: Human-readable shop name, if known
        company_profile_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Company Profile Id
          description: Bound company profile id (string UUID, sanitized)
        company_profile_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Company Profile Name
          description: Bound company profile name
        connection_health:
          anyOf:
          - type: string
          - type: 'null'
          title: Connection Health
          description: '''healthy'' | ''warning'' | ''critical'' | ''unknown'' | null'
        initial_sync_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Initial Sync Status
          description: '''pending'' | ''running'' | ''completed'' | ''failed'' | ''skipped'' | null'
        last_sync_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Sync At
          description: Last successful sync timestamp
        onboarding_complete:
          type: boolean
          title: Onboarding Complete
          description: Whether the bound profile has finished onboarding
          default: false
        pomo_url:
          type: string
          title: Pomo Url
          description: Deep-link into the full Pomo app
      type: object
      required:
      - bound
      - pomo_url
      title: AppHomeStatusResponse
      description: 'Status of an embedded shop as seen from the App Home.


        ``bound`` is the primary discriminator: when false the shop has no active

        Pomo binding and every profile-related field is null, but ``shop_domain`` is

        still populated from the verified session token so the UI can address the

        store.'
    BatchPostMetricsRequest:
      properties:
        instagram_account_id:
          type: string
          title: Instagram Account Id
        post_ids:
          items:
            type: string
          type: array
          title: Post Ids
      type: object
      required:
      - instagram_account_id
      - post_ids
      title: BatchPostMetricsRequest
      description: Request model for getting metrics for multiple Instagram posts.
    LinkedInLaunchVideoAdRequest:
      properties:
        ad_id:
          type: string
          title: Ad Id
        ad_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Ad Account Id
        organization_urn:
          anyOf:
          - type: string
          - type: 'null'
          title: Organization Urn
        targeting_discrimination_notice_acknowledged:
          type: boolean
          title: Targeting Discrimination Notice Acknowledged
          default: false
        political_intent_confirmed:
          type: boolean
          title: Political Intent Confirmed
          default: false
        linkedin_lead_form_config:
          anyOf:
          - $ref: '#/components/schemas/LinkedInLeadFormConfig'
          - type: 'null'
      type: object
      required:
      - ad_id
      title: LinkedInLaunchVideoAdRequest
    GoogleAdGroupRequest:
      properties:
        account_id:
          type: string
          title: Account Id
        campaign_id:
          type: string
          title: Campaign Id
        name:
          type: string
          title: Name
      type: object
      required:
      - account_id
      - campaign_id
      - name
      title: GoogleAdGroupRequest
    HubSpotStatusResponse:
      properties:
        connected:
          type: boolean
          title: Connected
        account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Id
        account_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Name
        portal_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Portal Id
      type: object
      required:
      - connected
      title: HubSpotStatusResponse
      description: Response model for the HubSpot connection status.
    LinkedInCampaignActionRequest:
      properties:
        platform_type:
          type: string
          title: Platform Type
        ad_id:
          type: string
          title: Ad Id
        ad_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Ad Account Id
        action:
          type: string
          title: Action
      type: object
      required:
      - platform_type
      - ad_id
      - action
      title: LinkedInCampaignActionRequest
    MetaLaunchAdCampaignRequest:
      properties:
        platform_type:
          type: string
          title: Platform Type
          description: 'Type of ad platform: meta_feed or meta_stories_reels'
        ad_id:
          title: Ad Id
          description: ID of the specific ad to launch (UUID string)
        ad_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Ad Account Id
          description: Legacy Meta Ad Account ID; launches use the active account
        page_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Page Id
          description: Facebook Page ID
        instagram_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Instagram Account Id
          description: Instagram Account ID
        placements:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Placements
          description: 'Placements override: instagram_stories, instagram_reels'
        meta_lead_form_config:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta Lead Form Config
          description: Meta Instant Form configuration
      type: object
      required:
      - platform_type
      - ad_id
      title: MetaLaunchAdCampaignRequest
      description: Request model for launching a Meta ad campaign
    GoogleAnalyticsStatusResponseModel:
      properties:
        connected:
          type: boolean
          title: Connected
          description: Whether the platform is connected
        healthy:
          type: boolean
          title: Healthy
          description: Whether the token is healthy (passed API check)
          default: false
        health_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Health Message
          description: Health check result message
        account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Id
          description: Platform-specific account identifier
        account_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Name
          description: Display name for the account
        token_expires_soon:
          type: boolean
          title: Token Expires Soon
          description: Whether token expires within buffer period
          default: false
        last_health_check:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Health Check
          description: ISO timestamp of last health check
        selected_property_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Selected Property Id
          description: Selected GA4 property ID
        selected_property_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Selected Property Name
          description: Selected GA4 property name
        selected_property_resource_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Selected Property Resource Name
          description: Selected GA4 property resource name
        property_count:
          type: integer
          title: Property Count
          description: Number of accessible GA4 properties
          default: 0
        property_selection_required:
          type: boolean
          title: Property Selection Required
          description: Whether the user must select a GA4 property
          default: false
        granted_scopes:
          items:
            type: string
          type: array
          title: Granted Scopes
          description: Granted Google OAuth scopes
        missing_scopes:
          items:
            type: string
          type: array
          title: Missing Scopes
          description: Configured scopes not granted by Google
        refresh_token_expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Refresh Token Expires At
          description: Refresh token expiry if Google returned time-bound access
        reconnect_required:
          type: boolean
          title: Reconnect Required
          description: Whether the user must reconnect Google Analytics
          default: false
      type: object
      required:
      - connected
      title: GoogleAnalyticsStatusResponseModel
      example:
        account_id: shop_12345
        account_name: My Store
        connected: true
        health_message: Token is valid
        healthy: true
        last_health_check: '2024-01-15T10:30:00Z'
        token_expires_soon: false
    ShopifyShopResponseModel:
      properties:
        connected:
          type: boolean
          title: Connected
          description: Whether the platform is connected
        account:
          anyOf:
          - $ref: '#/components/schemas/DataSourceAccountInfo'
          - type: 'null'
          description: Account details if connected
        shop:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Shop
          description: Shop details
      type: object
      required:
      - connected
      title: ShopifyShopResponseModel
      description: Response model for shop information.
    TikTokLaunchVideoAdRequest:
      properties:
        ad_id:
          type: string
          title: Ad Id
        advertiser_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Advertiser Id
        ad_text_override:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
          title: Ad Text Override
          description: 'Optional override for ad_text (TikTok requirement: max 100 chars)'
        display_name_override:
          anyOf:
          - type: string
            maxLength: 40
          - type: 'null'
          title: Display Name Override
          description: 'Optional override for display_name (TikTok requirement: max 40 chars)'
        ad_name_override:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
          title: Ad Name Override
          description: 'Optional override for ad_name (TikTok requirement: max 512 chars)'
      type: object
      required:
      - ad_id
      title: TikTokLaunchVideoAdRequest
      description: Request model for launching a TikTok video ad with optional text field overrides
    DataSourceAccountInfo:
      properties:
        id:
          type: string
          title: Id
          description: Platform-specific account ID
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Account/business name
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
          description: Account email
        currency:
          anyOf:
          - type: string
          - type: 'null'
          title: Currency
          description: Default currency (e.g., USD)
        country:
          anyOf:
          - type: string
          - type: 'null'
          title: Country
          description: Country code (e.g., US)
        timezone:
          anyOf:
          - type: string
          - type: 'null'
          title: Timezone
          description: Account timezone
      type: object
      required:
      - id
      title: DataSourceAccountInfo
      description: 'Standard account information model.


        Used by: GET /{platform}/account or embedded in other responses'
    MetaCampaignActionRequest:
      properties:
        platform_type:
          type: string
          title: Platform Type
          description: 'Type of ad platform: meta_feed or meta_stories_reels'
        ad_id:
          type: string
          title: Ad Id
          description: ID of the specific ad to act on
        ad_account_id:
          type: string
          title: Ad Account Id
          description: Meta Ad Account ID
        action:
          type: string
          title: Action
          description: 'Action to perform: pause or delete'
      type: object
      required:
      - platform_type
      - ad_id
      - ad_account_id
      - action
      title: MetaCampaignActionRequest
      description: Request model for pausing/deleting a Meta campaign.
    SlackSettingsUpdateRequest:
      properties:
        default_channel_id:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Default Channel Id
        allowlist_patterns:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Allowlist Patterns
          description: Optional Slack email allowlist patterns (e.g. *@machflow.ai, user@domain.com, @domain.com)
      type: object
      title: SlackSettingsUpdateRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    LinkedInSyncPreviewRequest:
      properties:
        platform_type:
          type: string
          title: Platform Type
        ad_id:
          type: string
          title: Ad Id
        ad_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Ad Account Id
        pending_update:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Pending Update
      type: object
      required:
      - platform_type
      - ad_id
      title: LinkedInSyncPreviewRequest
    TikTokAdStatusResponse:
      properties:
        success:
          type: boolean
          title: Success
        message:
          type: string
          title: Message
        status:
          type: string
          title: Status
          description: The new status of the ad (active/paused)
      type: object
      required:
      - success
      - message
      - status
      title: TikTokAdStatusResponse
      description: Response model for ad status update operations
    GoogleCreateAdFromCampaignRequest:
      properties:
        campaign_id:
          type: string
          title: Campaign Id
          description: ID of the campaign to create ad from
        idea_number:
          type: integer
          title: Idea Number
          description: Idea number within the campaign
        google_account_id:
          type: string
          title: Google Account Id
          description: Google Ads account ID to create the ad in
        variation:
          type: integer
          title: Variation
          description: Variation number (0 for original, 1+ for variations)
          default: 0
      type: object
      required:
      - campaign_id
      - idea_number
      - google_account_id
      title: GoogleCreateAdFromCampaignRequest
    GoogleSyncPreviewRequest:
      properties:
        platform_type:
          type: string
          title: Platform Type
          description: google_search, google_display, or google_video
        ad_id:
          type: string
          title: Ad Id
          description: ID of the specific ad to sync
        google_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Google Account Id
          description: Google Ads account ID (optional override)
        force_sync_fields:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Force Sync Fields
          description: Optional fields to reconcile remotely even when the local diff is empty.
        pending_update:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Pending Update
          description: Pending Pomo edit payload to preview without saving it.
      type: object
      required:
      - platform_type
      - ad_id
      title: GoogleSyncPreviewRequest
      description: Request model for previewing a sync and billing impact.
    MetaAuthResponseModel:
      properties:
        auth_url:
          type: string
          title: Auth Url
        auth_type:
          type: string
          title: Auth Type
      type: object
      required:
      - auth_url
      - auth_type
      title: MetaAuthResponseModel
    SlackLinkRequest:
      properties:
        slack_user_id:
          type: string
          maxLength: 64
          minLength: 2
          title: Slack User Id
        slack_team_id:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Slack Team Id
        slack_user_name:
          anyOf:
          - type: string
            maxLength: 255
          - type: 'null'
          title: Slack User Name
      type: object
      required:
      - slack_user_id
      title: SlackLinkRequest
    TikTokSocialPublishSettingsRequest:
      properties:
        campaign_id:
          type: string
          title: Campaign Id
        idea_number:
          type: integer
          title: Idea Number
        variation:
          type: integer
          title: Variation
          default: 0
        settings:
          $ref: '#/components/schemas/TikTokSocialPublishSettings'
      type: object
      required:
      - campaign_id
      - idea_number
      - settings
      title: TikTokSocialPublishSettingsRequest
    LinkedInLeadFormConfig:
      properties:
        name:
          type: string
          maxLength: 256
          title: Name
        headline:
          type: string
          maxLength: 60
          title: Headline
        description:
          anyOf:
          - type: string
            maxLength: 160
          - type: 'null'
          title: Description
          default: ''
        privacy_policy_url:
          type: string
          maxLength: 2000
          title: Privacy Policy Url
        thank_you_message:
          type: string
          maxLength: 300
          title: Thank You Message
        fields:
          items:
            type: string
            enum:
            - FIRST_NAME
            - LAST_NAME
            - EMAIL
            - WORK_EMAIL
            - PHONE_NUMBER
            - WORK_PHONE_NUMBER
            - JOB_TITLE
            - COMPANY_NAME
            - COMPANY_SIZE
            - INDUSTRY
            - CITY
            - STATE
            - COUNTRY
          type: array
          title: Fields
      type: object
      required:
      - name
      - headline
      - privacy_policy_url
      - thank_you_message
      - fields
      title: LinkedInLeadFormConfig
    TikTokAdPauseRequest:
      properties:
        ad_id:
          type: string
          title: Ad Id
          description: The database UUID of the ad to pause
        advertiser_id:
          type: string
          title: Advertiser Id
          description: The TikTok advertiser ID
      type: object
      required:
      - ad_id
      - advertiser_id
      title: TikTokAdPauseRequest
      description: Request model for pausing a TikTok ad
    HubSpotAuthResponse:
      properties:
        auth_url:
          type: string
          title: Auth Url
      type: object
      required:
      - auth_url
      title: HubSpotAuthResponse
      description: Response model for the HubSpot auth URL.
    LinkedInLaunchImageAdRequest:
      properties:
        ad_id:
          type: string
          title: Ad Id
        ad_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Ad Account Id
        organization_urn:
          anyOf:
          - type: string
          - type: 'null'
          title: Organization Urn
        targeting_discrimination_notice_acknowledged:
          type: boolean
          title: Targeting Discrimination Notice Acknowledged
          default: false
        political_intent_confirmed:
          type: boolean
          title: Political Intent Confirmed
          default: false
        linkedin_lead_form_config:
          anyOf:
          - $ref: '#/components/schemas/LinkedInLeadFormConfig'
          - type: 'null'
      type: object
      required:
      - ad_id
      title: LinkedInLaunchImageAdRequest
    CreatePostRequest:
      properties:
        instagram_account_id:
          type: string
          title: Instagram Account Id
        image_url:
          type: string
          title: Image Url
        caption:
          type: string
          title: Caption
        hashtags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Hashtags
      type: object
      required:
      - instagram_account_id
      - image_url
      - caption
      title: CreatePostRequest
      description: Request model for creating an Instagram post.
    SlackTestMessageRequest:
      properties:
        channel_id:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Channel Id
        text:
          anyOf:
          - type: string
            maxLength: 2500
          - type: 'null'
          title: Text
          description: Optional test message body
      type: object
      title: SlackTestMessageRequest
    QuickBooksStatusResponseModel:
      properties:
        connected:
          type: boolean
          title: Connected
          description: Whether the platform is connected
        healthy:
          type: boolean
          title: Healthy
          description: Whether the token is healthy (passed API check)
          default: false
        health_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Health Message
          description: Health check result message
        account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Id
          description: Platform-specific account identifier
        account_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Name
          description: Display name for the account
        token_expires_soon:
          type: boolean
          title: Token Expires Soon
          description: Whether token expires within buffer period
          default: false
        last_health_check:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Health Check
          description: ISO timestamp of last health check
        realm_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Realm Id
          description: QuickBooks company realm ID
        company_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Company Name
          description: Company name from QBO CompanyInfo
      type: object
      required:
      - connected
      title: QuickBooksStatusResponseModel
      description: Connection status with optional health check.
      example:
        account_id: shop_12345
        account_name: My Store
        connected: true
        health_message: Token is valid
        healthy: true
        last_health_check: '2024-01-15T10:30:00Z'
        token_expires_soon: false
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    DataSourceLocation:
      properties:
        id:
          type: string
          title: Id
          description: Location ID
        name:
          type: string
          title: Name
          description: Location name
        address:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Address
          description: Location address
        status:
          type: string
          title: Status
          description: Location status
          default: ACTIVE
        currency:
          type: string
          title: Currency
          description: Location currency
          default: USD
        timezone:
          anyOf:
          - type: string
          - type: 'null'
          title: Timezone
          description: Location timezone
      type: object
      required:
      - id
      - name
      title: DataSourceLocation
      description: 'Location model for platforms with multiple locations.


        Used by: Square, Shopify (locations)'
    SlackChannelsListResponse:
      properties:
        channels:
          items:
            $ref: '#/components/schemas/SlackChannelResponse'
          type: array
          title: Channels
      type: object
      title: SlackChannelsListResponse
    MetaCampaignResumeRequest:
      properties:
        platform_type:
          type: string
          title: Platform Type
          description: 'Type of ad platform: meta_feed or meta_stories_reels'
        ad_id:
          type: string
          title: Ad Id
          description: ID of the specific ad to act on (DB UUID or Meta ad id)
        ad_account_id:
          type: string
          title: Ad Account Id
          description: Meta Ad Account ID
      type: object
      required:
      - platform_type
      - ad_id
      - ad_account_id
      title: MetaCampaignResumeRequest
      description: Request model for resuming a Meta campaign (no action field).
    ShopifyStatusResponseModel:
      properties:
        connected:
          type: boolean
          title: Connected
          description: Whether the platform is connected
        healthy:
          type: boolean
          title: Healthy
          description: Whether the token is healthy (passed API check)
          default: false
        health_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Health Message
          description: Health check result message
        account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Id
          description: Platform-specific account identifier
        account_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Name
          description: Display name for the account
        token_expires_soon:
          type: boolean
          title: Token Expires Soon
          description: Whether token expires within buffer period
          default: false
        last_health_check:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Health Check
          description: ISO timestamp of last health check
        shop_domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Shop Domain
          description: Shopify store domain
        shop_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Shop Name
          description: Shop name
      type: object
      required:
      - connected
      title: ShopifyStatusResponseModel
      description: Response model for connection status with health check.
      example:
        account_id: shop_12345
        account_name: My Store
        connected: true
        health_message: Token is valid
        healthy: true
        last_health_check: '2024-01-15T10:30:00Z'
        token_expires_soon: false
    InstagramPostCampaignRequest:
      properties:
        campaign_id:
          type: string
          title: Campaign Id
          description: ID of the campaign to post
        idea_number:
          type: integer
          title: Idea Number
          description: Idea number within the campaign
        instagram_account_id:
          type: string
          title: Instagram Account Id
          description: Instagram business account ID to post to
        instagram_account_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Instagram Account Name
          description: Instagram account display name
        instagram_username:
          anyOf:
          - type: string
          - type: 'null'
          title: Instagram Username
          description: Instagram username without @
        auth_method:
          anyOf:
          - type: string
          - type: 'null'
          title: Auth Method
          description: 'Selected auth method: instagram or facebook'
        variation:
          type: integer
          title: Variation
          description: Variation number (0 for original, 1+ for variations)
          default: 0
      type: object
      required:
      - campaign_id
      - idea_number
      - instagram_account_id
      title: InstagramPostCampaignRequest
    PostResponseModel:
      properties:
        id:
          type: string
          title: Id
      type: object
      required:
      - id
      title: PostResponseModel
      description: Response model for created Instagram post.
    SlackCampaignCardRequest:
      properties:
        channel_id:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Channel Id
        thread_ts:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Thread Ts
        dedupe_key:
          anyOf:
          - type: string
            maxLength: 191
          - type: 'null'
          title: Dedupe Key
        campaign_info:
          additionalProperties: true
          type: object
          title: Campaign Info
          description: Generic campaign payload used to build Slack Block Kit cards.
      type: object
      title: SlackCampaignCardRequest
    FacebookPostCampaignRequest:
      properties:
        campaign_id:
          type: string
          title: Campaign Id
          description: ID of campaign to publish
        idea_number:
          type: integer
          title: Idea Number
          description: Idea number for campaign row
        page_id:
          type: string
          title: Page Id
          description: Facebook page ID to publish to
        page_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Page Name
          description: Facebook page name for posting identity display
        variation:
          type: integer
          title: Variation
          description: Variation number (default 0)
          default: 0
      type: object
      required:
      - campaign_id
      - idea_number
      - page_id
      title: FacebookPostCampaignRequest
    LinkedInCampaignPostRequest:
      properties:
        campaign_id:
          type: string
          title: Campaign Id
          description: ID of the campaign post
        idea_number:
          type: integer
          title: Idea Number
          description: Idea number within the campaign
        variation:
          type: integer
          title: Variation
          description: Variation number (0 for original, 1+ for variations)
          default: 0
      type: object
      required:
      - campaign_id
      - idea_number
      title: LinkedInCampaignPostRequest
    DeletePostRequest:
      properties:
        post_id:
          type: string
          title: Post Id
        auth_method:
          anyOf:
          - type: string
          - type: 'null'
          title: Auth Method
          description: 'Bound auth method: instagram or facebook'
      type: object
      required:
      - post_id
      title: DeletePostRequest
      description: Request model for deleting an Instagram post.
    InstagramAuthResponseModel:
      properties:
        auth_url:
          type: string
          title: Auth Url
      type: object
      required:
      - auth_url
      title: InstagramAuthResponseModel
      description: Response model for Instagram authorization URL.
    LinkedInCampaignResumeRequest:
      properties:
        platform_type:
          type: string
          title: Platform Type
        ad_id:
          type: string
          title: Ad Id
        ad_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Ad Account Id
      type: object
      required:
      - platform_type
      - ad_id
      title: LinkedInCampaignResumeRequest
    AmazonAdGroupRequest:
      properties:
        profile_id:
          type: string
          title: Profile Id
        campaign_id:
          type: string
          title: Campaign Id
        name:
          type: string
          title: Name
        default_bid:
          type: number
          title: Default Bid
          default: 1.0
      type: object
      required:
      - profile_id
      - campaign_id
      - name
      title: AmazonAdGroupRequest
    LinkedInSyncAdCampaignRequest:
      properties:
        platform_type:
          type: string
          title: Platform Type
        ad_id:
          type: string
          title: Ad Id
        ad_account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Ad Account Id
        pending_update:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Pending Update
      type: object
      required:
      - platform_type
      - ad_id
      title: LinkedInSyncAdCampaignRequest
    InstagramActivateIdentityRequest:
      properties:
        instagram_account_id:
          type: string
          title: Instagram Account Id
          description: Instagram account ID to use for social publishing
        auth_method:
          anyOf:
          - type: string
          - type: 'null'
          title: Auth Method
          description: 'Selected auth method: instagram or facebook'
      type: object
      required:
      - instagram_account_id
      title: InstagramActivateIdentityRequest
    TikTokAdResumeRequest:
      properties:
        ad_id:
          type: string
          title: Ad Id
          description: The database UUID of the ad to resume
        advertiser_id:
          type: string
          title: Advertiser Id
          description: The TikTok advertiser ID
      type: object
      required:
      - ad_id
      - advertiser_id
      title: TikTokAdResumeRequest
      description: Request model for resuming a TikTok ad
    GoogleCampaignActionRequest:
      properties:
        platform_type:
          type: string
          title: Platform Type
          description: 'Type of ad platform: google_display or google_search'
        ad_id:
          type: string
          title: Ad Id
          description: Normalized platform ad ID to act on
        google_account_id:
          type: string
          title: Google Account Id
          description: Google Ads account ID
        action:
          type: string
          title: Action
          description: 'Action to perform: pause or delete'
      type: object
      required:
      - platform_type
      - ad_id
      - google_account_id
      - action
      title: GoogleCampaignActionRequest
      description: Request model for pausing/deleting a Google campaign.
    DataSourceOrdersResponse:
      properties:
        orders:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Orders
          description: List of orders
        has_more:
          type: boolean
          title: Has More
          description: Whether more orders are available
          default: false
        cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
          description: Cursor for pagination
      type: object
      title: DataSourceOrdersResponse
      description: 'Response for orders list endpoint.


        Used by: GET /shopify/orders'
    AmazonAccountsResponseModel:
      properties:
        accounts:
          items:
            additionalProperties:
              anyOf:
              - type: string
              - type: integer
            type: object
          type: array
          title: Accounts
      type: object
      required:
      - accounts
      title: AmazonAccountsResponseModel
    DataSourceAccountResponse:
      properties:
        connected:
          type: boolean
          title: Connected
          description: Whether the platform is connected
        account:
          anyOf:
          - $ref: '#/components/schemas/DataSourceAccountInfo'
          - type: 'null'
          description: Account details if connected
      type: object
      required:
      - connected
      title: DataSourceAccountResponse
      description: 'Response for account information endpoint.


        Used by: GET /{platform}/account'
    TikTokSocialPublishSettings:
      properties:
        privacy_level:
          type: string
          title: Privacy Level
          description: TikTok privacy_level from creator_info.privacy_level_options
        allow_comment:
          type: boolean
          title: Allow Comment
          default: false
        allow_duet:
          type: boolean
          title: Allow Duet
          default: false
        allow_stitch:
          type: boolean
          title: Allow Stitch
          default: false
        commercial_content_disclosure:
          type: boolean
          title: Commercial Content Disclosure
          default: false
        brand_content_toggle:
          type: boolean
          title: Brand Content Toggle
          default: false
        brand_organic_toggle:
          type: boolean
          title: Brand Organic Toggle
          default: false
        is_aigc:
          type: boolean
          title: Is Aigc
          default: true
        video_cover_timestamp_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Video Cover Timestamp Ms
        photo_cover_index:
          anyOf:
          - type: integer
          - type: 'null'
          title: Photo Cover Index
          default: 0
        auto_add_music:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Auto Add Music
          default: true
      type: object
      required:
      - privacy_level
      title: TikTokSocialPublishSettings
    KlaviyoList:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        created:
          anyOf:
          - type: string
          - type: 'null'
          title: Created
        updated:
          anyOf:
          - type: string
          - type: 'null'
          title: Updated
        profile_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Profile Count
        list_type:
          type: string
          title: List Type
          default: list
      type: object
      required:
      - id
      - name
      title: KlaviyoList
      description: Klaviyo list/segment model.
    PostMetricsRequest:
      properties:
        post_id:
          type: string
          title: Post Id
        metrics:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Metrics
      type: object
      required:
      - post_id
      title: PostMetricsRequest
      description: Request model for getting Instagram post metrics.
    TikTokActivateAccountRequest:
      properties:
        advertiser_id:
          type: string
          title: Advertiser Id
          description: TikTok advertiser ID to activate for future launches
      type: object
      required:
      - advertiser_id
      title: TikTokActivateAccountRequest
    GoogleAdCampaignRequest:
      properties:
        account_id:
          type: string
          title: Account Id
        name:
          type: string
          title: Name
        budget_amount_micros:
          type: integer
          title: Budget Amount Micros
        start_date:
          type: string
          title: Start Date
        end_date:
          anyOf:
          - type: string
          - type: 'null'
          title: End Date
      type: object
      required:
      - account_id
      - name
      - budget_amount_micros
      - start_date
      title: GoogleAdCampaignRequest
    KlaviyoStatusResponse:
      properties:
        connected:
          type: boolean
          title: Connected
        account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Id
        account_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Name
        lists_count:
          type: integer
          title: Lists Count
          default: 0
        segments_count:
          type: integer
          title: Segments Count
          default: 0
      type: object
      required:
      - connected
      title: KlaviyoStatusResponse
      description: Response model for Klaviyo connection status.
    ShopifyInstallResolveRequestModel:
      properties:
        claim_handle:
          anyOf:
          - type: string
          - type: 'null'
          title: Claim Handle
          description: Optional legacy URL claim; when present it must match the httpOnly claim cookie
        intent_token:
          anyOf:
          - type: string
          - type: 'null'
          title: Intent Token
          description: Pomo on-ramp intent token
        chosen_organization_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Chosen Organization Id
          description: Org selected for the multi-org case
        chosen_company_profile_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Chosen Company Profile Id
          description: Existing matched profile selected to connect
        chosen_create_new:
          type: boolean
          title: Chosen Create New
          description: User opted to start a new brand profile instead of a match
          default: false
      type: object
      title: ShopifyInstallResolveRequestModel
    LinkedInPostCampaignRequest:
      properties:
        campaign_id:
          type: string
          title: Campaign Id
          description: ID of the campaign to post
        idea_number:
          type: integer
          title: Idea Number
          description: Idea number within the campaign
        author_urn:
          anyOf:
          - type: string
          - type: 'null'
          title: Author Urn
          description: Selected LinkedIn author URN
        variation:
          type: integer
          title: Variation
          description: Variation number (0 for original, 1+ for variations)
          default: 0
      type: object
      required:
      - campaign_id
      - idea_number
      title: LinkedInPostCampaignRequest
    SlackStatusResponse:
      properties:
        connected:
          type: boolean
          title: Connected
          description: Whether the platform is connected
        healthy:
          type: boolean
          title: Healthy
          description: Whether the token is healthy (passed API check)
          default: false
        health_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Health Message
          description: Health check result message
        account_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Id
          description: Platform-specific account identifier
        account_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Account Name
          description: Display name for the account
        token_expires_soon:
          type: boolean
          title: Token Expires Soon
          description: Whether token expires within buffer period
          default: false
        last_health_check:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Health Check
          description: ISO timestamp of last health check
        team_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Team Id
        team_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Team Name
        workspace_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Workspace Url
        bot_user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Bot User Id
        default_channel_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Default Channel Id
        linked_slack_user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Linked Slack User Id
        linked_slack_user_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Linked Slack User Name
        allowlist_patterns:
          items:
            type: string
          type: array
          title: Allowlist Patterns
        scopes:
          items:
            type: string
          type: array
          title: Scopes
      type: object
      required:
      - connected
      title: SlackStatusResponse
      example:
        account_id: shop_12345
        account_name: My Store
        connected: true
        health_message: Token is valid
        healthy: true
        last_health_check: '2024-01-15T10:30:00Z'
        token_expires_soon: false
    GoogleActivateAccountRequest:
      properties:
        account_id:
          type: string
          title: Account Id
          description: Google Ads account ID to activate for future launches
      type: object
      required:
      - account_id
      title: GoogleActivateAccountRequest
    AmazonAuthResponseModel:
      properties:
        auth_url:
          type: string
          title: Auth Url
      type: object
      required:
      - auth_url
      title: AmazonAuthResponseModel
    GoogleAnalyticsPropertiesResponse:
      properties:
        connected:
          type: boolean
          title: Connected
        properties:
          items:
            $ref: '#/components/schemas/GoogleAnalyticsProperty'
          type: array
          title: Properties
        selected_property_resource_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Selected Property Resource Name
      type: object
      required:
      - connected
      title: GoogleAnalyticsPropertiesResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer