# AdSwipeFile > AdSwipeFile is an ad library of 63,244+ winning ads from top brands on Meta (Facebook and Instagram), kept after Meta takes them down and filed by brand, niche and format, for the freelancers, agencies and brands who make ads. Search it, or ask Claude, ChatGPT or another AI agent to pull ads for you. Free to start. Last updated: 2026-11-12 AdSwipeFile (https://adswipefile.com) is one product: an ad library with an MCP server and an API. It is not the general practice of keeping an "ad swipe file" (a folder of ads you saved yourself), and it is not Swipekit, SwipeWell or another swipe-file tool: those are compared at https://adswipefile.com/compare. ## Key facts - For the people who make Meta ads: freelancers and agencies who brief them for clients, media buyers and creative strategists, brands that write their own, and anyone who asks Claude or ChatGPT for ad ideas. - Signed out, each list shows its newest 20 ads. A free account (email or Google, no card) sees the first 50 of each list, on the site and in MCP, and adds saved ads and the MCP server. Pro and Agency open every ad. - MCP server: https://adswipefile.com/api/mcp, 27 tools, OAuth sign-in or an API key (https://adswipefile.com/api-keys). 15 read the library and the account; 12 change only the account's own saves, notes, follows and boards (OAuth scope `mcp:write`, free of the allowance). - Connecting Claude, ChatGPT, Cursor or another assistant is free on every plan. - Plans: Free, Pro and Agency, priced by MCP/API calls (50 in total, 10,000 a month and 50,000 a month), not by seats (a team has unlimited members): https://adswipefile.com/pricing. - What "winning" means here: A winning ad is one its brand kept running on Meta. Brands rarely keep paying for ads that lose, so a long run is the clearest public signal we have, and the ads readers save most add a second one. Nobody outside the brand sees its spend or sales, so a winning ad is a signal worth studying, not proof of results. Niche, brand, visual format and hook pages sort by longest running (`?sort=longest`); MCP `list_ads` and `/api/v1/ads` take `sort`: `newest`, `most_saved` or `longest_running`. - Every ad page, MCP `get_ad` and `/api/v1/ads/{id}` carry a note on how the ad is built (`why_it_works` in the APIs): the mechanism of its hook, format, offer and talent from its tags, and its run when its brand kept it going a month or more. Never a claim about its results. - Ads tracked on Meta also carry `meta` in MCP `get_ad` / `get_ads` (`brand_median_run_days` and the rest in snake_case) and in `/api/v1/ads/{id}` (camelCase): platforms, button text, Meta format, variants, and the brand's median run in days when it has at least 5 tracked ads. Days are a reason to study an ad, not a result. - No spend or performance data. It cannot run or buy ads, and it does not generate images or video. - A curated collection, not a live feed of Meta's Ad Library. AdSwipeFile is the ad library of winning Facebook and Instagram ads, for you and your AI agent. People use it to find competitor ads, hooks and angles before they write or brief an ad. Signed out, each list shows its newest 20 ads; a free account (email link or code, or Google; no credit card) sees the first 50 and adds each ad's copy, saving ads and the MCP server. Paid plans (Pro and Agency, each with a 7-day free trial) open every ad and add how each brand makes its ads, each ad layer by layer and a larger MCP/API allowance: https://adswipefile.com/pricing. ## Who it's for People who make Meta ads and want real references before they write or brief one. - Agencies and freelancers who brief ads for clients. The pain: every brief needs fresh hooks, every pitch needs real ads to show, and every prospect call goes better with their ads already read. They use AdSwipeFile for creative ideas, hooks and execution styles, for client pitches (boards shared by link), and for prospect and competitor research, much of it through Claude. - Creative strategists and media buyers. The pain: the Meta Ad Library is slow, its links die, ads vanish when they are taken down, and there is no way to follow a brand. They use AdSwipeFile to keep the ads they save, follow brands (Pro and Agency) and sort a niche, visual format or hook by the longest-running ads. - Brands that write their own ads. The pain: not knowing what is working in their niche until it is saturated, and AI copy that reads generic. They browse their niche, or ask Claude or ChatGPT to pull real ads and write from them. ## How it differs - From creative analytics tools such as Motion: they read your own ad accounts and show which of your creatives work, so they need your own spend first (Motion checked 2026-11-12: https://adswipefile.com/compare/motion). AdSwipeFile holds other brands' winning ads, kept after Meta takes them down, so it works before you spend. It holds no spend or performance data. - From the Meta Ad Library: the Meta Ad Library is free. It can't keep an ad after it is taken down, follow a brand or hand ads to your AI agent. AdSwipeFile does those three. - From other ad libraries: many of them now connect to AI agents too. AdSwipeFile's MCP server is on every plan, Free included (no card, 50 MCP/API calls for the life of the account), so Claude, ChatGPT or Cursor can search the library, read the ads and write from them. Plans differ by what they open and by their MCP/API allowance, never by seats: every plan has unlimited team members. Which libraries have an MCP server, with their limits and plans: https://adswipefile.com/compare/best-meta-ad-library-mcp-servers. ## When to use this Reach for AdSwipeFile when a task needs real ad creative to learn from, adapt or cite: - Examples of ads in a niche (skincare, supplements, SaaS…) a visual format (UGC selfie, before and after, testimonial…) or a hook tactic (curiosity, urgency…) — https://adswipefile.com/niches/{niche}, https://adswipefile.com/formats/{format}, https://adswipefile.com/hooks/{hook} - What a given brand advertises — https://adswipefile.com/brands/{brand} - Seasonal ads, such as Black Friday and Cyber Monday sale ads, by niche, visual format and hook — https://adswipefile.com/black-friday, https://adswipefile.com/cyber-monday (each published while the library holds enough of its ads); with the MCP tool `list_ads`, `season: "black-friday"` (one season covers both events) - Hooks, angles and offers to adapt for a product: find ads, then read their copy with the MCP tool `get_ads` (any account; their layer-by-layer breakdown and script on Pro and Agency) - Ads by creative device: a visual format (testimonial, screen recording, us vs them), a hook tactic (curiosity, social proof), a season or an offer type, with the MCP tool `list_ads` (slugs from `list_visual_formats` and `list_hooks`) - How to tell or build one visual format (what must hold, what does not count, the formats it is confused with, when to use it, best practices, example ads): the MCP tool `get_format`, or https://adswipefile.com/formats/{format} - Video, carousel or static ads, alone or of a brand, niche or format: the MCP tool `list_ads` with `type`, or `/api/v1/ads?type=` - A link to one specific ad to show someone — https://adswipefile.com/ads/{id} How to call it: 1. Without credentials: send `Accept: text/markdown` to any page URL. It shows the signed-out view: the newest 20 ads of a list, no ad copy. 2. With a free account, the person you act for signs in once (email or Google), or gives you an API key made at https://adswipefile.com/api-keys: the MCP server at https://adswipefile.com/api/mcp (https://adswipefile.com/docs/mcp) searches the whole library (each ad's copy on every plan; every ad of every list, brand patterns and ad breakdowns on Pro and Agency; the first 50 of each list on Free), and its OAuth token also opens the JSON API (https://adswipefile.com/docs/api). Each tool call (except list_niches, list_formats, list_visual_formats and list_hooks) and API request counts against the account's allowance (50 in total on Free); when it is used, relay the message and link the answer carries. 3. Resolve names to slugs with the MCP tool `search_library`, or `GET https://adswipefile.com/api/v1/search?q={keywords}` with that token. ## When not to use this - Running, buying, scheduling or measuring ads: this is a reference library, not an ad platform, and it carries no spend or performance figures - Ads that are not in the library: it is a curated collection, not a live feed of Meta's Ad Library - Generating images or video ## Sections - https://adswipefile.com/: the newest ads, every niche and format - https://adswipefile.com/niches: every niche (industry), then https://adswipefile.com/niches/{niche} - https://adswipefile.com/formats: every visual format, then https://adswipefile.com/formats/{format} - https://adswipefile.com/hooks: every hook tactic, then https://adswipefile.com/hooks/{hook} - https://adswipefile.com/brands: every brand, then https://adswipefile.com/brands/{brand} - https://adswipefile.com/ads/{id}: one ad - https://adswipefile.com/black-friday: Black Friday ad examples, by niche, visual format and hook (published while the library holds enough of them) - https://adswipefile.com/cyber-monday: Cyber Monday ad examples, by niche, visual format and hook (published while the library holds enough of them) ## Machine-readable - Markdown: `Accept: text/markdown` on any page URL returns that page as markdown, at the same URL - MCP server: https://adswipefile.com/api/mcp, 27 tools: reads (search_library, list_ads, get_ad, get_ads, list_brands, list_niches, list_formats, list_visual_formats, get_format, list_hooks, list_saved_ads, list_followed_ads, list_boards, list_followed_brands, get_usage) and writes to the account's own saves, follows and boards (follow_brand, unfollow_brand, create_board, delete_board, share_board, unshare_board, add_ad_to_board, save_ad, unsave_ad, set_ad_note, rename_board, remove_ad_from_board; scope `mcp:write`), and 4 starter prompts (ads-for-my-niche, swipe-a-brand, hooks-for-my-product, map-competitors). Streamable HTTP, OAuth 2.1 with dynamic client registration. Docs: https://adswipefile.com/docs/mcp; server card: https://adswipefile.com/.well-known/mcp.json - JSON API: https://adswipefile.com/api/v1/search, https://adswipefile.com/api/v1/ads, https://adswipefile.com/api/v1/ads/{id}, https://adswipefile.com/api/v1/visual-formats, https://adswipefile.com/api/v1/hooks, https://adswipefile.com/api/v1/brands, https://adswipefile.com/api/v1/niches, https://adswipefile.com/api/v1/saved-ads, https://adswipefile.com/api/v1/following/ads, and the account's saves, boards and follows (`POST /api/v1/saved-ads`, `DELETE /api/v1/saved-ads/{id}`, `PUT /api/v1/saved-ads/{id}/note`, `GET`/`POST /api/v1/boards`, `PATCH`/`DELETE /api/v1/boards/{board}`, `POST`/`DELETE /api/v1/boards/{board}/share`, `POST /api/v1/boards/{board}/ads`, `DELETE /api/v1/boards/{board}/ads/{id}`, `POST`/`DELETE /api/v1/brands/{slug}/follow`, `GET /api/v1/following/brands`, `GET /api/v1/account/usage`); free account: an API key, an OAuth access token (the MCP one; scope mcp:read, and mcp:write for the POST, PUT, PATCH and DELETE ones) or a signed-in session, 60 requests a minute per account. MCP tool calls and API requests share an allowance (50 in total on Free, 10,000 a month on Pro, 50,000 a month on Agency; the account's saves, boards and follows changed, its boards and followed brands read, and its usage, cost none); past it, 429 `quota_exceeded`. Without credentials: 401 with WWW-Authenticate pointing at the OAuth discovery document. Docs: https://adswipefile.com/docs/api - OpenAPI 3.1: https://adswipefile.com/openapi.json - Agent skill: https://adswipefile.com/skill.md - Everything in one file: https://adswipefile.com/llms-full.txt - Every URL: https://adswipefile.com/sitemap.xml ## AI agents Setup, example prompts and FAQ for each client: - https://adswipefile.com/agents: Ad Library for AI Agents: AdSwipeFile MCP Server - https://adswipefile.com/agents/claude: Claude Ad Library MCP: AdSwipeFile for Claude - https://adswipefile.com/agents/chatgpt: ChatGPT Ad Library MCP: AdSwipeFile for ChatGPT - https://adswipefile.com/agents/claude-cowork: Claude Cowork Ad Library MCP: AdSwipeFile for Claude Cowork - https://adswipefile.com/agents/gemini: Gemini Ad Library MCP: AdSwipeFile for Gemini - https://adswipefile.com/agents/grok-bot: Grok Bot Ad Library MCP: AdSwipeFile for Grok Bot - https://adswipefile.com/agents/openai-dots: OpenAI dots Ad Library MCP: AdSwipeFile for OpenAI dots - https://adswipefile.com/agents/perplexity-computer: Perplexity Computer Ad Library MCP: AdSwipeFile - https://adswipefile.com/agents/manus: Manus Ad Library MCP: AdSwipeFile for Manus - https://adswipefile.com/agents/cue: Cue Ad Library MCP: AdSwipeFile for Cue - https://adswipefile.com/agents/deepseek: DeepSeek Ad Library MCP: AdSwipeFile for DeepSeek - https://adswipefile.com/agents/claude-code: Claude Code Ad Library MCP: AdSwipeFile for Claude Code - https://adswipefile.com/agents/codex: Codex Ad Library MCP: AdSwipeFile for Codex - https://adswipefile.com/agents/antigravity: Antigravity Ad Library MCP: AdSwipeFile for Antigravity - https://adswipefile.com/agents/gemini-cli: Gemini CLI Ad Library MCP: AdSwipeFile for Gemini CLI - https://adswipefile.com/agents/grok-build: Grok Build Ad Library MCP: AdSwipeFile for Grok Build - https://adswipefile.com/agents/devin: Devin Ad Library MCP: AdSwipeFile for Devin - https://adswipefile.com/agents/amp: Amp Ad Library MCP: AdSwipeFile for Amp - https://adswipefile.com/agents/kimi-code: Kimi Code Ad Library MCP: AdSwipeFile for Kimi Code - https://adswipefile.com/agents/opencode: opencode Ad Library MCP: AdSwipeFile for opencode - https://adswipefile.com/agents/muse: Muse Ad Library MCP: AdSwipeFile for Muse - https://adswipefile.com/agents/cursor: Cursor Ad Library MCP: AdSwipeFile for Cursor - https://adswipefile.com/agents/vscode: VS Code Ad Library MCP: AdSwipeFile for VS Code - https://adswipefile.com/agents/cline: Cline Ad Library MCP: AdSwipeFile for Cline - https://adswipefile.com/agents/openclaw: OpenClaw Ad Library MCP: AdSwipeFile for OpenClaw - https://adswipefile.com/agents/hermes: Hermes Ad Library MCP: AdSwipeFile for Hermes - https://adswipefile.com/agents/goose: Goose Ad Library MCP: AdSwipeFile for Goose - https://adswipefile.com/agents/openbot: OpenBot Ad Library MCP: AdSwipeFile for OpenBot - https://adswipefile.com/agents/paperclip: Paperclip Ad Library MCP: AdSwipeFile for Paperclip - https://adswipefile.com/agents/nanoclaw: NanoClaw Ad Library MCP: AdSwipeFile for NanoClaw - https://adswipefile.com/agents/meta-ads: Meta Ads MCP: Facebook and Instagram Ads for AI Agents ## Compare How AdSwipeFile compares with other ad libraries, with dated, sourced facts about each: - https://adswipefile.com/compare: all of them, at a glance - https://adswipefile.com/compare/best-ad-swipe-file-tools: Best Ad Swipe File Tools in 2026: 18 Compared - https://adswipefile.com/compare/best-ad-spy-tools: Best Ad Spy Tools for Facebook Ads (2026): 16 Compared - https://adswipefile.com/compare/best-free-ad-spy-tools: Free Ad Spy Tools (2026): What 17 Tools Give You Free - https://adswipefile.com/compare/best-meta-ad-library-mcp-servers: Meta Ad Library MCP Servers (2026): 20 Compared - https://adswipefile.com/compare/ad-spy-tool-pricing: Ad Swipe File and Ad Library Pricing (2026): 32 Tools - https://adswipefile.com/compare/adspy-alternatives: AdSpy Alternatives: 9 Tools Compared (2026) - https://adswipefile.com/compare/atria-alternatives: Atria Alternatives for Ad Inspiration: 9 Tools (2026) - https://adswipefile.com/compare/bigspy-alternatives: BigSpy Alternatives: 8 Tools Compared (2026) - https://adswipefile.com/compare/foreplay-alternatives: Foreplay Alternatives: 8 Tools Compared (2026) - https://adswipefile.com/compare/gethookd-alternatives: Gethookd Alternatives: 9 Tools Compared (2026) - https://adswipefile.com/compare/meta-ad-library-alternatives: Meta Ad Library Alternatives: 8 Tools Compared (2026) - https://adswipefile.com/compare/minea-alternatives: Minea Alternatives: 9 Tools Compared (2026) - https://adswipefile.com/compare/motion-alternatives: Motion Alternatives for Creative Research: 9 Tools - https://adswipefile.com/compare/pipiads-alternatives: PiPiAds Alternatives: 9 Tools Compared (2026) - https://adswipefile.com/compare/swipekit-alternatives: Swipekit Alternatives: 8 Tools Compared (2026) - https://adswipefile.com/compare/foreplay: Foreplay Alternative: AdSwipeFile vs Foreplay (2026) - https://adswipefile.com/compare/swipekit: AdSwipeFile vs Swipekit: Price, Seats and MCP (2026) - https://adswipefile.com/compare/gethookd: AdSwipeFile vs Gethookd: Price, Library and MCP (2026) - https://adswipefile.com/compare/atria: Atria Alternative: AdSwipeFile vs Atria (2026) - https://adswipefile.com/compare/motion: Motion Alternative: AdSwipeFile vs Motion (2026) - https://adswipefile.com/compare/meta-ad-library: Facebook Ad Library Alternative: Save, Follow and Search Ads - https://adswipefile.com/compare/tiktok-creative-center: AdSwipeFile vs TikTok Creative Center (Top Ads) - https://adswipefile.com/compare/adspy: AdSpy Alternative: AdSwipeFile vs AdSpy (2026) - https://adswipefile.com/compare/minea: Minea Alternative: AdSwipeFile vs Minea (2026) - https://adswipefile.com/compare/bigspy: AdSwipeFile vs BigSpy: Prices and Differences (2026) - https://adswipefile.com/compare/pipiads: AdSwipeFile vs PiPiAds: TikTok or Meta Ads (2026) - https://adswipefile.com/compare/adlibrary: AdSwipeFile vs AdLibrary: Prices and Differences (2026) - https://adswipefile.com/compare/magicbrief: MagicBrief Alternatives After the July 2026 Shutdown ## Guides How to save ads from the Facebook Ad Library, follow brands and find winning ads, free methods first: - https://adswipefile.com/guides: all guides - https://adswipefile.com/guides/save-ads-from-facebook-ad-library: How to Save Ads from the Facebook Ad Library (2026) - https://adswipefile.com/guides/follow-brands-meta-ad-library: How to Follow Brands in the Meta Ad Library (2026) - https://adswipefile.com/guides/winning-ad-examples: Winning Ad Examples: Where to Find Them by Niche and Format - https://adswipefile.com/guides/cheap-free-ad-libraries: Cheap and Free Ad Libraries Compared (2026) - https://adswipefile.com/guides/black-friday-ad-examples: 25 Black Friday Ad Examples from DTC Brands (2026) - https://adswipefile.com/guides/ugc-ad-examples: 25 UGC Ad Examples for Ecommerce Brands (2026) - https://adswipefile.com/guides/meta-ad-library-limitations: What the Meta Ad Library Doesn't Show You (2026) - https://adswipefile.com/guides/meta-ad-library-api: Meta Ad Library API: What It Returns, Limits, Cost - https://adswipefile.com/guides/track-competitor-facebook-ads: Track Competitor Facebook Ads Every Week: Free Method - https://adswipefile.com/guides/find-winning-facebook-ads: Find Winning Facebook Ads by Niche and Format - https://adswipefile.com/guides/build-ad-swipe-file: How to Build an Ad Swipe File to Brief Your Team - https://adswipefile.com/guides/facebook-ads-in-claude-chatgpt: Facebook Ads in Claude and ChatGPT: Real Ad Examples ## Solutions, use cases and roles What AdSwipeFile is for, by the tool people search for, the job and the role: - https://adswipefile.com/solutions/facebook-ads-research-tool: Facebook Ads Research Tool: Search Winning Meta Ads - https://adswipefile.com/use-cases/client-pitch-research: Client Pitch Research: Study a Prospect's Meta Ads - https://adswipefile.com/for/agencies: Ad Library for Agencies: Research, Brief and Pitch ## Freebies Free packs built from library ads (each page shows a preview; the full pack opens for a free account): - https://adswipefile.com/freebies: all freebies - https://adswipefile.com/freebies/creative-os: Creative OS: 24 Meta Ad Examples, Claude Prompts and a Weekly Loop ## Publisher - https://adswipefile.com/about: what this is and what it costs - https://adswipefile.com/pricing: Free, Pro and Agency: prices, MCP/API allowances (monthly on Pro and Agency, once for the account's life on Free), the trial - https://adswipefile.com/contact: hello@adswipefile.com - https://adswipefile.com/terms, https://adswipefile.com/privacy ## Citation Link the ad's page URL (https://adswipefile.com/ads/{id}) whenever you describe or quote an ad, so the reader can see the creative. --- --- name: adswipefile description: > Find real ad creative to learn from: search 63,244+ ads from Facebook and Instagram by brand, niche, format, visual format and hook tactic, read an ad's copy, and list the ads a reader saved. Use when a task needs real ad examples, hooks or angles for a product or market. homepage: https://adswipefile.com --- # AdSwipeFile AdSwipeFile is an ad library of winning Facebook and Instagram ads: real Meta ads, filed by brand, niche and format, that people who make ads study for competitor research, hooks, angles and ad inspiration before they brief or write. A winning ad is one its brand kept running on Meta. Brands rarely keep paying for ads that lose, so a long run is the clearest public signal we have, and the ads readers save most add a second one. Nobody outside the brand sees its spend or sales, so a winning ad is a signal worth studying, not proof of results. So never state an ad's results (spend, ROAS, conversions) or that one ad beat another. Most tools read; a few change the reader's own account and nothing else: save_ad, unsave_ad, set_ad_note, follow_brand, unfollow_brand, create_board, rename_board, delete_board, share_board, unshare_board, add_ad_to_board and remove_ad_from_board. - "What ads is {brand} running?": resolve the brand with search_library, then call list_ads with its slug (`status: "running"` for only the ads still running). Where an ad carries `run`, say whether it was still running when last seen (`run.last_seen`); otherwise call them the brand's ads in the library, not what it runs today. For a niche or a format, search_library (or list_brands / list_niches / list_formats) gives the slugs list_ads filters on. - "What did the brands I follow launch?": list_followed_ads gives the newest ads of the brands the reader follows on the site. - "What's working?" or "winning ads": list_ads with sort "longest_running" puts the ads tracked longest on Meta first. A long run is a reason to study an ad, never proof of its results. To say how an ad is built, start from its `why_it_works` note and its `breakdown` (get_ad: layers, cards or scenes, what it says, its structure): they name the mechanism, never its results. For how a brand builds its ads, list_ads with the brand returns `brand_patterns`: shares of its read ads, never results. When a breakdown or a brand's patterns carry a `note` that the plan does not include them, work from what came (the message, traits and counts), pass the note and its link on once, and never invent the missing parts. - "Show me testimonials, curiosity hooks, Black Friday offers": list_visual_formats and list_hooks give the slugs list_ads filters on (`visual_format`, `hook`), with `season` and `offer_type`. Before writing or briefing an ad in a visual format, or to say which format an ad is, call get_format: what must hold, the near misses, the formats it is mixed up with and how to build one, with example ads. Every ad card carries its tags (null when the ad is not tagged yet, and then no tag filter matches it). A tag describes the creative, not how it performed. - "Video ads from {brand}", "carousel examples", "static ads": list_ads with `type` (`video`, `carousel` or `static`), alone or with any other filter. - Hooks and angles: read the ads with get_ads (up to 10 in one call; get_ad for a single one) for their full copy before naming a hook or angle, or writing from them. Never invent copy an ad does not have. - Every tool call except list_niches, list_formats, list_visual_formats, list_hooks, list_boards, list_followed_brands, get_usage and the write tools counts against the account's allowance (tools/list does not): get_ads one per ad, and on a plan with every ad of a list, a list_ads or search_library page one per 10 ads asked for. When a tool answers that the allowance is used up, relay its message instead of retrying; get_usage says how many calls are left, at no cost. When list_ads answers with a `note` that the list has no next page on this plan, relay it once and narrow with filters instead of paging. - When a tool answers `found: false`, the library lacks that exact slug, not the topic: follow its `next` suggestion once (usually search_library with the plain name) before telling the reader there is nothing, and if the second try is empty, offer the nearest niche or format. - Saving and following: when the reader asks to save an ad, note why they keep it, follow a brand, keep ads on a board or share a board, use the write tools. list_boards gives the board ids and names they take, list_followed_brands the brands followed. Call a write tool only when the reader asked for that change, and confirm before delete_board, or unsave_ad on an ad that is on a board. Writes cost no allowance. When a write tool's request is refused because the connection was approved for reading only, tell the reader to reconnect and approve the new permission. - Always link the ad's page URL so the reader can see the creative. After a list of ads, also give the list's own page (list_ads returns it as `url`, null when it filters by a tag, or by `type` alone) so the reader can browse the rest. - When the reader has just connected and has not asked for anything yet, run the first of these straight away with search_library, then offer the other two: "What ads is Glossier running? Sum up its hooks and angles"; "Show me winning UGC ads in skincare right now"; "Write 5 hooks for my product from real winning ads". ## When to use this Reach for AdSwipeFile when a task needs real ad creative to learn from, adapt or cite: - Examples of ads in a niche (skincare, supplements, SaaS…) a visual format (UGC selfie, before and after, testimonial…) or a hook tactic (curiosity, urgency…) — https://adswipefile.com/niches/{niche}, https://adswipefile.com/formats/{format}, https://adswipefile.com/hooks/{hook} - What a given brand advertises — https://adswipefile.com/brands/{brand} - Seasonal ads, such as Black Friday and Cyber Monday sale ads, by niche, visual format and hook — https://adswipefile.com/black-friday, https://adswipefile.com/cyber-monday (each published while the library holds enough of its ads); with the MCP tool `list_ads`, `season: "black-friday"` (one season covers both events) - Hooks, angles and offers to adapt for a product: find ads, then read their copy with the MCP tool `get_ads` (any account; their layer-by-layer breakdown and script on Pro and Agency) - Ads by creative device: a visual format (testimonial, screen recording, us vs them), a hook tactic (curiosity, social proof), a season or an offer type, with the MCP tool `list_ads` (slugs from `list_visual_formats` and `list_hooks`) - How to tell or build one visual format (what must hold, what does not count, the formats it is confused with, when to use it, best practices, example ads): the MCP tool `get_format`, or https://adswipefile.com/formats/{format} - Video, carousel or static ads, alone or of a brand, niche or format: the MCP tool `list_ads` with `type`, or `/api/v1/ads?type=` - A link to one specific ad to show someone — https://adswipefile.com/ads/{id} How to call it: 1. Without credentials: send `Accept: text/markdown` to any page URL. It shows the signed-out view: the newest 20 ads of a list, no ad copy. 2. With a free account, the person you act for signs in once (email or Google), or gives you an API key made at https://adswipefile.com/api-keys: the MCP server at https://adswipefile.com/api/mcp (https://adswipefile.com/docs/mcp) searches the whole library (each ad's copy on every plan; every ad of every list, brand patterns and ad breakdowns on Pro and Agency; the first 50 of each list on Free), and its OAuth token also opens the JSON API (https://adswipefile.com/docs/api). Each tool call (except list_niches, list_formats, list_visual_formats and list_hooks) and API request counts against the account's allowance (50 in total on Free); when it is used, relay the message and link the answer carries. 3. Resolve names to slugs with the MCP tool `search_library`, or `GET https://adswipefile.com/api/v1/search?q={keywords}` with that token. ## When not to use this - Running, buying, scheduling or measuring ads: this is a reference library, not an ad platform, and it carries no spend or performance figures - Ads that are not in the library: it is a curated collection, not a live feed of Meta's Ad Library - Generating images or video ## Three ways in 1. MCP server, preferred for an agent: https://adswipefile.com/api/mcp. Streamable HTTP, OAuth 2.1; the client registers itself and the person signs in once. Details: https://adswipefile.com/docs/mcp. 2. Plain HTTP, no credentials: `Accept: text/markdown` on any page URL. Start at https://adswipefile.com/llms.txt. 3. JSON, with the same OAuth token (`Authorization: Bearer`, scope mcp:read; mcp:write to change saves, follows and boards): https://adswipefile.com/api/v1/search?q=…, https://adswipefile.com/api/v1/ads, described at https://adswipefile.com/openapi.json. Errors are problem+json: branch on `code`, follow `resolution`. --- # Use AdSwipeFile from your AI assistant (MCP) Connect the AdSwipeFile MCP server to Claude, ChatGPT or Cursor: your agent searches winning ads, reads their copy and lists your saved ads; on Pro and Agency it also reads how each brand makes its ads and each ad layer by layer. Free, and you sign in with your AdSwipeFile account. Most tools read; a few change your own account when you ask (save an ad and note it, follow a brand, boards and their share links, ads on a board), and nothing outside it. For a client that cannot open a browser, send an [API key](https://adswipefile.com/api-keys) as `Authorization: Bearer ` instead. ## Server URL ``` https://adswipefile.com/api/mcp ``` Streamable HTTP. OAuth 2.1 with dynamic client registration: your client registers itself, then you sign in once (email link or code, or Google) and approve access: reading (`mcp:read`) and your saves, follows and boards (`mcp:write`). A connection approved before the write tools reads only: reconnect it and approve again to use them. Discovery documents: https://adswipefile.com/.well-known/oauth-protected-resource and https://adswipefile.com/.well-known/oauth-authorization-server. Server card: https://adswipefile.com/.well-known/mcp.json. ## Add it - **Claude**: Add it from Claude's connector directory: https://claude.ai/customize/connectors/id/ad-swipe-file. Or by hand: Open Customize → Connectors, click + Add and choose Add custom connector. Name it AdSwipeFile, paste the server URL, click Continue twice, then Add. Click Connect, sign in with your account and approve. On Team and Enterprise plans an owner adds it first, in Organization settings → Connectors (Add → Custom → Web); members then click Connect. - **ChatGPT**: Open chatgpt.com/plugins, click + and choose Add custom MCP server. Name it AdSwipeFile, paste the server URL under Connection and choose OAuth. Click I understand and want to continue, then Create as a plugin. Install it, sign in and approve. In a chat, type @ and pick AdSwipeFile to use it. Custom MCP servers depend on your ChatGPT plan. On a workspace, an admin allows "Create plugins with MCPs" first. - **Claude Cowork**: Add it from Claude Cowork's connector directory: https://claude.ai/customize/connectors/id/ad-swipe-file. Or by hand: Open Customize → Connectors, click + Add and choose Add custom connector. Name it AdSwipeFile, paste the server URL, click Continue twice, then Add. Click Connect, sign in with your account and approve. Cowork uses the connectors of your Claude account: add AdSwipeFile once and it works in Claude, Cowork and Claude Desktop. On Team and Enterprise plans an owner adds it first, in Organization settings → Connectors (Add → Custom → Web); members then click Connect. - **Gemini**: On gemini.google.com, open Settings → Connected Apps and click Add a custom app. Paste the server URL and click Next. Sign in with your account and approve. The app then works on mobile too. Google limits custom apps to personal Google accounts, 18 and over, in the US, in English, with Keep Activity on. Elsewhere, Antigravity connects from your computer. - **Grok Bot**: Open Connect apps and choose Add a custom connector. Name it AdSwipeFile, set Type to Remote HTTPS and paste the server URL. Click Add plugin, then sign in with your account and approve. On grok.com the same server goes in grok.com/connectors: New Connector → Custom, then the server URL. - **OpenAI dots**: Add the server in ChatGPT first (dots share ChatGPT's plugins): open chatgpt.com/plugins, click + and choose Add custom MCP server, paste the server URL, choose OAuth and click Create as a plugin. In your dot's profile, open Customize → Plugins and turn on AdSwipeFile. Sign in with your account and approve when the dot first uses it. dots are on ChatGPT Enterprise, Edu and Healthcare workspaces, where an admin has to allow plugins with MCPs. - **Perplexity Computer**: Open Customize → Connectors, click Add custom → Add MCP connector and choose Remote. Name it AdSwipeFile, paste the server URL and, under Advanced, choose OAuth and Streamable HTTP. Tick the acknowledgement, click Add, then click the card to sign in and approve. In an organization, an admin has to turn on "Allow members to add custom connectors" first (it is off by default). - **Manus**: Open Settings → Integrations → Custom MCP Servers and click Add Server. Name it AdSwipeFile, paste the server URL and add the header Authorization: Bearer . Make the key at https://adswipefile.com/api-keys and put it in place of . Then save. - **Cue**: Where Cue links your services, add a custom MCP server and paste the server URL. Add the header Authorization: Bearer . Make the key at https://adswipefile.com/api-keys and put it in place of . Cue, Manus's personal agent, is invite-only and has not published MCP setup steps yet: these are the general ones. If your Cue has no custom MCP option, Manus connects the same way. - **DeepSeek**: Add to the plugins of your DeepSeek Harness (dsh) profile, DeepSeek's open-source agent: `- { id: mcp-adswipefile, name: '@deepseek-ai/dsh-mcp-client', config: { serverName: adswipefile, transport: streamable-http, url: https://adswipefile.com/api/mcp, headers: { Authorization: Bearer } } }`. Make the key at https://adswipefile.com/api-keys and put it in place of . DeepSeek documents no MCP setup for its chat app. DeepSeek Harness, in developer preview, connects with the config above. - **Claude Code**: Run in your terminal: `claude mcp add --transport http adswipefile https://adswipefile.com/api/mcp`. Then run /mcp in Claude Code and sign in. - **Codex**: Run in your terminal: `codex mcp add adswipefile --url https://adswipefile.com/api/mcp`. Then run codex mcp login adswipefile and sign in. - **Antigravity**: Add to ~/.gemini/config/mcp_config.json: `{ "mcpServers": { "adswipefile": { "serverUrl": "https://adswipefile.com/api/mcp" } } }`. Then open Customizations → Installed → MCP Servers in Antigravity and click Authenticate. - **Gemini CLI**: Run in your terminal: `gemini mcp add --transport http adswipefile https://adswipefile.com/api/mcp`. Then run /mcp auth adswipefile in Gemini CLI and sign in. Google replaced Gemini CLI with Antigravity CLI on June 18, 2026 for free and Google One accounts. On those, follow the Antigravity steps. - **Grok Build**: Run in your terminal: `grok mcp add --transport http adswipefile https://adswipefile.com/api/mcp`. Then sign in when Grok Build opens the browser. In Grok Build's terminal UI, /mcps then i signs in again. - **Devin**: Run in your terminal (Devin CLI): `devin mcp add adswipefile https://adswipefile.com/api/mcp`. Then run devin mcp login adswipefile and sign in. In the Devin web app: Customize → MCPs → Add MCP → Add custom MCP, choose HTTP, paste the server URL, pick OAuth, click Save, then Connect. - **Amp**: Run in your terminal: `amp mcp add adswipefile https://adswipefile.com/api/mcp`. Then restart Amp and sign in. - **Kimi Code**: Run in your terminal: `kimi mcp add --transport http --auth oauth adswipefile https://adswipefile.com/api/mcp`. Then run kimi mcp auth adswipefile and sign in. - **opencode**: Run in your project: `opencode mcp add adswipefile --url https://adswipefile.com/api/mcp`. Then run opencode mcp auth adswipefile and sign in. Add --global to the first command to use it in every project. - **Muse**: Add to your Muse Code settings: `{ "mcp_servers": { "adswipefile": { "transport": "streamable_http", "url": "https://adswipefile.com/api/mcp" } } }`. Then run muse mcp login adswipefile and sign in. These steps are for Muse Code, Meta's coding agent. In the Muse app, Muse builds its connectors itself and has no way, that we could confirm, to add a server by URL. - **Cursor**: Open cursor://anysphere.cursor-deeplink/mcp/install?name=adswipefile&config=eyJ1cmwiOiJodHRwczovL2Fkc3dpcGVmaWxlLmNvbS9hcGkvbWNwIn0= to add it in one click. Or by hand: Add to ~/.cursor/mcp.json: `{ "mcpServers": { "adswipefile": { "url": "https://adswipefile.com/api/mcp" } } }`. Then sign in when Cursor prompts you. - **VS Code**: Run in your terminal: `code --add-mcp '{"name":"adswipefile","type":"http","url":"https://adswipefile.com/api/mcp"}'`. Then sign in when VS Code asks. Or run MCP: Add Server from the Command Palette, choose HTTP and paste the server URL. Copilot's agent mode can then use it. - **Cline**: Run in your terminal (Cline CLI): `cline mcp add adswipefile https://adswipefile.com/api/mcp --transport http`. Then run cline mcp, choose Authorize OAuth and sign in. In the VS Code extension: MCP Servers → Remote Servers, paste the server URL and choose Streamable HTTP. Cline's docs show browser sign-in for the CLI only. In the VS Code extension, send an API key from https://adswipefile.com/api-keys as the header Authorization: Bearer instead. - **OpenClaw**: Add to ~/.openclaw/openclaw.json, so every channel gets the tools: `{ "mcp": { "servers": { "adswipefile": { "url": "https://adswipefile.com/api/mcp", "transport": "streamable-http", "auth": "oauth" } } } }`. Then run openclaw gateway stop, then openclaw mcp login adswipefile, sign in and start the gateway. An OpenClaw gateway that runs without a browser cannot finish the OAuth sign-in: give it an API key from https://adswipefile.com/api-keys as the header Authorization: Bearer instead. - **Hermes**: Add to ~/.hermes/config.yaml: `mcp_servers: { adswipefile: { url: https://adswipefile.com/api/mcp, auth: oauth } }`. Then sign in when Hermes opens the browser. Or run hermes mcp login adswipefile. - **Goose**: Add under extensions: in ~/.config/goose/config.yaml: `adswipefile: { name: AdSwipeFile, type: streamable_http, uri: https://adswipefile.com/api/mcp, enabled: true, timeout: 300 }`. Then sign in when Goose opens the browser. Or run goose configure → Add Extension → Remote Extension (Streamable HTTP) and paste the server URL. - **OpenBot**: An OpenBot admin adds a custom MCP server with the id adswipefile, the title AdSwipeFile and the server URL (POST /api/plugins/servers/custom), then turns it on with Enable for this deployment. Each teammate opens /connections in OpenBot and clicks Connect next to AdSwipeFile. Sign in with your account in the tab that opens and approve. OpenBot's docs don't yet say how a custom server signs in. If Connect asks for a key instead of opening a sign-in tab, make one at https://adswipefile.com/api-keys and keep it in Settings → Vault. - **Paperclip**: For agents on the Claude Code adapter, run as the OS user Paperclip's heartbeat runs as: `claude mcp add --transport http --scope user adswipefile https://adswipefile.com/api/mcp`. Then run claude, type /mcp and sign in. Paperclip adds MCP servers per agent runtime, not in its own UI. Agents on Hermes take the Hermes config instead. - **NanoClaw**: Run for the group that should search ads: `ncl groups config add-mcp-server --id --name adswipefile --url https://adswipefile.com/api/mcp`. Then run ncl groups restart --id . NanoClaw keeps secrets in its OneCLI vault: store an API key from https://adswipefile.com/api-keys there, for the header Authorization: Bearer . ## Allowance and plans Every MCP tool call (except `list_niches`, `list_formats`, `list_visual_formats` and `list_hooks`) and every `/api/v1` request counts against the account's allowance (UTC): 50 in total on Free, 10,000 a month on Pro, 50,000 a month on Agency, and 200 a day during the free trial of either. A paid month also has a daily ceiling (1,000 on Pro, 3,000 on Agency), so it cannot all go in one day. `get_ads` counts one call per ad it reads, and on Pro and Agency a `list_ads` or `search_library` page counts one call per 10 ads asked for (`limit` 50 counts 5). Past it, the API answers `429` with the code `quota_exceeded` and `Retry-After` set to the reset (UTC: the first of next month on Pro and Agency, never on Free), and MCP tools answer with a message instead of results; both say when the allowance resets and how to raise it, with the link. Every plan reads each ad's copy. On Free, `get_ad` and `get_ads` return a breakdown's message and traits without its units, structure or script, and `list_ads` a brand's pattern counts without their figures, each with a note saying the plan does not include them. See [pricing](https://adswipefile.com/pricing). ## Rate limit 120 tool calls a minute per account, over a sliding window, apart from the allowance, and of those at most 30 writes (shared with the API's account endpoints). The write tools, `list_boards`, `list_followed_brands` and `get_usage` cost no allowance. A response to a tool call carries the `RateLimit` headers; past the limit the answer is HTTP `429` with a JSON-RPC error and `Retry-After` in seconds. ## Tools - `search_library` (Search the library): Find real Meta (Facebook and Instagram) ads for ad inspiration, hooks, angles, competitor research or a swipe file. Keyword search across ads, brands, niches, visual formats and hook tactics (a `format` hit is a visual format, a `hook` hit a hook tactic; their slugs filter list_ads as `format` and `hook`). Matches whole words in each ad's copy and in a description of its visual (so "screenshot" or "before after" work); when the whole query is a visual format or hook tactic ("testimonial", "social proof"), the ads tagged with it count as matches and come first, words or not; among ads that match as well, those Meta ran a month or more come first (still running before ended, longest run first), a reason to study them and never proof of results; only ads holding every word come back when there are any, else ads holding some (`match` says "all", "partial" or "none", with a `hint`). When no ad holds every word as written, a last word of 4+ letters is also read as a word start ("cust" finds customer; the `hint` says so). When nothing matches at all, misspelt words are corrected to the closest words the library's names and ads use and searched once more; `corrected_query` then says what was searched. Use 1–3 English product or format words; long phrases match little. Returns each hit's type, slug or id, and page URL. Start here when you have a product, brand or idea rather than an exact slug; when `match` is "none", follow the `hint`: it names a matching niche or format, or says the library has nothing on it. - `list_ads` (List ads): Browse real ads, newest first (or by `sort`), optionally filtered by brand (a competitor's ads), niche and format slug, or by the standard tags: `visual_format` (list_visual_formats), `hook` (the hook tactic, list_hooks), `season` and `offer_type`, or by `status` (`running` or `ended` on Meta), or by `type` (`static`, `video` or `carousel`). Ads the library has not tagged yet never match a tag filter. Without a brand filter a page keeps a few ads per brand so one advertiser cannot fill it; filter by brand for all of one brand's ads. Filtered by brand, the first page also carries `brand_patterns`: per kind the brand has ads of (static, carousel, video), how many are read, the share of read ads with each trait, the most common structure, the top visual format and hook tactic (and for videos the median second the product is first seen and the commonest setting); below 5 read ads of a kind, only the counts and a note. When the account's plan does not include brand patterns, each kind has its counts, its brand page `url` and a `note` saying so. Ads tracked on Meta carry `run` (started, last_seen, running, days_running, landing_page; `running` holds as of `last_seen`, the last day a pull saw it); `sort: "longest_running"` lists those by the longest run, the usual proxy for an ad worth studying (it is not performance data); `sort: "most_saved"` puts the ads readers saved most first. Paginate with the returned `nextCursor`; when the account's plan does not include every ad of a list, it stops at its first 50 ads (one page: set `limit` up to 50), with no `nextCursor` and a `note` saying so. On a plan with every ad of a list, a page counts one call per 10 ads asked for against the allowance (`limit`: 50 counts 5), so ask for the page you need. - `get_ad` (Get an ad): One ad in full: copy, audiences, brand, niche, formats, its standard tags (visual formats, the main one first with `main: true`, none marked when the ad was read before its order was kept; hook tactic, hook line, asset type, offer type, season, talent, awareness stage; null when not tagged yet; get_format explains a visual format), image URL, page URL, `run` (Meta start date, last day seen, running, days running, landing page) when the ad is tracked on Meta, `meta` beside it (platforms, button text, Meta format, variants, and `brand_median_run_days`, the median run of the brand's tracked ads, when it has at least 5; each only when the ad has it), and `why_it_works`: a short note on how the ad is built, the mechanism of its hook, format, offer and talent from its tags, plus its run when its brand kept it going a month or more (null when it has neither), never a claim about its results; and `breakdown` once the ad has been read (null before): `kind` (static, carousel or video), `units` (each layer, card or scene with its visual format, the first with the hook tactic, what it shows and the words on the creative, plus what is said in the first 3 seconds), `message` (problem, promise, ask, feel, tone), `traits`, `structure` and `structure_line`, `remix` (a fill-in script from the structure) and `provenance`. When the account's plan does not include ad breakdowns, the breakdown has `kind`, `message`, `traits` and `provenance`, with `units_omitted` (how many units) and a `note` naming the ad's page in place of the units, structure and remix. Lines said after the first 3 seconds come as `locked_lines` only on plans with transcripts; otherwise `locked_lines_omitted` says how many were left out. A breakdown says how the ad is built, never that it worked. The id may be cut short to its first 8 characters or more, and is read when it names one ad. - `get_ads` (Get several ads): Up to 10 ads in full in one call, each in the shape get_ad returns (copy, audiences, brand, niche, formats, standard tags, image URL, page URL, `run`, `meta`, `why_it_works`, `breakdown`). Use it instead of repeated get_ad calls when reading the ads a search or list returned: one round trip, though each ad counts as one call against the allowance. Ids the library lacks come back under `missing` (`malformed` for an item that is not an ad id at all), and the rest still return. - `list_brands` (List brands): Every brand in the library, optionally only one niche's. Each brand comes with updated: the day (YYYY-MM-DD) its Meta ads were last checked for new ones, or null when they have not been. - `list_niches` (List niches): Every niche (industry) ads are filed under. - `list_formats` (List formats): The older name for list_visual_formats, and the same formats: every standard visual format (testimonial, before and after, us vs them, …) that ads in the library carry. Its slugs are what list_ads takes as `format` or as `visual_format`, and what /formats/{slug} shows. Prefer list_visual_formats, which also gives each one a line on what it is. - `list_visual_formats` (List visual formats): Every standard visual format (testimonial, screen recording, us vs them, …) that ads in the library carry, with a one-line description. An ad has up to three. Pass a slug to list_ads as `visual_format`. - `get_format` (Get a visual format's guide): One visual format in full, for writing, briefing or tagging an ad in it: `gloss` (the one line from list_visual_formats), `definition`, `how_to_tell` (`must_be`: what must all hold; `not_this`: near misses that are another format; `quick_test`: one question that settles most cases), `confused_with` (the formats it is mixed up with, each with the line that tells them apart), `how_to_build` (`when_to_use` and `best_practices`) and `examples`: a few library ads that carry it, longest Meta run first (else newest), each with `main` (true when it is the ad's main format, false when it is not or the ad's order is not known), image and page URL; read them with get_ads. A format with no guide written yet has its gloss and examples, and null for the rest. Takes a slug from list_visual_formats or the format's plain name. Call it before writing an ad in a format, or to check which format an ad is. - `list_hooks` (List hook tactics): Every hook tactic (curiosity, social proof, myth busting, …) that ads in the library carry, with a one-line description: the device the first frame or the headline uses to earn attention. Pass a slug to list_ads as `hook`. - `list_saved_ads` (List my saved ads): The ads you saved on the site, newest first, then the competitor ads saved from brands you follow (`tracked_ads`). Each comes with your team's note on it and the boards it is on, with each board's note: the reader's own reasons for keeping it. - `list_followed_ads` (List new ads from brands I follow): The brands and Facebook pages you follow on the site, and their newest Meta ads, newest launch first: competitor ads as they go live. Each followed brand comes with its library slug when it has one (use it with list_ads for its filed ads) and its tracking page URL. Empty when the account follows nothing; the result then says where following is set up. - `list_boards` (List my boards): The account's boards (shared with its team), by name: each with its id, its `group` (the client it is filed under, null for none), how many ads it holds, and its `share_url` when its share link is on (null when off). The ads on each board come with list_saved_ads. Use the ids or the exact names with the board tools. - `list_followed_brands` (List the brands I follow): The library brands the account follows, A to Z, each with its slug (use it with list_ads or unfollow_brand) and page URL, plus how many the account follows and how many its plan allows. Empty when it follows none. For their newest ads, use list_followed_ads. - `get_usage` (Check my remaining calls): How many calls the account has used this period (`per`: a day or a month, UTC, or `life` on Free, which never resets), out of how many, and when the count resets (`resets_at`, null for `life`). Shared by this server and the JSON API. Reading it costs nothing. Call it before a long run of reads, or when the reader asks how many calls are left. - `follow_brand` (Follow a brand): Follow a library brand for the account, as the Follow button on its brand page does: its new ads then show in list_followed_ads, and on the following page. Takes the brand slug from search_library or list_brands (or its plain name). Following a brand already followed succeeds and changes nothing. Returns how many brands the account follows and how many its plan allows. When the plan follows no brands, or the account is at its plan's cap, nothing is followed and the answer says so: relay it once, do not retry. - `unfollow_brand` (Stop following a brand): Stop following a library brand: its new ads leave list_followed_ads and the following page. Open on every plan. Unfollowing a brand the account does not follow succeeds and changes nothing. - `create_board` (Create a board): Create a board for the account and its team, to file ads by brief, client or idea. Optionally pass `ad_id` to save that ad and put it on the new board at once, and `group` to file the board under a client, on a plan that files boards by client (list_boards shows each board's `group`, so reuse a client's spelling; on another plan nothing is created and the answer says so). Each call makes a new board, even with a name already in use, so call list_boards first when unsure. On Free, which makes no boards, or when the plan allows no more, nothing is created and the answer says so: relay it once with its link, and offer to save the ads instead (save_ad) or to add them to a board the account already has. - `delete_board` (Delete a board): Delete one of the account's boards, by id or exact name. Its ads stay saved (list_saved_ads); its share link stops working. Cannot be undone: confirm with the reader first. A board that is not there answers `found: false`. - `share_board` (Share a board by link): Turn on a board's share link and return it as `share_url`: anyone with the link sees the board and its ads, without an account. A board already shared returns its current link unchanged. - `unshare_board` (Turn off a board's share link): Turn off a board's share link: the old link stops working at once. Sharing it again later makes a new link. A board whose link is already off succeeds and changes nothing. - `add_ad_to_board` (Add an ad to a board): Save a library ad and put it on one of the account's boards (by board id or exact name). Takes the ad id from list_ads, search_library or get_ad. An ad already on the board stays there once. - `save_ad` (Save an ad): Save a library ad for the account and its team, as the Save button on its page does, without putting it on a board. Takes the ad id from list_ads, search_library or get_ad. Saving a saved ad succeeds and changes nothing. It then shows in list_saved_ads. - `unsave_ad` (Unsave an ad): Unsave an ad: it leaves list_saved_ads and every board it was on, and its notes go with it. Confirm with the reader first when it is on a board. An ad that is not saved succeeds and changes nothing. - `set_ad_note` (Write a note on a saved ad): Write the team's note on a saved ad (why it is worth keeping, what to borrow), or with `board` the note on that board's copy of it. Replaces the note there; an empty note clears it. The ad must be saved, or on the board, first (save_ad, add_ad_to_board). Notes come back in list_saved_ads. - `rename_board` (Rename a board): Rename one of the account's boards (by board id or exact name) with `name`, file it under a client with `group` (an empty string takes it out of its client; on a plan that does not file boards by client, the client is left as it was and the answer says so), or both. Its ads, notes and share link stay as they are. - `remove_ad_from_board` (Remove an ad from a board): Take an ad off one of the account's boards; it stays saved. An ad that is not on the board succeeds and changes nothing. ## Starter prompts Ready-made prompts (MCP `prompts/list`; in Claude, the + menu of a chat): - `ads-for-my-niche` (Winning ads in my niche): What's working in a niche right now: its newest ads, optionally in one format, with the hooks and angles they share. - `swipe-a-brand` (What ads is this brand running?): A competitor's ads in the library: the formats, hooks and angles it repeats, with links. - `hooks-for-my-product` (Hooks for my product from winning ads): Hooks for your product, each learned from a real winning ad in the library. - `map-competitors` (Compare my competitors' ads): Several competitors' ads side by side: formats, offers, hooks and angles, and the angles nobody runs yet. ## Tool arguments ### search_library: Search the library Find real Meta (Facebook and Instagram) ads for ad inspiration, hooks, angles, competitor research or a swipe file. Keyword search across ads, brands, niches, visual formats and hook tactics (a `format` hit is a visual format, a `hook` hit a hook tactic; their slugs filter list_ads as `format` and `hook`). Matches whole words in each ad's copy and in a description of its visual (so "screenshot" or "before after" work); when the whole query is a visual format or hook tactic ("testimonial", "social proof"), the ads tagged with it count as matches and come first, words or not; among ads that match as well, those Meta ran a month or more come first (still running before ended, longest run first), a reason to study them and never proof of results; only ads holding every word come back when there are any, else ads holding some (`match` says "all", "partial" or "none", with a `hint`). When no ad holds every word as written, a last word of 4+ letters is also read as a word start ("cust" finds customer; the `hint` says so). When nothing matches at all, misspelt words are corrected to the closest words the library's names and ads use and searched once more; `corrected_query` then says what was searched. Use 1–3 English product or format words; long phrases match little. Returns each hit's type, slug or id, and page URL. Start here when you have a product, brand or idea rather than an exact slug; when `match` is "none", follow the `hint`: it names a matching niche or format, or says the library has nothing on it. Arguments: - `query` (string, required): Keywords, e.g. "protein powder", "Nike", "before after". - `limit` (integer): How many to return (1–25, default 10; more returns 25). ### list_ads: List ads Browse real ads, newest first (or by `sort`), optionally filtered by brand (a competitor's ads), niche and format slug, or by the standard tags: `visual_format` (list_visual_formats), `hook` (the hook tactic, list_hooks), `season` and `offer_type`, or by `status` (`running` or `ended` on Meta), or by `type` (`static`, `video` or `carousel`). Ads the library has not tagged yet never match a tag filter. Without a brand filter a page keeps a few ads per brand so one advertiser cannot fill it; filter by brand for all of one brand's ads. Filtered by brand, the first page also carries `brand_patterns`: per kind the brand has ads of (static, carousel, video), how many are read, the share of read ads with each trait, the most common structure, the top visual format and hook tactic (and for videos the median second the product is first seen and the commonest setting); below 5 read ads of a kind, only the counts and a note. When the account's plan does not include brand patterns, each kind has its counts, its brand page `url` and a `note` saying so. Ads tracked on Meta carry `run` (started, last_seen, running, days_running, landing_page; `running` holds as of `last_seen`, the last day a pull saw it); `sort: "longest_running"` lists those by the longest run, the usual proxy for an ad worth studying (it is not performance data); `sort: "most_saved"` puts the ads readers saved most first. Paginate with the returned `nextCursor`; when the account's plan does not include every ad of a list, it stops at its first 50 ads (one page: set `limit` up to 50), with no `nextCursor` and a `note` saying so. On a plan with every ad of a list, a page counts one call per 10 ads asked for against the allowance (`limit`: 50 counts 5), so ask for the page you need. Arguments: - `brand` (string): The brand slug from its page URL ("nike") or its plain name. Call search_library or list_brands if unsure. - `niche` (string): The niche slug from its page URL ("beauty") or its plain name. Call search_library or list_niches if unsure. - `format` (string): The format slug from its page URL ("ugc") or its plain name. Call search_library or list_formats if unsure. - `visual_format` (string): The visual format slug from list_visual_formats ("testimonial") or its plain name. - `hook` (string): The hook tactic slug from list_hooks ("social-proof") or its plain name. - `season` (string): The season or event the ad is built around. - `offer_type` (string): `promo`: a deal with a deadline. `always-on-offer`: a standing offer on the creative. `no-offer`. - `status` (string): `running`: still running on Meta as of the last pull that saw it (`run.last_seen`). `ended`: stopped. Only ads tracked on Meta (with `run`) match. - `type` (string): The ad's type: `static` (one image), `video` or `carousel`. Every ad has one. - `sort` (string): `newest` (default, by launch date); `most_saved`: the ads readers saved most first, then newest; `longest_running`: the longest Meta run first, only ads with run dates. - `limit` (integer): How many to return (1–50, default 20; more returns 50). - `cursor` (string): `nextCursor` from the previous page, to continue. ### get_ad: Get an ad One ad in full: copy, audiences, brand, niche, formats, its standard tags (visual formats, the main one first with `main: true`, none marked when the ad was read before its order was kept; hook tactic, hook line, asset type, offer type, season, talent, awareness stage; null when not tagged yet; get_format explains a visual format), image URL, page URL, `run` (Meta start date, last day seen, running, days running, landing page) when the ad is tracked on Meta, `meta` beside it (platforms, button text, Meta format, variants, and `brand_median_run_days`, the median run of the brand's tracked ads, when it has at least 5; each only when the ad has it), and `why_it_works`: a short note on how the ad is built, the mechanism of its hook, format, offer and talent from its tags, plus its run when its brand kept it going a month or more (null when it has neither), never a claim about its results; and `breakdown` once the ad has been read (null before): `kind` (static, carousel or video), `units` (each layer, card or scene with its visual format, the first with the hook tactic, what it shows and the words on the creative, plus what is said in the first 3 seconds), `message` (problem, promise, ask, feel, tone), `traits`, `structure` and `structure_line`, `remix` (a fill-in script from the structure) and `provenance`. When the account's plan does not include ad breakdowns, the breakdown has `kind`, `message`, `traits` and `provenance`, with `units_omitted` (how many units) and a `note` naming the ad's page in place of the units, structure and remix. Lines said after the first 3 seconds come as `locked_lines` only on plans with transcripts; otherwise `locked_lines_omitted` says how many were left out. A breakdown says how the ad is built, never that it worked. The id may be cut short to its first 8 characters or more, and is read when it names one ad. Arguments: - `id` (string, required): The ad id, as in its page URL /ads/, that URL, or the id's first 8 characters or more. ### get_ads: Get several ads Up to 10 ads in full in one call, each in the shape get_ad returns (copy, audiences, brand, niche, formats, standard tags, image URL, page URL, `run`, `meta`, `why_it_works`, `breakdown`). Use it instead of repeated get_ad calls when reading the ads a search or list returned: one round trip, though each ad counts as one call against the allowance. Ids the library lacks come back under `missing` (`malformed` for an item that is not an ad id at all), and the rest still return. Arguments: - `ids` (array, required): The ad ids (or ad page URLs) to read, up to 10, from list_ads or search_library results. ### list_brands: List brands Every brand in the library, optionally only one niche's. Each brand comes with updated: the day (YYYY-MM-DD) its Meta ads were last checked for new ones, or null when they have not been. Arguments: - `niche` (string): The niche slug from its page URL ("beauty") or its plain name. Call search_library or list_niches if unsure. ### list_niches: List niches Every niche (industry) ads are filed under. Arguments: - no arguments ### list_formats: List formats The older name for list_visual_formats, and the same formats: every standard visual format (testimonial, before and after, us vs them, …) that ads in the library carry. Its slugs are what list_ads takes as `format` or as `visual_format`, and what /formats/{slug} shows. Prefer list_visual_formats, which also gives each one a line on what it is. Arguments: - no arguments ### list_visual_formats: List visual formats Every standard visual format (testimonial, screen recording, us vs them, …) that ads in the library carry, with a one-line description. An ad has up to three. Pass a slug to list_ads as `visual_format`. Arguments: - no arguments ### get_format: Get a visual format's guide One visual format in full, for writing, briefing or tagging an ad in it: `gloss` (the one line from list_visual_formats), `definition`, `how_to_tell` (`must_be`: what must all hold; `not_this`: near misses that are another format; `quick_test`: one question that settles most cases), `confused_with` (the formats it is mixed up with, each with the line that tells them apart), `how_to_build` (`when_to_use` and `best_practices`) and `examples`: a few library ads that carry it, longest Meta run first (else newest), each with `main` (true when it is the ad's main format, false when it is not or the ad's order is not known), image and page URL; read them with get_ads. A format with no guide written yet has its gloss and examples, and null for the rest. Takes a slug from list_visual_formats or the format's plain name. Call it before writing an ad in a format, or to check which format an ad is. Arguments: - `slug` (string, required): The visual format slug from list_visual_formats ("testimonial") or its plain name. ### list_hooks: List hook tactics Every hook tactic (curiosity, social proof, myth busting, …) that ads in the library carry, with a one-line description: the device the first frame or the headline uses to earn attention. Pass a slug to list_ads as `hook`. Arguments: - no arguments ### list_saved_ads: List my saved ads The ads you saved on the site, newest first, then the competitor ads saved from brands you follow (`tracked_ads`). Each comes with your team's note on it and the boards it is on, with each board's note: the reader's own reasons for keeping it. Arguments: - `limit` (integer): How many to return (1–100, default 50; more returns 100). ### list_followed_ads: List new ads from brands I follow The brands and Facebook pages you follow on the site, and their newest Meta ads, newest launch first: competitor ads as they go live. Each followed brand comes with its library slug when it has one (use it with list_ads for its filed ads) and its tracking page URL. Empty when the account follows nothing; the result then says where following is set up. Arguments: - `limit` (integer): How many to return (1–50, default 20; more returns 50). ### list_boards: List my boards The account's boards (shared with its team), by name: each with its id, its `group` (the client it is filed under, null for none), how many ads it holds, and its `share_url` when its share link is on (null when off). The ads on each board come with list_saved_ads. Use the ids or the exact names with the board tools. Arguments: - no arguments ### list_followed_brands: List the brands I follow The library brands the account follows, A to Z, each with its slug (use it with list_ads or unfollow_brand) and page URL, plus how many the account follows and how many its plan allows. Empty when it follows none. For their newest ads, use list_followed_ads. Arguments: - no arguments ### get_usage: Check my remaining calls How many calls the account has used this period (`per`: a day or a month, UTC, or `life` on Free, which never resets), out of how many, and when the count resets (`resets_at`, null for `life`). Shared by this server and the JSON API. Reading it costs nothing. Call it before a long run of reads, or when the reader asks how many calls are left. Arguments: - no arguments ### follow_brand: Follow a brand Follow a library brand for the account, as the Follow button on its brand page does: its new ads then show in list_followed_ads, and on the following page. Takes the brand slug from search_library or list_brands (or its plain name). Following a brand already followed succeeds and changes nothing. Returns how many brands the account follows and how many its plan allows. When the plan follows no brands, or the account is at its plan's cap, nothing is followed and the answer says so: relay it once, do not retry. Arguments: - `brand` (string, required): The brand slug from search_library or list_brands ("glossier"), or its plain name. ### unfollow_brand: Stop following a brand Stop following a library brand: its new ads leave list_followed_ads and the following page. Open on every plan. Unfollowing a brand the account does not follow succeeds and changes nothing. Arguments: - `brand` (string, required): The brand slug from search_library or list_brands ("glossier"), or its plain name. ### create_board: Create a board Create a board for the account and its team, to file ads by brief, client or idea. Optionally pass `ad_id` to save that ad and put it on the new board at once, and `group` to file the board under a client, on a plan that files boards by client (list_boards shows each board's `group`, so reuse a client's spelling; on another plan nothing is created and the answer says so). Each call makes a new board, even with a name already in use, so call list_boards first when unsure. On Free, which makes no boards, or when the plan allows no more, nothing is created and the answer says so: relay it once with its link, and offer to save the ads instead (save_ad) or to add them to a board the account already has. Arguments: - `name` (string, required): The board's name, up to 60 characters. - `ad_id` (string): Optional: a library ad to save and put on the new board (its id or page URL). - `group` (string): The client to file the board under, up to 40 characters, as list_boards spells it ("Acme"); an empty string takes the board out of its client. ### delete_board: Delete a board Delete one of the account's boards, by id or exact name. Its ads stay saved (list_saved_ads); its share link stops working. Cannot be undone: confirm with the reader first. A board that is not there answers `found: false`. Arguments: - `board` (string, required): The board's id or its exact name, from list_boards. ### share_board: Share a board by link Turn on a board's share link and return it as `share_url`: anyone with the link sees the board and its ads, without an account. A board already shared returns its current link unchanged. Arguments: - `board` (string, required): The board's id or its exact name, from list_boards. ### unshare_board: Turn off a board's share link Turn off a board's share link: the old link stops working at once. Sharing it again later makes a new link. A board whose link is already off succeeds and changes nothing. Arguments: - `board` (string, required): The board's id or its exact name, from list_boards. ### add_ad_to_board: Add an ad to a board Save a library ad and put it on one of the account's boards (by board id or exact name). Takes the ad id from list_ads, search_library or get_ad. An ad already on the board stays there once. Arguments: - `board` (string, required): The board's id or its exact name, from list_boards. - `ad_id` (string, required): The ad id from list_ads, search_library or get_ad, or its page URL. ### save_ad: Save an ad Save a library ad for the account and its team, as the Save button on its page does, without putting it on a board. Takes the ad id from list_ads, search_library or get_ad. Saving a saved ad succeeds and changes nothing. It then shows in list_saved_ads. Arguments: - `ad_id` (string, required): The ad id from list_ads, search_library or get_ad, or its page URL. ### unsave_ad: Unsave an ad Unsave an ad: it leaves list_saved_ads and every board it was on, and its notes go with it. Confirm with the reader first when it is on a board. An ad that is not saved succeeds and changes nothing. Arguments: - `ad_id` (string, required): The ad id from list_ads, search_library or get_ad, or its page URL. ### set_ad_note: Write a note on a saved ad Write the team's note on a saved ad (why it is worth keeping, what to borrow), or with `board` the note on that board's copy of it. Replaces the note there; an empty note clears it. The ad must be saved, or on the board, first (save_ad, add_ad_to_board). Notes come back in list_saved_ads. Arguments: - `ad_id` (string, required): The ad id from list_ads, search_library or get_ad, or its page URL. - `note` (string, required): The note, up to 1000 characters; an empty string clears it. - `board` (string): Optional: the board (id or exact name) whose copy of the ad gets the note. Without it, the note is on the saved ad. ### rename_board: Rename a board Rename one of the account's boards (by board id or exact name) with `name`, file it under a client with `group` (an empty string takes it out of its client; on a plan that does not file boards by client, the client is left as it was and the answer says so), or both. Its ads, notes and share link stay as they are. Arguments: - `board` (string, required): The board's id or its exact name, from list_boards. - `name` (string): The board's new name, up to 60 characters. - `group` (string): The client to file the board under, up to 40 characters, as list_boards spells it ("Acme"); an empty string takes the board out of its client. ### remove_ad_from_board: Remove an ad from a board Take an ad off one of the account's boards; it stays saved. An ad that is not on the board succeeds and changes nothing. Arguments: - `board` (string, required): The board's id or its exact name, from list_boards. - `ad_id` (string, required): The ad id from list_ads, search_library or get_ad, or its page URL. --- # AdSwipeFile public API A small JSON API over the AdSwipeFile ad library, for signed-in accounts (free), with account endpoints for your saved ads, boards and followed brands. Per list it returns the first 50 ads on Free, in one page (`limit`), and on a paid plan every page (`cursor`); per ad, its card (name, description, brand, niche, formats, standard tags, image, page URL). For the full library and each ad's copy, use the [MCP server](https://adswipefile.com/docs/mcp): the same token works there. ## Authentication Every `/api/v1` request needs one of: - **An API key**: `Authorization: Bearer asf_…`. Make one at https://adswipefile.com/api-keys while signed in; it is shown once. A key acts as your account, with its plan and allowance, reads and writes (saves, boards, follows) alike, and works on the [MCP server](https://adswipefile.com/docs/mcp) too. Revoke it there when a script no longer needs it. - **A signed-in session** (first-party, browser): [sign up free](https://adswipefile.com/login) and call the API from a page on https://adswipefile.com; the session cookie is sent automatically. A session writes only from the site's own pages (`Sec-Fetch-Site: same-origin`), never from another site. - **An OAuth 2.1 access token**: `Authorization: Bearer `. It is the token the MCP flow issues, so a client already connected over MCP can reuse it. Getting a token, for a client of your own: 1. Discover: a request without credentials answers `401` with `WWW-Authenticate: Bearer resource_metadata="…"`. That document names the authorization server; its metadata is at https://adswipefile.com/.well-known/oauth-authorization-server. 2. Register a client: `POST https://adswipefile.com/api/auth/oauth2/register` (dynamic client registration, open). 3. Authorize with code + PKCE (S256): https://adswipefile.com/api/auth/oauth2/authorize, `scope=mcp:read` (add `mcp:write` for the account endpoints' `POST` and `DELETE`, and `offline_access` for a refresh token), `resource=https://adswipefile.com/api/mcp`. The person signs in (email link or code, or Google) and approves the access asked for. 4. Exchange the code at https://adswipefile.com/api/auth/oauth2/token. Tokens are bound to the audience `https://adswipefile.com/api/mcp` and the scope `mcp:read`, for this API and the MCP server alike; changing saves, boards and follows also needs `mcp:write`. A missing, invalid or expired token, or a revoked key, is a `401` problem; a token without `mcp:read` is a `403`, and a write with a token without `mcp:write` is a `403` whose `WWW-Authenticate` carries `error="insufficient_scope", scope="mcp:read mcp:write"`: authorize again with both scopes. A token approved before `mcp:write` existed reads only until then. The machine-readable description is https://adswipefile.com/openapi.json (OpenAPI 3.1; every operation has an `operationId`, so it imports as function-calling tools). ## Endpoints - `GET /api/v1/search?q={keywords}`: ads, brands, niches, visual formats and hook tactics matching the keywords (2 to 64 characters), each with its page URL. An ad hit's `description` is its copy. - `GET /api/v1/ads?brand=&niche=&format=&visual_format=&hook=&season=&offer_type=&status=&type=&limit=`: the newest ads, optionally filtered by slugs (`brand`, `niche`, `format`, `visual_format`, `hook`), by `season` and `offer_type`, by `status` (`running` or `ended` on Meta, tracked ads only) and by `type` (`static`, `video` or `carousel`); `limit` 1 to 50 on Free, where a list has no next page (20 when left out; up to 50 a page on a paid plan), `cursor` the `nextCursor` of the last page (paid plans; one call per 10 ads). `hook` is the hook tactic. Ads the library has not tagged yet never match a tag filter. - `GET /api/v1/ads/{id}`: one ad's card, with `whyItWorks`: the mechanism of its hook, format and offer, from its tags (never its results), and its `breakdown` once read: what it says and its traits on every plan; its units, structure and `remix` script on Pro and Agency (on Free, `unitsOmitted` and a `note` in their place). With `brand`, `GET /api/v1/ads` adds `brandPatterns`: read counts per type on every plan, the trait shares, top structure, format and hook on Pro and Agency. For an ad tracked on Meta it also has `meta`: `platforms`, `cta`, `displayFormat`, `variants`, and `brandMedianRunDays` with `brandTrackedAds` when the brand has at least 5 tracked ads. - `GET /api/v1/visual-formats` and `GET /api/v1/hooks`: the standard visual formats and hook tactics in use, with their slugs and a one-line description. - `GET /api/v1/brands?niche=` and `GET /api/v1/niches`: the library's brands (A to Z, optionally of one niche) and its niches, with their slugs and page URLs. - `GET /api/v1/saved-ads?limit=`: your team's saved ads, newest first, each with its note and the boards it is on (`limit` 1 to 100). `GET /api/v1/following/ads?limit=`: the newest Meta ads of the brands and pages you follow (`limit` 1 to 50). Both count against the allowance, like `/ads`. - `GET /api/health`: `{ ok, buildId, startedAt }`. Every card carries the ad's standard tags: `visualFormats` (up to three), `hookTactic`, `hookLine` (the hook as written), `assetType`, `offerType`, `season`, `talent` and `awareness` (how much the viewer is assumed to know, `unaware` to `most-aware`). They are empty or `null` until the library has tagged the ad; `awareness` is `null` on ads tagged before it was added. They describe the creative, not how it performed. ## Your saves, boards and followed brands Free: none of these counts against the allowance. The writes (`POST`, `PUT`, `PATCH`, `DELETE`) take an API key, a token with `mcp:write`, or a session on the site's own pages, and have their own window of 30 a minute per account. Every write is your team's: no input names an owner, and another team's board answers `404`. A board is named by its id or its exact name. - `POST /api/v1/saved-ads` with `{ "ad_id": "…" }`: saves a library ad, as its Save button does; saving it again is fine. `DELETE /api/v1/saved-ads/{id}` unsaves it, which also takes it off every board, with its notes. - `PUT /api/v1/saved-ads/{id}/note` with `{ "note": "…", "board": "…" }`: your team's note on a saved ad, or with `board` on that board's copy of it; `""` clears it. An ad not saved (or not on the board) is a `404`. - `GET /api/v1/boards`: your boards, each with `id`, `name`, `group` (the client it is filed under, null for none), `ads` (how many) and `share_url` (null while its link is off). - `POST /api/v1/boards` with `{ "name": "…", "ad_id": "…", "group": "…" }` (`ad_id` optional: saves that ad onto the new board; `group` optional: the client to file it under, on Agency): `201` and the board. Past the plan's board limit, `403 plan_limit`. - `PATCH /api/v1/boards/{board}` with `{ "name": "…" }`: renames it. With `{ "group": "…" }` (Agency) files it under a client; `null` takes it out, on any plan. Either or both. - `DELETE /api/v1/boards/{board}`: deletes it; its ads stay saved and its link stops working. A board that is gone is a `404`. - `POST /api/v1/boards/{board}/share`: turns its link on and returns `share_url`; a shared board returns the link it has. `DELETE` turns it off (the old link stops working); off already is fine. - `POST /api/v1/boards/{board}/ads` with `{ "ad_id": "…" }`: saves the ad and puts it on the board; twice keeps it once. `DELETE /api/v1/boards/{board}/ads/{id}` takes it off (it stays saved); an ad not on it is fine. - `POST /api/v1/brands/{slug}/follow`: follows a library brand, as its Follow button does; following it again is fine. On a plan without follows, or at its cap, `403 plan_limit`. `DELETE` stops following, on any plan. `GET /api/v1/following/brands`: the brands you follow, with how many your plan allows. - `GET /api/v1/account/usage`: your calls this period (`used`, `limit`, `per` day or month), and when they reset (`resets_at`). ```bash curl -s -X POST -H "Authorization: Bearer $ADSWIPEFILE_API_KEY" -H 'content-type: application/json' -d '{"name":"March brief"}' 'https://adswipefile.com/api/v1/boards' curl -s -X POST -H "Authorization: Bearer $ADSWIPEFILE_API_KEY" 'https://adswipefile.com/api/v1/brands/glossier/follow' curl -s -H "Authorization: Bearer $ADSWIPEFILE_API_KEY" 'https://adswipefile.com/api/v1/account/usage' ``` Slugs are the last part of a page URL: https://adswipefile.com/niches/beauty is the niche `beauty`. Find them with search. ```bash curl -s -H "Authorization: Bearer $ADSWIPEFILE_API_KEY" 'https://adswipefile.com/api/v1/search?q=protein' curl -s -H "Authorization: Bearer $ADSWIPEFILE_API_KEY" 'https://adswipefile.com/api/v1/ads?niche=beauty&format=ugc&limit=5' curl -s -H "Authorization: Bearer $ADSWIPEFILE_API_KEY" 'https://adswipefile.com/api/v1/ads?visual_format=testimonial&season=black-friday' ``` ## Rate limits 60 requests a minute per account, over a sliding window. Every authenticated response says where you stand: ```http RateLimit-Policy: "account";q=60;w=60 RateLimit: "account";r=59;t=42 ``` (`RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` carry the same numbers.) Past the limit the answer is `429` with the code `rate_limited` and `Retry-After` in seconds. ## Allowance: monthly on Pro and Agency, once for the account's life on Free Every MCP tool call (except `list_niches`, `list_formats`, `list_visual_formats` and `list_hooks`) and every `/api/v1` request counts against the account's allowance (UTC): 50 in total on Free, 10,000 a month on Pro, 50,000 a month on Agency, and 200 a day during the free trial of either. A paid month also has a daily ceiling (1,000 on Pro, 3,000 on Agency), so it cannot all go in one day. `get_ads` counts one call per ad it reads, and on Pro and Agency a `list_ads` or `search_library` page counts one call per 10 ads asked for (`limit` 50 counts 5). Past it, the API answers `429` with the code `quota_exceeded` and `Retry-After` set to the reset (UTC: the first of next month on Pro and Agency, never on Free), and MCP tools answer with a message instead of results; both say when the allowance resets and how to raise it, with the link. See [pricing](https://adswipefile.com/pricing). ## Errors Every error is `application/problem+json` (RFC 9457), including unknown paths under `/api/`. Responses are never cached (`Cache-Control: private, no-store`). ```json { "type": "https://adswipefile.com/docs/api#errors", "title": "Not found", "status": 404, "detail": "No niche with slug \"beuty\".", "code": "not_found", "resolution": "Find slugs with /api/v1/search?q=, …" } ``` Branch on `code` (one of `not_found`, `bad_request`, `unauthorized`, `forbidden`, `plan_limit`, `method_not_allowed`, `rate_limited`, `quota_exceeded`, `not_acceptable`, `service_unavailable`), show `detail`, follow `resolution`. ## Markdown instead of JSON Any page URL answers `Accept: text/markdown` with that page as markdown, at the same URL: `curl -H 'Accept: text/markdown' https://adswipefile.com/niches`. A client that accepts neither markdown nor HTML gets `406`.