TagSentry
Sign in
All endpoints

DocsAPIScans

POST/sites/{siteId}/scans

Start a scan

Crawls the site in a real browser and records every tracker it finds.

Auth header

Authorization: Bearer tsk_live_…

The key needsscans:write

Parameters

  • siteIdstringin pathrequired

    The site id, from GET /v1/sites.

Example request

curl -X POST "https://app.tagsentry.ai/api/v1/sites/3f6c1b8e-2d4a-4c7e-9a51-0b8f2e6d7c10/scans" \  -H "Authorization: Bearer tsk_live_…"

Response 202

  • startedbooleanrequired

    False means a scan for this site was ALREADY queued or running and this request added nothing — not an error. Poll the scan instead of starting another.

  • scanIdstring | nullrequired

    The id of the tier-1 scan this request started: the scanId GET /sites/{siteId}/scans/latest returns for it and the scanRunId its scan.completed (tier: tier1) carries. Null when started is false.

  • detailstringrequired

Example response

{  "started": false,  "scanId": "3f6c1b8e-2d4a-4c7e-9a51-0b8f2e6d7c10",  "detail": "…"}
More about this endpoint

WHY THIS BLOCKS A BANNER TOO. A site no scan has finished serves none, because publishing a banner over trackers nobody has finished looking at would be a claim about an inventory we do not have. A site created through this API is in that state from birth.

started: false IS SUCCESS: it means a scan was already queued or running and this request added nothing. Poll the scan rather than starting another.

scanId is the tier-1 run this request started. Its scan.completed webhook says tier: tier1; a deeper tier-2 crawl follows a completed tier 1 and sends a second scan.completed with its own id and tier: tier2.

The site must be reachable over the public internet -- a crawl cannot see a password-protected staging environment or a localhost dev server.

Errors401 · 403 · 404 · 500
  • 401Missing, malformed, unknown, revoked or expired API key. These are deliberately indistinguishable in the response -- distinguishing them would confirm to a caller that a token was once real.
  • 403The key authenticated but does not carry the scope(s) this operation requires, or (`domain_not_verified`) the site's domain is not verified, so its consent records are not released.
  • 404No such resource on this account. A site id belonging to a DIFFERENT account answers 404, never 403 -- a 403 would confirm the id exists somewhere.
  • 500Something failed on our side. The requestId in the body is what to quote.

Every error has the same body: { error: { code, message, requestId } }.

From the OpenAPI document, version 2026-08-26. Raw OpenAPI