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 for deterministic paging:

• página (start with 0)
• desplazarse (empty string on first request; then send the desplazarse 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 Todo
• de, a - start-date range
• desde la última vez que se le vio, tolastseen - last-seen date range
• 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.

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:

• Autenticación
• Créditos y facturación
• Límites de velocidad
• Errores