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
• Auth: 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 for API-key integrations.
/api/magic-ai is the dashboard session route used by the web app.

Minimum request body#

Send at least one search input:

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

Recommended pagination fields for deterministic paging:

• sayfa (start with 0)
• scroll (empty string on first request; then send the scroll returned by the previous response)

Optional filters#

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

• countries - comma-separated country codes or Tümü
• from, to - start-date range
• fromlastseen, tolastseen - last-seen date range
• minadspend, maxadspend - ad spend range
• mindays, maxdays - days-running range
• adscorefilter - 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": "..."
}

• data is an array of matched ads.
• scroll is the cursor for the next page. If no more data exists, it can be empty.

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:

• Kimlik Doğrulama
• Krediler ve faturalandırma
• Hız sınırları
• Hatalar