Scans API

List scan history, trigger new scans, and retrieve scan results.

List Scans

GET/api/v1/scans

Returns a list of scans ordered by creation date (newest first).

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Number of scans to return (max 100)

Response

JSON

{
  "scans": [
    {
      "id": "uuid",
      "status": "completed",
      "engines": ["google_ai", "chatgpt", "perplexity"],
      "products_scanned": 10,
      "avg_score": 68.4,
      "created_at": "2025-01-15T10:30:00Z",
      "completed_at": "2025-01-15T10:35:00Z"
    }
  ]
}

Get Scan Details

GET/api/v1/scans/:id

Returns detailed results for a specific scan, including per-product scores.

Response

JSON

{
  "scan": {
    "id": "uuid",
    "status": "completed",
    "engines": ["google_ai", "chatgpt"],
    "created_at": "2025-01-15T10:30:00Z"
  },
  "results": [
    {
      "product_id": "uuid",
      "product_name": "Nike Air Max 90",
      "engine": "chatgpt",
      "query": "best running shoes 2025",
      "mentioned": true,
      "position": 2,
      "sentiment": "positive",
      "recommended": true,
      "score": 82
    }
  ]
}

Trigger a Scan

POST/api/v1/scans

Triggers a new scan. The scan runs asynchronously — use the returned scan ID to poll for results.

Request Body

JSON

{
  "engines": ["google_ai", "chatgpt", "perplexity"]
}

The engines array is optional. If omitted, all available engines with valid API keys will be used.

Response

JSON

{
  "scan_id": "uuid",
  "status": "pending"
}

Required scope: write (for POST), read (for GET)