{"openapi":"3.1.0","info":{"title":"Meta Ads MCP Server — REST API","description":"RESTful API for Meta (Facebook) Ads management. Proxy to the Meta Marketing API with convenience endpoints for campaigns, ad sets, ads, creatives, audiences, insights, and more.","version":"1.0.0"},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"MCP API Key — required for all /mcp and /api/* endpoints. Set via MCP_API_KEY env var on the server."},"metaToken":{"type":"apiKey","in":"header","name":"X-Meta-Token","description":"Meta/Facebook access token. Required for all /api/* and /mcp routes. Falls back to META_ACCESS_TOKEN env var if not provided."}},"schemas":{}},"paths":{"/health":{"get":{"summary":"Health check","tags":["Health"],"description":"Returns server status, tool count, available modes, and uptime.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["ok"]},"name":{"type":"string"},"version":{"type":"string"},"tools":{"type":"number"},"modes":{"type":"array","items":{"type":"string"}},"uptime":{"type":"number"}},"required":["status","name","version","tools","modes","uptime"],"additionalProperties":false}}}}}}},"/mcp":{"post":{"summary":"MCP JSON-RPC request","tags":["MCP Protocol"],"description":"Send MCP JSON-RPC requests. Used by MCP clients (Claude, etc.) to invoke tools.","responses":{"200":{"description":"Default Response"}}},"get":{"summary":"MCP SSE stream","tags":["MCP Protocol"],"description":"Server-Sent Events stream for MCP notifications. Requires mcp-session-id header.","responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Terminate MCP session","tags":["MCP Protocol"],"description":"Close an active MCP session. Requires mcp-session-id header.","responses":{"200":{"description":"Default Response"}}}},"/api/v1/meta/{*}":{"get":{"summary":"GET proxy to Meta Graph API","tags":["Proxy"],"description":"Forward any GET request to the Meta Graph API. The path after /api/v1/meta/ becomes the Graph API path. Example: /api/v1/meta/me/adaccounts?fields=id,name","parameters":[{"schema":"object","in":"query","name":"type"},{"schema":{"type":"string"},"in":"query","name":"additionalProperties"},{"schema":"Any Graph API query parameters","in":"query","name":"description"},{"schema":{"type":"string"},"in":"path","name":"*","required":true,"description":"Graph API path, e.g. \"me/adaccounts\" or \"act_123/campaigns\""},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}},"post":{"summary":"POST proxy to Meta Graph API","tags":["Proxy"],"description":"Forward any POST request to the Meta Graph API. Example: /api/v1/meta/act_123/campaigns with body { name, objective, ... }","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":{},"description":"Any Graph API POST body"}}},"description":"Any Graph API POST body"},"parameters":[{"schema":{"type":"string"},"in":"path","name":"*","required":true,"description":"Graph API path, e.g. \"me/adaccounts\" or \"act_123/campaigns\""},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}},"delete":{"summary":"DELETE proxy to Meta Graph API","tags":["Proxy"],"description":"Forward any DELETE request to the Meta Graph API. Example: /api/v1/meta/123456789","parameters":[{"schema":"object","in":"query","name":"type"},{"schema":{"type":"string"},"in":"query","name":"additionalProperties"},{"schema":"Any Graph API query parameters","in":"query","name":"description"},{"schema":{"type":"string"},"in":"path","name":"*","required":true,"description":"Graph API path, e.g. \"me/adaccounts\" or \"act_123/campaigns\""},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/accounts":{"get":{"summary":"List ad accounts","tags":["Accounts"],"description":"List all accessible ad accounts for the authenticated user.","parameters":[{"schema":{"type":"string"},"in":"query","name":"fields","required":false,"description":"Comma-separated fields to return"},{"schema":{"type":"string"},"in":"query","name":"limit","required":false,"description":"Max results per page"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/accounts/{id}":{"get":{"summary":"Get account details","tags":["Accounts"],"description":"Get detailed information about a specific ad account.","parameters":[{"schema":{"type":"string"},"in":"query","name":"fields","required":false,"description":"Comma-separated fields to return"},{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Resource ID"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/campaigns":{"get":{"summary":"List campaigns","tags":["Campaigns"],"description":"List campaigns for an ad account with optional filtering by status.","parameters":[{"schema":{"type":"string"},"in":"query","name":"account_id","required":false,"description":"Ad account ID (e.g. \"act_123456789\")"},{"schema":{"type":"string"},"in":"query","name":"fields","required":false,"description":"Comma-separated fields to return"},{"schema":{"type":"string"},"in":"query","name":"limit","required":false,"description":"Max results per page (default 25, max 100)"},{"schema":{"type":"string"},"in":"query","name":"effective_status","required":false,"description":"Filter by status, e.g. ACTIVE,PAUSED"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}},"post":{"summary":"Create campaign","tags":["Campaigns"],"description":"Create a new campaign. Created in PAUSED status by default.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"string","description":"Ad account ID"},"name":{"type":"string","description":"Campaign name"},"objective":{"type":"string","description":"Campaign objective: OUTCOME_AWARENESS, OUTCOME_ENGAGEMENT, OUTCOME_LEADS, OUTCOME_SALES, OUTCOME_TRAFFIC, OUTCOME_APP_PROMOTION"},"status":{"type":"string","description":"Initial status: ACTIVE or PAUSED (default)"},"special_ad_categories":{"type":"string","description":"JSON array of special categories, e.g. \"[]\""},"daily_budget":{"type":"string","description":"Daily budget in currency cents"},"lifetime_budget":{"type":"string","description":"Lifetime budget in currency cents"},"bid_strategy":{"type":"string","description":"Bid strategy: LOWEST_COST_WITHOUT_CAP, COST_CAP, etc."},"buying_type":{"type":"string","description":"AUCTION (default) or RESERVED"}},"required":["name","objective"],"additionalProperties":true}}}},"parameters":[{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/campaigns/{id}":{"get":{"summary":"Get campaign","tags":["Campaigns"],"description":"Get detailed information about a specific campaign.","parameters":[{"schema":{"type":"string"},"in":"query","name":"fields","required":false,"description":"Comma-separated fields to return"},{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Resource ID"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}},"put":{"summary":"Update campaign","tags":["Campaigns"],"description":"Update an existing campaign. Only provided fields are modified.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"New campaign name"},"status":{"type":"string","description":"New status: ACTIVE, PAUSED, DELETED, ARCHIVED"},"daily_budget":{"type":"string","description":"New daily budget in currency cents"},"lifetime_budget":{"type":"string","description":"New lifetime budget in currency cents"},"bid_strategy":{"type":"string","description":"New bid strategy"}},"additionalProperties":true}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Resource ID"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete campaign","tags":["Campaigns"],"description":"Delete a campaign. Sets status to DELETED. All child ad sets and ads stop delivering.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Resource ID"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/adsets":{"get":{"summary":"List ad sets","tags":["Ad Sets"],"description":"List ad sets for an ad account with optional filtering.","parameters":[{"schema":{"type":"string"},"in":"query","name":"account_id","required":false,"description":"Ad account ID"},{"schema":{"type":"string"},"in":"query","name":"fields","required":false,"description":"Comma-separated fields to return"},{"schema":{"type":"string"},"in":"query","name":"limit","required":false,"description":"Max results per page"},{"schema":{"type":"string"},"in":"query","name":"effective_status","required":false,"description":"Filter by status, e.g. ACTIVE,PAUSED"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}},"post":{"summary":"Create ad set","tags":["Ad Sets"],"description":"Create a new ad set within a campaign. Defines audience targeting, budget, schedule, and optimization.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"string","description":"Ad account ID"},"name":{"type":"string","description":"Ad set name"},"campaign_id":{"type":"string","description":"Parent campaign ID"},"targeting":{"description":"Targeting spec object (geo_locations, age_min, age_max, genders, interests, etc.)"},"billing_event":{"type":"string","description":"Billing event: IMPRESSIONS, LINK_CLICKS, etc."},"optimization_goal":{"type":"string","description":"Optimization goal: REACH, LINK_CLICKS, CONVERSIONS, etc."},"bid_amount":{"type":"number","description":"Bid amount in cents"},"daily_budget":{"type":"number","description":"Daily budget in cents"},"lifetime_budget":{"type":"number","description":"Lifetime budget in cents"},"start_time":{"type":"string","description":"Start time in ISO 8601 format"},"end_time":{"type":"string","description":"End time in ISO 8601 format"},"status":{"type":"string","description":"Initial status: ACTIVE or PAUSED"},"promoted_object":{"description":"Promoted object for conversion optimization"}},"required":["name","campaign_id","billing_event","optimization_goal"],"additionalProperties":true}}}},"parameters":[{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/adsets/{id}":{"get":{"summary":"Get ad set","tags":["Ad Sets"],"description":"Get detailed information about a specific ad set.","parameters":[{"schema":{"type":"string"},"in":"query","name":"fields","required":false,"description":"Comma-separated fields to return"},{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Resource ID"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}},"put":{"summary":"Update ad set","tags":["Ad Sets"],"description":"Update an existing ad set. Only provided fields are modified.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"New ad set name"},"targeting":{"description":"Updated targeting spec"},"billing_event":{"type":"string","description":"Updated billing event"},"optimization_goal":{"type":"string","description":"Updated optimization goal"},"bid_amount":{"type":"number","description":"Updated bid amount in cents"},"daily_budget":{"type":"number","description":"Updated daily budget in cents"},"lifetime_budget":{"type":"number","description":"Updated lifetime budget in cents"},"start_time":{"type":"string","description":"Updated start time"},"end_time":{"type":"string","description":"Updated end time"},"status":{"type":"string","description":"Updated status: ACTIVE, PAUSED, DELETED, ARCHIVED"}},"additionalProperties":true}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Resource ID"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete ad set","tags":["Ad Sets"],"description":"Delete an ad set. This is irreversible — all child ads will also be deleted.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Resource ID"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/ads":{"get":{"summary":"List ads","tags":["Ads"],"description":"List ads for an ad account with optional filtering.","parameters":[{"schema":{"type":"string"},"in":"query","name":"account_id","required":false,"description":"Ad account ID"},{"schema":{"type":"string"},"in":"query","name":"fields","required":false,"description":"Comma-separated fields to return"},{"schema":{"type":"string"},"in":"query","name":"limit","required":false,"description":"Max results per page"},{"schema":{"type":"string"},"in":"query","name":"effective_status","required":false,"description":"Filter by status, e.g. ACTIVE,PAUSED"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}},"post":{"summary":"Create ad","tags":["Ads"],"description":"Create a new ad within an ad set. Combines a creative with targeting and budget from the ad set.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"string","description":"Ad account ID"},"name":{"type":"string","description":"Ad name"},"adset_id":{"type":"string","description":"Parent ad set ID"},"creative":{"description":"Creative spec: {\"creative_id\":\"<id>\"} or inline creative object"},"status":{"type":"string","description":"Initial status: ACTIVE or PAUSED"},"tracking_specs":{"description":"Tracking specs array for conversion tracking"}},"required":["name","adset_id"],"additionalProperties":true}}}},"parameters":[{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/ads/{id}":{"get":{"summary":"Get ad","tags":["Ads"],"description":"Get detailed information about a specific ad.","parameters":[{"schema":{"type":"string"},"in":"query","name":"fields","required":false,"description":"Comma-separated fields to return"},{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Resource ID"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}},"put":{"summary":"Update ad","tags":["Ads"],"description":"Update an existing ad. Only provided fields are modified.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"New ad name"},"status":{"type":"string","description":"Updated status: ACTIVE, PAUSED, DELETED, ARCHIVED"},"creative":{"description":"Updated creative spec"},"tracking_specs":{"description":"Updated tracking specs"}},"additionalProperties":true}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Resource ID"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}},"delete":{"summary":"Delete ad","tags":["Ads"],"description":"Delete an ad. This is irreversible.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Resource ID"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/creatives":{"get":{"summary":"List creatives","tags":["Creatives"],"description":"List ad creatives for an ad account.","parameters":[{"schema":{"type":"string"},"in":"query","name":"account_id","required":false,"description":"Ad account ID"},{"schema":{"type":"string"},"in":"query","name":"fields","required":false,"description":"Comma-separated fields to return"},{"schema":{"type":"string"},"in":"query","name":"limit","required":false,"description":"Max results per page"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}},"post":{"summary":"Create creative","tags":["Creatives"],"description":"Create a new ad creative with images, videos, text, links, and call-to-action buttons.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"string","description":"Ad account ID"},"name":{"type":"string","description":"Creative name"},"object_story_spec":{"description":"Creative content: page_id + link_data/video_data/photo_data"},"asset_feed_spec":{"description":"Dynamic creative assets for A/B testing"},"url_tags":{"type":"string","description":"UTM parameters appended to all links"}},"required":["name"],"additionalProperties":true}}}},"parameters":[{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/insights/{objectId}":{"get":{"summary":"Get insights","tags":["Insights"],"description":"Get performance insights (impressions, clicks, spend, etc.) for a campaign, ad set, or ad.","parameters":[{"schema":{"type":"string"},"in":"query","name":"fields","required":false,"description":"Comma-separated metrics: impressions, clicks, spend, cpc, cpm, ctr, actions, etc."},{"schema":{"type":"string"},"in":"query","name":"date_preset","required":false,"description":"Predefined date range: last_7d, last_30d, this_month, etc."},{"schema":{"type":"string"},"in":"query","name":"time_range","required":false,"description":"JSON: {\"since\":\"YYYY-MM-DD\",\"until\":\"YYYY-MM-DD\"}"},{"schema":{"type":"string"},"in":"query","name":"breakdowns","required":false,"description":"Breakdown dimensions: age, gender, country, publisher_platform, etc."},{"schema":{"type":"string"},"in":"query","name":"level","required":false,"description":"Aggregation level: campaign, adset, ad"},{"schema":{"type":"string"},"in":"path","name":"objectId","required":true,"description":"Campaign, ad set, or ad ID"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/images":{"get":{"summary":"List images","tags":["Images"],"description":"List images in the ad account image library.","parameters":[{"schema":{"type":"string"},"in":"query","name":"account_id","required":false,"description":"Ad account ID"},{"schema":{"type":"string"},"in":"query","name":"fields","required":false,"description":"Comma-separated fields to return"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}},"post":{"summary":"Upload image","tags":["Images"],"description":"Upload an image to the ad account library via base64 bytes or public URL.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"string","description":"Ad account ID"},"bytes":{"type":"string","description":"Base64-encoded image data"},"url":{"type":"string","description":"Public URL of the image"},"name":{"type":"string","description":"Optional image name"}},"additionalProperties":true}}}},"parameters":[{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/audiences":{"get":{"summary":"List custom audiences","tags":["Audiences"],"description":"List all custom audiences for an ad account.","parameters":[{"schema":{"type":"string"},"in":"query","name":"account_id","required":false,"description":"Ad account ID"},{"schema":{"type":"string"},"in":"query","name":"fields","required":false,"description":"Comma-separated fields to return"},{"schema":{"type":"string"},"in":"query","name":"limit","required":false,"description":"Max results per page"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}},"post":{"summary":"Create custom audience","tags":["Audiences"],"description":"Create a new custom audience from customer data, website activity, app events, or engagement.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"string","description":"Ad account ID"},"name":{"type":"string","description":"Audience name"},"subtype":{"type":"string","description":"CUSTOM, WEBSITE, APP, OFFLINE, or ENGAGEMENT"},"description":{"type":"string","description":"Audience description"},"customer_file_source":{"type":"string","description":"Source: USER_PROVIDED_ONLY, PARTNER_PROVIDED_ONLY, BOTH_USER_AND_PARTNER_PROVIDED"},"rule":{"description":"Audience rules for WEBSITE/APP subtypes"}},"required":["name","subtype"],"additionalProperties":true}}}},"parameters":[{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/pixels":{"get":{"summary":"List pixels","tags":["Pixels"],"description":"List Meta Pixels for an ad account.","parameters":[{"schema":{"type":"string"},"in":"query","name":"account_id","required":false,"description":"Ad account ID"},{"schema":{"type":"string"},"in":"query","name":"fields","required":false,"description":"Comma-separated fields to return"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/conversions/{pixelId}":{"post":{"summary":"Send conversion event","tags":["Conversions"],"description":"Send server-side conversion events to the Meta Conversions API. Hash all PII with SHA-256 before sending.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"event_name":{"type":"string","description":"Event name: Purchase, Lead, ViewContent, AddToCart, etc."},"event_time":{"type":"number","description":"Unix timestamp (seconds)"},"action_source":{"type":"string","description":"Event origin: website, app, email, phone_call, etc."},"user_data":{"description":"User matching data with SHA-256 hashed PII"},"custom_data":{"description":"Event-specific data: value, currency, content_ids, etc."},"event_source_url":{"type":"string","description":"URL where the event occurred"},"event_id":{"type":"string","description":"Unique ID for deduplication"}},"required":["event_name","event_time","action_source"],"additionalProperties":true},"description":"Array of conversion events"},"test_event_code":{"type":"string","description":"Test event code from Events Manager"}},"required":["data"],"additionalProperties":true}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"pixelId","required":true,"description":"Meta Pixel ID"},{"schema":{"type":"string"},"in":"header","name":"x-meta-token","required":false,"description":"Meta/Facebook access token (required for /api/* routes)"},{"schema":{"type":"string"},"in":"header","name":"x-meta-account-id","required":false,"description":"Override default ad account ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{}},"required":["success"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"number"},"type":{"type":"string"},"subcode":{"type":"number"},"fbtrace_id":{"type":"string"}},"required":["message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}}},"servers":[{"url":"https://meta-mcp.pragmaticgrowth.com","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"security":[{"bearerAuth":[]},{"metaToken":[]}],"tags":[{"name":"Health","description":"Server health check"},{"name":"Accounts","description":"Ad account management"},{"name":"Campaigns","description":"Campaign CRUD operations"},{"name":"Ad Sets","description":"Ad set CRUD operations"},{"name":"Ads","description":"Ad CRUD operations"},{"name":"Creatives","description":"Ad creative management"},{"name":"Insights","description":"Performance reporting and analytics"},{"name":"Images","description":"Ad image management"},{"name":"Audiences","description":"Custom audience management"},{"name":"Pixels","description":"Facebook pixel management"},{"name":"Conversions","description":"Conversions API"},{"name":"Proxy","description":"Generic Meta Graph API proxy"},{"name":"MCP Protocol","description":"Model Context Protocol endpoints (for AI clients)"}]}