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: POST
• Path: /api/v1/magic-ai
• Auth: Chave X-API ou Authorization: Bearer <key>
• Content type: form payload (application/x-www-form-urlencoded ou multipart/form-data)

Utilização /api/v1/magic-ai para integrações com chave de API.
/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
• imagem (uploaded file), or
• image_url (public image URL)

Recommended pagination fields for deterministic paging:

• página (start with 0)
• rolar (empty string on first request; then send the rolar returned by the previous response)

Optional filters#

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

• países - comma-separated country codes or Todos
• de, para - start-date range
• desde a última vez que foi visto, tolastseen - last-seen date range
• minadspend, gasto máximo - ad spend range
• mindays, dias máximos - days-running range
• filtro de pontuação de anúncios - 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": "..."
}

• dados is an array of matched ads.
• rolar 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:

• Autenticação
• Créditos e cobrança
• Limites de taxa
• Erros