Documentos
Ctrl+K Buscar Alt+[Alt+] Guías
Obtener clave API

API · Biblioteca de anuncios

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

Uso /api/v1/magic-ai para integraciones con claves API.
/api/magic-ai is the dashboard session route used by the web app.

Minimum request body

Send at least one search input:

  • texto (free-text prompt), or
  • imagen (uploaded file), or
  • url_de_la_imagen (URL de la imagen pública)

Recommended pagination fields:

  • página (start with 0, increment on each continuation)
  • desplazarse (empty on first request; then send the desplazarse returned by the previous response)
  • límite (optional page size; default 20, max 50 on first request; stored in desplazarse for continuations)

API pagination: desplazarse 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:

  • países - comma-separated country codes or Todo
  • de, a - start-date range
  • desde la última vez que se le vio, tolastseen - last-seen date range
  • activefilter=active - restricts results to ads last seen within the past 4 days
  • gasto en defensa, gasto máximo en publicidad - ad spend range
  • mindays, días máximos - days-running range
  • filtro de puntuación publicitaria - 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": "..."
}
  • datos is an array of matched ads.
  • desplazarse 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: