naftiko: 1.0.0-alpha2
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-06'
binds:
- namespace: env
  keys:
    SNAPCHAT_ACCESS_TOKEN: SNAPCHAT_ACCESS_TOKEN
    SNAPCHAT_CAPI_ACCESS_TOKEN: SNAPCHAT_CAPI_ACCESS_TOKEN
capability:
  consumes:
  - type: http
    namespace: snapchat-ads
    baseUri: https://adsapi.snapchat.com/v1
    description: Snapchat Ads API for programmatic campaign management
    authentication:
      type: bearer
      token: '{{SNAPCHAT_ACCESS_TOKEN}}'
    resources:
    - name: organizations
      path: /me/organizations
      description: Retrieve organizations the user has access to
      operations:
      - name: list-organizations
        method: GET
        description: List All Organizations
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: organization
      path: /organizations/{organization_id}
      description: Manage a specific organization
      operations:
      - name: get-organization
        method: GET
        description: Get a Specific Organization
        inputParameters:
        - name: organization_id
          in: path
          type: string
          required: true
          description: Organization ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: ad-accounts
      path: /organizations/{organization_id}/adaccounts
      description: Manage ad accounts for an organization
      operations:
      - name: list-ad-accounts
        method: GET
        description: List All Ad Accounts for an Organization
        inputParameters:
        - name: organization_id
          in: path
          type: string
          required: true
          description: Organization ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: create-ad-account
        method: POST
        description: Create an Ad Account
        inputParameters:
        - name: organization_id
          in: path
          type: string
          required: true
          description: Organization ID
        body:
          type: json
          data:
            adaccounts: '{{tools.adaccounts}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: campaigns
      path: /adaccounts/{ad_account_id}/campaigns
      description: Manage campaigns for an ad account
      operations:
      - name: list-campaigns
        method: GET
        description: List All Campaigns for an Ad Account
        inputParameters:
        - name: ad_account_id
          in: path
          type: string
          required: true
          description: Ad Account ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: create-campaign
        method: POST
        description: Create a Campaign
        inputParameters:
        - name: ad_account_id
          in: path
          type: string
          required: true
          description: Ad Account ID
        body:
          type: json
          data:
            campaigns: '{{tools.campaigns}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: ad-squads
      path: /adaccounts/{ad_account_id}/adsquads
      description: Manage ad squads for an ad account
      operations:
      - name: create-ad-squad
        method: POST
        description: Create an Ad Squad
        inputParameters:
        - name: ad_account_id
          in: path
          type: string
          required: true
          description: Ad Account ID
        body:
          type: json
          data:
            adsquads: '{{tools.adsquads}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: ads
      path: /adaccounts/{ad_account_id}/ads
      description: Manage ads for an ad account
      operations:
      - name: list-ads
        method: GET
        description: List All Ads for an Ad Account
        inputParameters:
        - name: ad_account_id
          in: path
          type: string
          required: true
          description: Ad Account ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: audience-segments
      path: /adaccounts/{ad_account_id}/segments
      description: Manage audience segments for ad targeting
      operations:
      - name: list-audience-segments
        method: GET
        description: List All Audience Segments for an Ad Account
        inputParameters:
        - name: ad_account_id
          in: path
          type: string
          required: true
          description: Ad Account ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: stats-campaign
      path: /adaccounts/{ad_account_id}/campaigns/{campaign_id}/stats
      description: Campaign performance statistics
      operations:
      - name: get-campaign-stats
        method: GET
        description: Get Campaign Statistics
        inputParameters:
        - name: ad_account_id
          in: path
          type: string
          required: true
          description: Ad Account ID
        - name: campaign_id
          in: path
          type: string
          required: true
          description: Campaign ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  - type: http
    namespace: snapchat-capi
    baseUri: https://tr.snapchat.com/v3
    description: Snapchat Conversions API for server-to-server event tracking
    authentication:
      type: apikey
      key: access_token
      value: '{{SNAPCHAT_CAPI_ACCESS_TOKEN}}'
      placement: query
    resources:
    - name: pixel-events
      path: /{pixel_id}/events
      description: Send web conversion events via Pixel ID
      operations:
      - name: send-web-conversion-events
        method: POST
        description: Send Web Conversion Events
        inputParameters:
        - name: pixel_id
          in: path
          type: string
          required: true
          description: Snap Pixel ID
        body:
          type: json
          data:
            data: '{{tools.events}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: app-events
      path: /{snap_app_id}/events
      description: Send app conversion events via Snap App ID
      operations:
      - name: send-app-conversion-events
        method: POST
        description: Send App Conversion Events
        inputParameters:
        - name: snap_app_id
          in: path
          type: string
          required: true
          description: Snap App ID
        body:
          type: json
          data:
            data: '{{tools.events}}'
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  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: $.