Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/webhood-io/webhood/llms.txt

Use this file to discover all available pages before exploring further.

The Create Scan endpoint submits a URL to your Webhood instance for analysis. Scanning is asynchronous: the endpoint immediately returns HTTP 202 Accepted with a new scan record whose status is pending. Your application must then poll GET /api/v1/scans/:id until the status transitions to done or error before retrieving the screenshot, HTML, or network trace.

​
Request

POST /api/v1/scans

​
Authentication

All requests require a valid Bearer token in the Authorization header. 
Authorization: Bearer <token>

​
Request Body

Send a JSON body with the following fields.
​
url
string
required
The fully-qualified URL to scan, including scheme. Must be a valid HTTP or HTTPS URL.Example: "https://example.com"
​
options
object
Optional scan configuration. If omitted, Webhood uses the instance defaults.

​
Response

Returns HTTP 202 Accepted with the newly created scan record. The status field will be pending at this point. A Location header is also set pointing to the scan’s GET endpoint.

​
Response Headers

HeaderValue
Location/api/beta/scans/<id> — URL to poll for status updates

​
Response Fields

​
id
string
Unique identifier for the new scan record. Use this value to poll for status.
​
slug
string
Auto-generated human-readable identifier in hostname-timestamp format, e.g. example.com-1714001200.
​
url
string
The URL that was submitted.
​
status
string
Always pending immediately after creation.
​
created
string
ISO 8601 timestamp of when the scan record was created.
​
updated
string
ISO 8601 timestamp of the last update.
​
errorMessage
string
Empty string on creation. Populated only if the scan later transitions to error.
​
html
array
Empty array on creation. Populated with file IDs after the scan completes.
​
screenshots
array
Empty array on creation. Populated with file IDs after the scan completes.
​
files
array
Empty array on creation. Populated with IDs of any additional artifact files attached to the scan.
​
done_at
string
Empty string on creation. Populated when the scan finishes.
​
final_url
string
Empty string on creation. Populated with the resolved URL after redirects once the scan is done.
​
options
object
The ScanOptions submitted with the request.
​
scanData
object
Empty on creation. Populated with full scan metadata once the scan completes.

​
Examples

​
Submit a URL for Scanning

curl -X POST http://localhost:8000/api/v1/scans \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "options": {
      "rate": "balanced",
      "screenshotSize": "full"
    }
  }'

​
Response — HTTP 202 Accepted

{
  "id": "a1b2c3d4e5f6g7h8",
  "slug": "example.com-1714001200",
  "url": "https://example.com",
  "status": "pending",
  "created": "2024-04-25T10:00:00.000Z",
  "updated": "2024-04-25T10:00:00.000Z",
  "errorMessage": "",
  "html": [],
  "screenshots": [],
  "files": [],
  "done_at": "",
  "final_url": "",
  "options": {
    "rate": "balanced",
    "screenshotSize": "full"
  },
  "scanData": null
}

​
Async Polling Pattern

Because scanning is asynchronous, follow these steps to retrieve results: Step 1 — Submit the URL POST /api/v1/scans with the url and any options. Save the id from the response. Step 2 — Poll for completion Repeatedly call GET /api/v1/scans/:id using the saved id. While status is pending or running, the server returns HTTP 202 with a Location header. Continue polling until status is done or error. 
# Poll until status is no longer pending/running
curl http://localhost:8000/api/v1/scans/a1b2c3d4e5f6g7h8 \
  -H 'Authorization: Bearer <token>'
Step 3 — Retrieve artifacts Once status is done, download the scan artifacts as needed:
  • Screenshot → GET /api/v1/scans/:id/screenshot
  • Captured HTML → GET /api/v1/scans/:id/html
  • Network trace → GET /api/v1/scans/:id/trace
A scan remains in pending status until an available scanner picks it up. If no scanner is currently connected and running, the scan will stay pending indefinitely. Ensure at least one scanner is online before submitting scans, or implement a timeout in your polling loop.

Build docs developers (and LLMs) love

Get started for freeTalk to us