Docs

Public API

The VisiScan API runs AI visibility scans from your own code. Create an API key in your dashboard, give it the scopes you need, and call the endpoints below. Every request is authenticated by the key, so API scans skip the browser email gate and return the full report directly.

Overview

Base URL: https://www.visiscan.app/api/v1
Authentication: bearer token on every request (see below).
Format: JSON request and response bodies; content-type: application/json on writes.
Tier: API scans run at the free tier. Full-report entitlements are not yet exposed through the API.

Authentication

Pass your key as a bearer token on every request:

Authorization: Bearer vsk_...

Keys are shown once at creation. A missing or invalid key returns 401; a key without the scope for an endpoint returns 403.

Scopes

A key carries one or more scopes. Grant the least it needs.

scans:write — enqueue a scan.
scans:read — read a scan and its report.
monitors:write — create a recurring monitor.

POST /api/v1/scans

Enqueues a scan for the given URL and returns immediately with a scan id. Requires scans:write. Each key has a monthly scan quota; requests past quota return 429.

curl -X POST https://www.visiscan.app/api/v1/scans \
  -H "Authorization: Bearer vsk_..." \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com"}'

# 202 Accepted
{"scanId":"cxyz123...","deduped":false}

deduped: true means a recent scan for the same URL was returned instead of starting a new one.

GET /api/v1/scans/:id

Polls a scan and returns the report once complete. Requires scans:read. Returns 404 if the scan does not exist or was not created by this key.

curl https://www.visiscan.app/api/v1/scans/cxyz123... \
  -H "Authorization: Bearer vsk_..."

# while running
{"scanId":"cxyz123...","status":"QUESTIONING","emailRequired":false}

# once complete
{"scanId":"cxyz123...","status":"COMPLETE","emailRequired":false,"report":{ ... }}

Scan status values

A scan moves through these stages in order. Poll until COMPLETE or FAILED.

QUEUED -> PROFILING -> QUESTIONING -> AUDITING -> SCORING -> COMPLETE
                                                          \-> FAILED

Errors

Status	Meaning
401	Missing or invalid API key.
403	Key lacks the scope for this endpoint.
404	Scan not found, or not owned by this key.
429	Monthly quota exceeded, or the URL is being rescanned too often.

Error responses carry a JSON body of the form {"error":"..."}.

For a machine-readable description of scopes and the auth server, see /.well-known/oauth-protected-resource. For agent discovery, see /llms.txt and /ai.txt.