{
  "info": {
    "name": "adsmcp",
    "description": "Postman collection for the adsmcp Meta Ads API playground. Set the `baseUrl` and `apiKey` collection variables. The `apiKey` is shown on the API Docs page in the running app — copy it from there. Every request below sends the key as the `X-API-Key` header via the collection-level auth.\n\nBefore running any /api/meta/* request, you must connect a Meta account once via the dashboard.\n\nWhenever an endpoint in adsmcp is added, removed, or changed, this collection MUST be updated in the same commit alongside `instructions.md` and `frontend/api-spec.js`.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    { "key": "baseUrl", "value": "http://localhost:4100" },
    { "key": "apiKey", "value": "amk_paste_your_api_key_here" },
    { "key": "adAccountId", "value": "act_123456789" },
    { "key": "pageId", "value": "987654321" },
    { "key": "pixelId", "value": "111111111" },
    { "key": "campaignId", "value": "" },
    { "key": "adsetId", "value": "" },
    { "key": "adId", "value": "" }
  ],
  "auth": {
    "type": "apikey",
    "apikey": [
      { "key": "key", "value": "X-API-Key", "type": "string" },
      { "key": "value", "value": "{{apiKey}}", "type": "string" },
      { "key": "in", "value": "header", "type": "string" }
    ]
  },
  "item": [
    {
      "name": "Meta — Read",
      "item": [
        {
          "name": "Get accounts",
          "request": {
            "method": "GET",
            "header": [],
            "url": { "raw": "{{baseUrl}}/api/meta/accounts", "host": ["{{baseUrl}}"], "path": ["api", "meta", "accounts"] }
          }
        },
        {
          "name": "Get pages",
          "request": {
            "method": "GET",
            "header": [],
            "url": { "raw": "{{baseUrl}}/api/meta/pages", "host": ["{{baseUrl}}"], "path": ["api", "meta", "pages"] }
          }
        },
        {
          "name": "Get pixels",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/meta/pixels?adAccountId={{adAccountId}}",
              "host": ["{{baseUrl}}"],
              "path": ["api", "meta", "pixels"],
              "query": [{ "key": "adAccountId", "value": "{{adAccountId}}" }]
            }
          }
        },
        {
          "name": "Get campaigns (by ad account)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/meta/campaigns?adAccountId={{adAccountId}}&keyword=&includeStats=true&datePreset=last_30d",
              "host": ["{{baseUrl}}"],
              "path": ["api", "meta", "campaigns"],
              "query": [
                { "key": "adAccountId", "value": "{{adAccountId}}" },
                { "key": "keyword", "value": "" },
                { "key": "includeStats", "value": "true" },
                { "key": "datePreset", "value": "last_30d" }
              ]
            }
          }
        },
        {
          "name": "Get campaigns (by ids)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/meta/campaigns?campaignIds={{campaignId}}&includeStats=true&since=2026-03-01&until=2026-04-01",
              "host": ["{{baseUrl}}"],
              "path": ["api", "meta", "campaigns"],
              "query": [
                { "key": "campaignIds", "value": "{{campaignId}}" },
                { "key": "includeStats", "value": "true" },
                { "key": "since", "value": "2026-03-01" },
                { "key": "until", "value": "2026-04-01" }
              ]
            }
          }
        },
        {
          "name": "Get ad sets (by campaign)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/meta/adsets?campaignIds={{campaignId}}&keyword=&includeStats=true&datePreset=last_30d",
              "host": ["{{baseUrl}}"],
              "path": ["api", "meta", "adsets"],
              "query": [
                { "key": "campaignIds", "value": "{{campaignId}}" },
                { "key": "keyword", "value": "" },
                { "key": "includeStats", "value": "true" },
                { "key": "datePreset", "value": "last_30d" }
              ]
            }
          }
        },
        {
          "name": "Get ad sets (by ids)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/meta/adsets?adsetIds={{adsetId}}",
              "host": ["{{baseUrl}}"],
              "path": ["api", "meta", "adsets"],
              "query": [{ "key": "adsetIds", "value": "{{adsetId}}" }]
            }
          }
        },
        {
          "name": "Get ads (by adset)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/meta/ads?adsetIds={{adsetId}}&includeStats=true&datePreset=last_30d",
              "host": ["{{baseUrl}}"],
              "path": ["api", "meta", "ads"],
              "query": [
                { "key": "adsetIds", "value": "{{adsetId}}" },
                { "key": "includeStats", "value": "true" },
                { "key": "datePreset", "value": "last_30d" }
              ]
            }
          }
        },
        {
          "name": "Get ads (by campaign)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/meta/ads?campaignIds={{campaignId}}",
              "host": ["{{baseUrl}}"],
              "path": ["api", "meta", "ads"],
              "query": [{ "key": "campaignIds", "value": "{{campaignId}}" }]
            }
          }
        },
        {
          "name": "Get ads (by ids)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/meta/ads?adIds={{adId}}",
              "host": ["{{baseUrl}}"],
              "path": ["api", "meta", "ads"],
              "query": [{ "key": "adIds", "value": "{{adId}}" }]
            }
          }
        },
        {
          "name": "Get insights (raw)",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/api/meta/insights?objectId={{campaignId}}&level=campaign&datePreset=last_30d",
              "host": ["{{baseUrl}}"],
              "path": ["api", "meta", "insights"],
              "query": [
                { "key": "objectId", "value": "{{campaignId}}" },
                { "key": "level", "value": "campaign" },
                { "key": "datePreset", "value": "last_30d" }
              ]
            }
          }
        }
      ]
    },
    {
      "name": "Meta — Write",
      "item": [
        {
          "name": "Create campaign",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"adAccountId\": \"{{adAccountId}}\",\n  \"name\": \"Spring 2026 - Lead Gen\",\n  \"objective\": \"OUTCOME_LEADS\",\n  \"status\": \"PAUSED\",\n  \"dailyBudget\": 25.00,\n  \"bidStrategy\": \"LOWEST_COST_WITHOUT_CAP\",\n  \"specialAdCategories\": []\n}"
            },
            "url": { "raw": "{{baseUrl}}/api/meta/campaigns", "host": ["{{baseUrl}}"], "path": ["api", "meta", "campaigns"] }
          }
        },
        {
          "name": "Create ad set",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"adAccountId\": \"{{adAccountId}}\",\n  \"name\": \"AdSet 1 - US Lookalike\",\n  \"campaignId\": \"{{campaignId}}\",\n  \"status\": \"PAUSED\",\n  \"dailyBudget\": 25.00,\n  \"billingEvent\": \"IMPRESSIONS\",\n  \"optimizationGoal\": \"OFFSITE_CONVERSIONS\",\n  \"promotedObject\": {\n    \"pixelId\": \"{{pixelId}}\",\n    \"customEventType\": \"LEAD\"\n  },\n  \"targeting\": {\n    \"geo_locations\": { \"countries\": [\"US\"] },\n    \"age_min\": 25,\n    \"age_max\": 65,\n    \"publisher_platforms\": [\"facebook\", \"instagram\"]\n  }\n}"
            },
            "url": { "raw": "{{baseUrl}}/api/meta/adsets", "host": ["{{baseUrl}}"], "path": ["api", "meta", "adsets"] }
          }
        },
        {
          "name": "Create ad (JSON with mediaUrl)",
          "request": {
            "method": "POST",
            "header": [{ "key": "Content-Type", "value": "application/json" }],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"adAccountId\": \"{{adAccountId}}\",\n  \"adsetId\": \"{{adsetId}}\",\n  \"pageId\": \"{{pageId}}\",\n  \"name\": \"Ad - Variant A\",\n  \"link\": \"https://example.com/landing\",\n  \"message\": \"Body / primary text shown above the creative\",\n  \"headline\": \"Catchy headline\",\n  \"description\": \"Optional link description\",\n  \"mediaUrl\": \"https://cdn.example.com/creatives/banner.jpg\",\n  \"callToAction\": { \"type\": \"LEARN_MORE\" },\n  \"status\": \"PAUSED\"\n}"
            },
            "url": { "raw": "{{baseUrl}}/api/meta/ads", "host": ["{{baseUrl}}"], "path": ["api", "meta", "ads"] },
            "description": "Server fetches mediaUrl and uploads the bytes to Meta. For video URLs it tries Meta's file_url shortcut first, then falls back to download+upload. For video creatives the auto-generated Meta thumbnail is fetched and applied — never supply your own."
          }
        },
        {
          "name": "Create ad (multipart with media file)",
          "request": {
            "method": "POST",
            "header": [],
            "body": {
              "mode": "formdata",
              "formdata": [
                { "key": "adAccountId", "value": "{{adAccountId}}", "type": "text" },
                { "key": "adsetId", "value": "{{adsetId}}", "type": "text" },
                { "key": "pageId", "value": "{{pageId}}", "type": "text" },
                { "key": "name", "value": "Ad - Variant A", "type": "text" },
                { "key": "link", "value": "https://example.com/landing", "type": "text" },
                { "key": "message", "value": "Body / primary text shown above the creative", "type": "text" },
                { "key": "headline", "value": "Catchy headline", "type": "text" },
                { "key": "description", "value": "Optional link description", "type": "text" },
                { "key": "callToAction", "value": "{\"type\":\"LEARN_MORE\"}", "type": "text" },
                { "key": "status", "value": "PAUSED", "type": "text" },
                { "key": "media", "type": "file", "src": [], "description": "Image (jpg/png/gif/webp) or video (mp4/mov/m4v/webm). Required unless creativeId is set. Thumbnails for video creatives are auto-fetched from Meta — never provide one." }
              ]
            },
            "url": { "raw": "{{baseUrl}}/api/meta/ads", "host": ["{{baseUrl}}"], "path": ["api", "meta", "ads"] }
          }
        }
      ]
    }
  ]
}