Skip to content
AIDE
Sign up
post/v1/scans

Create a new scan

Accepts a URL + optional metadata. The scan runs asynchronously; stream progress via the ``stream_url`` or poll ``result_url``. **Auth & dedupe**: Authenticated callers (session JWT or an API key with ``scans:write``) can scan a given domain only once — re-requests return ``existing=true`` + the prior ``scan_id``. Anonymous callers (no token) are limited to a single lifetime scan, identified by the server-issued ``aide_anon`` cookie + client IP. **Cache**: anonymous and Free callers re-requesting the same URL + profile within 24h receive the completed scan with ``cached=true, existing=true``; Pro+ always get a fresh scan. **Privacy**: scans are private by default; send ``publish_to_leaderboard=true`` to opt into the public leaderboard.

Parameters

ParametersTypeRequiredDescription
X-Anon-Id(header)———
authorization(header)———
aide_anon(cookie)———

Request body

  • urlstring <uri>Required
  • site_typeanyOfOptional
  • depthintegerOptional
  • js_renderbooleanOptional
  • priorityenum (2)Optional
  • webhook_urlanyOfOptional
  • metadataobjectOptional
  • profileenum (13)Optional

    Which check suite a scan asks for. Profile is orthogonal to ``site_type``: a "content" site can be scanned with the AI Agent-Ready suite *or* the SEO suite, and each suite weights its categories differently. Adding a profile is intentionally cheap — the registry filters by check class attribute so we never have to maintain a parallel inventory. Yeni bir profile eklemek için: bu enum'a satır ekle, ilgili check sınıflarının ``profiles`` frozenset'ine yeni profili koy. Frontend tarafında ``apps/web/src/lib/profiles.ts`` registry'sine de ekleme şart (UI route klasörü + i18n key'leri için).

  • seo_keywordsarrayOptional
  • seo_target_countryanyOfOptional
  • seo_competitorsarrayOptional
  • publish_to_leaderboardbooleanOptional

Responses

  • 202Successful Response
    • scan_idstringRequired
    • statusenum (5)Required
    • created_atstring <date-time>Required
    • estimated_duration_secondsintegerOptional
    • stream_urlstringRequired
    • result_urlstringRequired
    • cachedbooleanOptional
    • existingbooleanOptional
  • 422Validation Error
    • detailarrayOptional
POST /v1/scans | AIDE