Snapchat Ad Campaign Management

naftiko: "1.0.0-alpha1"

info:
  label: "Snapchat Ad Campaign Management"
  description: >-
    Unified workflow capability for programmatic management of Snapchat
    advertising campaigns. Combines the Ads API and Conversions API to
    support the full ad lifecycle: creating and managing organizations,
    ad accounts, campaigns, ad squads, ads, creatives, audience segments,
    and measuring campaign performance with server-side conversion tracking.
    Used by performance marketers, growth engineers, and ad operations teams.
  tags:
    - Advertising
    - Campaigns
    - Conversions
    - Marketing
    - Snapchat
  created: "2026-05-02"
  modified: "2026-05-02"

binds:
  - namespace: env
    keys:
      SNAPCHAT_ACCESS_TOKEN: SNAPCHAT_ACCESS_TOKEN
      SNAPCHAT_CAPI_ACCESS_TOKEN: SNAPCHAT_CAPI_ACCESS_TOKEN

capability:
  consumes:
    - import: snapchat-ads
      location: ./shared/ads-api.yaml
    - import: snapchat-capi
      location: ./shared/conversions-api.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: snapchat-campaign-api
      description: "Unified REST API for Snapchat ad campaign management and conversion tracking."
      resources:
        - path: /v1/organizations
          name: organizations
          description: "List all accessible Snapchat organizations"
          operations:
            - method: GET
              name: list-organizations
              description: "List All Organizations"
              call: "snapchat-ads.list-organizations"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/ad-accounts
          name: ad-accounts
          description: "Manage ad accounts"
          operations:
            - method: GET
              name: list-ad-accounts
              description: "List All Ad Accounts for an Organization"
              call: "snapchat-ads.list-ad-accounts"
              with:
                organization_id: "rest.organization_id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/campaigns
          name: campaigns
          description: "Manage advertising campaigns"
          operations:
            - method: GET
              name: list-campaigns
              description: "List All Campaigns for an Ad Account"
              call: "snapchat-ads.list-campaigns"
              with:
                ad_account_id: "rest.ad_account_id"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-campaign
              description: "Create a Campaign"
              call: "snapchat-ads.create-campaign"
              with:
                ad_account_id: "rest.ad_account_id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/ads
          name: ads
          description: "Manage individual ad units"
          operations:
            - method: GET
              name: list-ads
              description: "List All Ads for an Ad Account"
              call: "snapchat-ads.list-ads"
              with:
                ad_account_id: "rest.ad_account_id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/audience-segments
          name: audience-segments
          description: "Manage custom audience segments"
          operations:
            - method: GET
              name: list-audience-segments
              description: "List All Audience Segments"
              call: "snapchat-ads.list-audience-segments"
              with:
                ad_account_id: "rest.ad_account_id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/conversions/web
          name: web-conversions
          description: "Send web conversion events"
          operations:
            - method: POST
              name: send-web-conversions
              description: "Send Web Conversion Events"
              call: "snapchat-capi.send-web-conversion-events"
              with:
                pixel_id: "rest.pixel_id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/conversions/app
          name: app-conversions
          description: "Send app conversion events"
          operations:
            - method: POST
              name: send-app-conversions
              description: "Send App Conversion Events"
              call: "snapchat-capi.send-app-conversion-events"
              with:
                snap_app_id: "rest.snap_app_id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/stats/campaigns/{campaign_id}
          name: campaign-stats
          description: "Campaign performance statistics"
          operations:
            - method: GET
              name: get-campaign-stats
              description: "Get Campaign Statistics"
              call: "snapchat-ads.get-campaign-stats"
              with:
                ad_account_id: "rest.ad_account_id"
                campaign_id: "rest.campaign_id"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: snapchat-campaign-mcp
      transport: http
      description: "MCP server for AI-assisted Snapchat ad campaign management and conversion optimization."
      tools:
        - name: list-organizations
          description: "List all Snapchat organizations accessible to the authenticated user"
          hints:
            readOnly: true
            openWorld: false
          call: "snapchat-ads.list-organizations"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-ad-accounts
          description: "List all ad accounts for a given Snapchat organization"
          hints:
            readOnly: true
            openWorld: false
          call: "snapchat-ads.list-ad-accounts"
          with:
            organization_id: "tools.organization_id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-campaigns
          description: "List all advertising campaigns for a Snapchat ad account"
          hints:
            readOnly: true
            openWorld: false
          call: "snapchat-ads.list-campaigns"
          with:
            ad_account_id: "tools.ad_account_id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: create-campaign
          description: "Create a new Snapchat advertising campaign"
          hints:
            readOnly: false
            destructive: false
          call: "snapchat-ads.create-campaign"
          with:
            ad_account_id: "tools.ad_account_id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-ads
          description: "List all ads for a Snapchat ad account"
          hints:
            readOnly: true
            openWorld: false
          call: "snapchat-ads.list-ads"
          with:
            ad_account_id: "tools.ad_account_id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: list-audience-segments
          description: "List all custom audience segments for targeting in a Snapchat ad account"
          hints:
            readOnly: true
            openWorld: false
          call: "snapchat-ads.list-audience-segments"
          with:
            ad_account_id: "tools.ad_account_id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: get-campaign-stats
          description: "Get performance statistics for a Snapchat campaign"
          hints:
            readOnly: true
            openWorld: false
          call: "snapchat-ads.get-campaign-stats"
          with:
            ad_account_id: "tools.ad_account_id"
            campaign_id: "tools.campaign_id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: send-web-conversion-events
          description: "Send web conversion events to Snapchat for campaign measurement via server-side CAPI"
          hints:
            readOnly: false
            destructive: false
          call: "snapchat-capi.send-web-conversion-events"
          with:
            pixel_id: "tools.pixel_id"
          outputParameters:
            - type: object
              mapping: "$."

        - name: send-app-conversion-events
          description: "Send app conversion events to Snapchat for campaign measurement via server-side CAPI"
          hints:
            readOnly: false
            destructive: false
          call: "snapchat-capi.send-app-conversion-events"
          with:
            snap_app_id: "tools.snap_app_id"
          outputParameters:
            - type: object
              mapping: "$."