Introduction
The Win & Scale REST API. Read one Meta ad account's warehouse and history, launch ads paused, and with the approval grant put them live.
The Win & Scale API reads one Meta ad account's warehouse and history, launches ads paused, and, with the approval grant, puts them live. All requests go to:
https://winandscale.com/api/v1A key reaches the one workspace it was minted in, and a workspace is one Meta ad account, so there is no account id in any path.
Quick start
Mint a key in Settings → API keys, then:
curl https://winandscale.com/api/v1/workspace \
-H "Authorization: Bearer rsk_your_key"curl "https://winandscale.com/api/v1/evidence-health?window=90d" \
-H "Authorization: Bearer rsk_your_key"One payload, two surfaces
Every operation runs exactly one product tool and returns that tool's own result. Where
the MCP server serves the same tool, the operation's x-mcp-tool
names it, so the two surfaces never disagree. Adding a research source and refreshing one
are REST and dashboard only, so those two operations carry no x-mcp-tool.
- Requests are snake_case: query parameters and JSON bodies, such as
daily_budgetandnext_test_id. - Responses are the tool's payload as-is, so field names are camelCase.
- Budgets are in the account currency's major units.
50means 50.00. - No CORS headers. Keys are server-side secrets, and browser use is not supported.
Conventions
- Request ids. Every response carries
X-Request-Id. It echoes yours when you send a sane one (letters, digits,.,_,-, up to 128 characters) and is otherwise generated. Errors repeat it asrequest_id. See Errors. - Errors are
{ error: { code, message } }. Branch oncode. - Retries are safe on the creates that take an
Idempotency-Key. See Idempotency. - Rate limits are advertised on every response. See Rate limits.
The OpenAPI document is at https://winandscale.com/openapi.json.
Resource groups
| Group | What it holds |
|---|---|
reports | The warehouse (daily, as of the last sync) and the history (lifetime totals per ad). Numbers, not verdicts. |
account | The connected ad account, its sync, its quota, its strategy and the thresholds reports judge against. |
launches | Launch ads PAUSED, then activate, pause, retarget or rebuild them. Lead forms and launch presets. Everything that changes spend needs the approval grant. |
creatives | The creative library and its Values on the house taxonomy. |
taxonomy | The Dimensions and this workspace's Values. |
briefs | Briefs and strategist notes shown to the operator. |
tests | Committed Tests with frozen intent, append-only Observations and a final Conclusion, plus learnings. |
swipes | Other people's ads, saved for reference. Never launchable. |
research | Customer language in, personas and angles out, every line traceable to a quote. |
Each endpoint page has an interactive playground.
What is MCP-only
Ten tools have no REST endpoint, each for a stated reason:
- Model-backed authoring:
meta_draft_messagingandmeta_transcribe_creative. - Ranked recommendations written for a model:
meta_suggest_next,meta_get_history_winnersandmeta_get_cross_analysis. The numbers under them are inGET /api/v1/ads,/history,/evidence-health,/strategy-rollupand/performance-cube. - Live reads of a third-party system:
meta_get_breakdowns,meta_get_audience_breakdownandmeta_search_ad_library. The first two spend the account's hourly Meta quota. - The session's workspace:
meta_list_workspacesandmeta_switch_workspace. A key is pinned to its workspace, andGET /api/v1/workspaceanswers the question.
Adding or refreshing a research source is the opposite case: it is REST and dashboard only.