All systemsFlownyx — Meta ads command center
API & MCP reference
Meta Marketing API v22.0 registry + our REST routes + MCP tools for external agents.
Meta endpoints
47
Implemented
42
Via Meta MCP
2
Our REST routes
13
Architecture recommendation
Use REST for the UI and deterministic automation. Use MCP when an external agent (Claude Code, Codex) needs strategy context without reimplementing Curt + Hernan.
Layer 1 — Our REST API — sync, bulk ops, entity writes, generation. Typed, testable, same auth as the dashboard.
Layer 2 — Our MCP (POST /api/mcp) — evaluate KPIs, Curt Five Metrics, learning locks, automation plans, image compose. Value-add over raw Meta.
Layer 3 — Official Meta MCP (mcp.metamkt.com) — 29 tools for live reads. OAuth-only, Meta-blessed.
Layer 4 — Pipeboard MCP — deeper writes when official MCP lacks coverage.
MCP tools (our server)
JSON-RPC over POST /api/mcp. Auth: remote agents send Authorization: Bearer <MCP_ACCESS_TOKEN>— this is the owner's personal token and grants full service-role access, so guard it like a root credential. Without a bearer, the browser's Supabase session is used; requests with neither get JSON-RPC error -32001 unauthorized. The GET health check stays open.
Write path: queue_action only queues pause/scale/archive/duplicate proposals into the /actions approval queue — it never touches Meta. There is deliberately no approve/execute tool on this server: approval and execution are human-only, in the app.
list_ad_accounts
list_personas
list_campaigns
evaluate_kpi
evaluate_curt_metrics
evaluate_learning_lock
plan_budget_split
get_automation_plan
list_meta_api_endpoints
list_copy_structures
compose_image
list_canvas_specs
queue_action
trigger_sync
run_landing_scan
list_pending_runs
get_business_brief
list_businesses
get_kpi_summary
list_signals
list_social_connections
get_pinterest_overview
schedule_pins
suggest_pin_slots
trigger_pinterest_analytics_sync
Our REST routes
| Method | Path | Description |
|---|---|---|
| GET | /api/sync/[adAccountId] | Pull campaigns, ad sets, ads, insights; recompute KPIs. |
| POST | /api/entities/[id]/status | Pause / resume / archive on Meta + mirror. |
| POST | /api/entities/[id]/budget | Update budget; optional Hernan +20% scale. |
| POST | /api/bulk | Bulk pause RED / scale GREEN / archive. dryRun for preview. |
| POST | /api/generate | AI copy + image generation pipeline. |
| POST | /api/publish | Push generated ad to Meta (PAUSED). |
| POST | /api/agent | Claude + Meta MCP analysis chat. |
| POST | /api/mcp | Our MCP server (strategy intelligence layer). |
| GET|PATCH | /api/settings/management | Management mode: manual | hybrid | automated. |
| POST | /api/track | First-party pixel event ingestion. |
| GET | /api/cron/sync-all | Cron: sync all accounts (6h). |
| GET | /api/cron/automate | Cron: automation runner (12h). |
| GET | /api/cron/refresh-perf | Cron: refresh AI learning loop (24h). |
Meta Marketing API registry
Aligned with official reference docs. Status reflects this codebase.
| Status | Method | Path | Description | Local route |
|---|---|---|---|---|
| implemented | GET | /me/adaccounts | List ad accounts for the authenticated user. | /api/sync (connect flow) |
| implemented | GET | /act_{id}/insights | Account-level insights. Supports async jobs for long ranges. | /api/sync/[adAccountId] |
| implemented | GET | /act_{id}/campaigns | List campaigns in an ad account. | /api/sync/[adAccountId] |
| implemented | GET | /act_{id}/adsets | List ad sets in an ad account. | /api/sync/[adAccountId] |
| implemented | GET | /act_{id}/ads | List ads in an ad account. | /api/sync/[adAccountId] |
| planned | GET | /act_{id}/adcreatives | List ad creatives. | — |
| implemented | GET | /act_{id}/customaudiences | List custom audiences (Hot 7/28/90 retargeting pools). | /strategy/audiences |
| implemented | POST | /act_{id}/customaudiences | Create customer-list / website-rule / engagement / lookalike audience. | — |
| implemented | POST | /{audience_id}/users | Upload SHA-256-hashed customer-list users (session batches; DELETE removes). | — |
| implemented | POST | /{audience_id}/usersreplace | Replace-session upload — swaps the entire customer list. | — |
| implemented | POST | /{audience_id}/adaccounts | Share audience with other ad accounts (targeting / targeting_and_insights). | — |
| implemented | DELETE | /{audience_id} | Delete a custom audience. | — |
| implemented | POST | /act_{id}/adimages | Upload image (multipart or base64 bytes) → image_hash for creatives. | /api/publish |
| implemented | POST | /act_{id}/advideos | Upload video (file or file_url; simple session — chunked TBD for >1GB). | — |
| implemented | GET | /{video_id} | Poll video processing status until video_status=ready. | — |
| implemented | GET | /act_{id}/generatepreviews | Preview iframes for a creative spec or creative_id per placement format. | — |
| implemented | GET | /{ad_id}/previews | Preview iframes for an existing ad. | — |
| implemented | POST | /act_{id}/campaigns | Create campaign (OUTCOME_LEADS, OUTCOME_SALES, etc.). | — |
| implemented | POST | /{campaign_id} | Update campaign status, budget, name. | /api/entities/[id]/status, /api/entities/[id]/budget |
| implemented | GET | /{campaign_id}/insights | Campaign-level performance insights. | — |
| implemented | POST | /{campaign_id} | Archive or delete campaign (status=DELETED). | /api/entities/[id]/status |
| planned | POST | /{campaign_id}/copies | Duplicate campaign (deep_copy, rename_options, status_option). Note: duplication ships via recreate (/api/meta/duplicate — frozen copy from the local mirror), not this endpoint. | /api/meta/duplicate (recreate) |
| implemented | POST | /act_{id}/adsets | Create ad set with targeting, budget, optimization goal. | — |
| implemented | POST | /{adset_id} | Update ad set status, budget, targeting. | /api/entities/[id]/status, /api/entities/[id]/budget |
| implemented | GET | /{adset_id}/insights | Ad set insights. | — |
| implemented | POST | /act_{id}/ads | Create ad linked to creative + ad set. | /api/publish |
| implemented | POST | /{ad_id} | Update ad status or name. | /api/entities/[id]/status |
| implemented | GET | /{ad_id}/insights | Ad-level insights (CTR, hook rate, CPA). | — |
| implemented | POST | /act_{id}/adcreatives | Create ad creative (image, video, carousel, post ID). | /api/publish |
| planned | GET | /{creative_id} | Read creative spec (copy, assets, CTA). | — |
| implemented | GET | /search | Targeting search — interests, geo, locales, schools, employers, categories. | — |
| implemented | GET | /act_{id}/targetingsearch | Account-scoped unified targeting search. | — |
| implemented | GET | /act_{id}/targetingbrowse | The Ads Manager Browse tree for detailed targeting. | — |
| implemented | GET | /act_{id}/targetingsentencelines | Human-readable summary of a targeting spec. | — |
| implemented | GET | /act_{id}/reachestimate | Audience size estimate for targeting spec (-1 = unavailable). | — |
| implemented | GET | /{adset_id|act_id}/delivery_estimate | Delivery estimate for an ad set or a candidate targeting spec. | — |
| mcp | GET | /{pixel_id}/stats | Pixel event stats. | — |
| implemented | POST | /{pixel_id}/events | Conversions API server events. | /api/track (first-party) → src/lib/tracking/capi.ts forwarder |
| implemented | POST | /{entity_id}/insights | Start async insights job (report_run_id) for long ranges/breakdowns. | — |
| implemented | GET | /{report_run_id} | Poll async insights job status, then fetch /{report_run_id}/insights. | — |
| implemented | GET | /act_{id}/activities | Change history — budget/status/targeting edits (Ads Manager History parity). | — |
| mcp | GET | /{business_id}/owned_ad_accounts | List ad accounts owned by a Business Manager. | — |
| implemented | GET | /me/accounts | Pages + page tokens + linked IG business account. | — |
| implemented | GET | /{page_id}/published_posts | Organic posts for Golden Ad Process. | /strategy/golden-ad |
| implemented | GET | /{page_post_id}/insights | Post insights (impressions_unique, reactions, clicks, video views). | — |
| implemented | GET | /{ig_user_id}/media | IG business media list for post-ID ads. | — |
| implemented | GET | /{ig_media_id}/insights | IG media insights (views = unified 2024+ metric). | — |
Settings — configure management mode per account. Dashboard — bulk ops preview + execute.