API & MCP

The Adsup.ai API gives you the same data as the app: ads our crawler captured, advertiser, publisher and network profiles, the coverage ledger, and on-demand crawls. Every operation is also available as a tool on our MCP server, so an AI agent such as Claude can use it directly.

The machine-readable description is at /api/v1/openapi.json (OpenAPI 3.1).

Access and keys

API and MCP access are included in Pro and Team. Create a key under Settings → API Keys and send it with every request:

curl -H "Authorization: Bearer sk_your_key" \
  "https://adsup.ai/api/v1/ads?q=vpn&geos=US,DE&pageSize=20"

Keys belong to your account. Delete a key to revoke it immediately. Browser cookies never authorize the API.

Credits

Calls spend credits from your plan. Pro includes 5,000 credits a month and Team 50,000 (yearly plans receive the year's credits up front). Your balance, this month's usage and the cost of each call are on the API Keys page and at GET /api/v1/me/usage.

A call that fails (any 4xx or 5xx response, including "not found") is refunded. Each response carries an X-Credits-Charged header.

Limits

• Rate limit: 60 requests per minute per key. Over the limit you get HTTP 429 with Retry-After. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.
• History: Pro sees the last 180 days, Team all history. Wider date filters are narrowed and the response says so in meta.limited ("history").
• On-demand crawls: Pro 20 and Team 100 per rolling 24 hours (shared with the app), at most one every 30 seconds.

Responses and errors

Every response uses the same envelope, with the HTTP status set to match:

{ "code": 0, "message": "ok", "data": { "items": [], "total": 0 } }

Errors have code: -1 and a machine-readable message:

Endpoints

Search filters: q, adTypes, networks, geos, devices, platforms, advertiserIds, publisherIds (e.g. web:example.com), landingDomains, languages, verticals, sizes (300x250), seenFrom / seenTo, firstSeenFrom / firstSeenTo (new ads), minDaysSeen, minPublishers, hasLandingPage, riskMin, sort (last_seen, first_seen, days_seen, publishers, impressions), order, page, pageSize (max 50).

impressions counts how often our crawlers observed an ad. It is not delivered impressions, spend or reach.

curl -X POST https://adsup.ai/api/v1/ads/search \
  -H "Authorization: Bearer sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"adTypes":["native"],"geos":["US"],"firstSeenFrom":"2026-11-01","sort":"first_seen"}'

MCP server

The MCP server speaks Streamable HTTP at https://adsup.ai/api/mcp and uses the same keys, credits and limits as the REST API. It is built on the official MCP TypeScript SDK and is stateless, so any compliant client works.

Tools: search_ads, get_ad, get_advertiser, get_publisher, get_network, coverage, request_crawl, get_crawl_request, get_usage. Each tool call costs the same as the REST call it maps to; the handshake and tool listing are free.

Claude Code:

claude mcp add --transport http adsup https://adsup.ai/api/mcp \
  --header "Authorization: Bearer sk_your_key"

Any client that takes a JSON config (for example Claude Desktop, Cursor):

{
  "mcpServers": {
    "adsup": {
      "type": "http",
      "url": "https://adsup.ai/api/mcp",
      "headers": { "Authorization": "Bearer sk_your_key" }
    }
  }
}

Then ask, for example: "Find native ads for VPN offers first seen in Germany this week and summarise the landing pages."

Alert webhooks

On Team, a saved search's daily alert can also be sent to a webhook (set it on Saved & alerts). Slack incoming-webhook URLs (hooks.slack.com) receive a Slack message. Other URLs receive:

{
  "type": "alert.new_ads",
  "alert_id": "…",
  "rule": { "kind": "saved_search", "target": "…", "name": "VPN native US" },
  "count": 3,
  "ads": [
    {
      "id": "…",
      "title": "…",
      "thumb_url": "…",
      "url": "https://adsup.ai/app/ads/…"
    }
  ],
  "sent_at": "2026-11-07T06:00:00.000Z"
}

Verify the X-Adsup-Signature: t=<unix>,v1=<hex> header: v1 is the HMAC-SHA256 of t + "." + body with the signing secret shown next to the webhook. Webhook URLs must be https:// on a public host; redirects are not followed.