Belgeler
Ctrl+K Arama Alt+[Alt+] Kılavuzlar
API anahtarını al

API · Reklam kütüphanesi

Magic AI API (/api/v1/magic-ai)

This page documents the programmatic Magic AI endpoint. Use it with an API key to run the same competitor-discovery flow used by the dashboard.

Endpoint

  • Method: YAYIN
  • Path: /api/v1/magic-ai
  • Yazar: X-API-Anahtarı ya da Authorization: Bearer <key>
  • Content type: form payload (application/x-www-form-urlencoded ya da multipart/form-data)

Kullanım /api/v1/magic-ai API anahtarı entegrasyonları için.
/api/magic-ai is the dashboard session route used by the web app.

Minimum request body

Send at least one search input:

  • metin (free-text prompt), or
  • görüntü (uploaded file), or
  • image_url (public image URL)

Recommended pagination fields:

  • sayfa (start with 0, increment on each continuation)
  • scroll (empty on first request; then send the scroll returned by the previous response)
  • sınır (optional page size; default 20, max 50 on first request; stored in scroll for continuations)

API pagination: scroll is an opaque server token (1 hour TTL). Repeat the same search inputs and filters on each continuation request. No browser cookies are required.

Optional filters

You can pass the same filters used in the Magic AI UI:

  • ülkeler - comma-separated country codes or Tümü
  • ...'den, ...'ye - start-date range
  • songörüldüğünden beri, görülmüş - last-seen date range
  • activefilter=active - restricts results to ads last seen within the past 4 days
  • minadspend, maxadspend - ad spend range
  • zihin günleri, maksimum gün sayısı - days-running range
  • reklam puan filtresi - ad score preset

If a filter is omitted, default behavior follows the product defaults.

Example: text search

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \
  -X POST "{origin}/api/v1/magic-ai" \
  --data-urlencode "text=Find winning beauty products for US women 25-34" \
  --data-urlencode "countries=US" \
  --data-urlencode "page=0" \
  --data-urlencode "scroll="

Example: continue pagination

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded; charset=UTF-8" \
  -X POST "{origin}/api/v1/magic-ai" \
  --data-urlencode "text=Find winning beauty products for US women 25-34" \
  --data-urlencode "countries=US" \
  --data-urlencode "page=1" \
  --data-urlencode "scroll=<scroll_token_from_previous_response>"

Response shape

Typical success response:

{
  "data": [
    {
      "id": "...",
      "ad_creative_body": "...",
      "ad_snapshot_url": "...",
      "image_url": "...",
      "country": "US"
    }
  ],
  "scroll": "..."
}
  • veriler is an array of matched ads.
  • scroll is the cursor for the next page. If no more data exists, it can be empty or null.

Each page returns up to 20 ads.

Errors and limits

This endpoint follows the same API-key auth and metering rules as the rest of the Standard API surface:

  • 401 invalid/missing API key
  • 403 account does not include API access
  • 429 rate limit or monthly credits exhausted

See: