Webhood REST API Reference — Overview and Schema

Webhood exposes a REST API mounted at /api/v1/, routed through Kong to the Go/PocketBase backend running at http://backend:8090. Kong forwards all /api/ traffic to the backend, making the API accessible on your host’s configured port. Every endpoint requires a valid Bearer token in the Authorization header — unauthenticated requests are rejected with 401 Unauthorized.

Base URL

http://<your-host>:<port>/api/v1

Replace <your-host> and <port> with the hostname and port of your Webhood deployment. In a default local setup this is typically http://localhost:8000/api/v1.

The /api/beta/ prefix is the legacy endpoint that predates v1. It remains fully functional and uses the same underlying scan records, but /api/v1/ is the preferred path for all new integrations. Use v1 unless you have an existing integration pinned to beta.

Available Endpoints

Method	Path	Description
`GET`	`/api/v1/scans`	List scans with optional filter, sort, limit, and offset
`POST`	`/api/v1/scans`	Submit a new scan
`GET`	`/api/v1/scans/:id`	Get a single scan record by ID
`GET`	`/api/v1/scans/:id/screenshot`	Stream the screenshot image for a scan
`GET`	`/api/v1/scans/:id/html`	Stream the captured HTML for a scan
`GET`	`/api/v1/scans/:id/trace`	Stream the network trace JSON for a scan

GET /api/v1/scans — Query Parameters

filter

string

PocketBase filter expression, e.g. status='done'. Supports standard field comparisons and logical operators.

sort

string

Comma-separated sort fields, e.g. -created for descending by creation time.

limit

integer

Maximum number of records to return. Omit to return all matching records.

offset

integer

Number of records to skip before returning results. Use with limit for pagination.

POST /api/v1/scans — Request Body

url

string

required

The fully-qualified URL to scan, e.g. https://example.com.

options

object

Optional scan configuration. See the ScanOptions object below.

HTTP Status Semantics

Scan records go through a lifecycle. The API reflects this in its HTTP response codes:

Status	Meaning
`202 Accepted`	The scan is `pending` or `running` — poll again. A `Location` header points to the scan URL.
`200 OK`	The scan is `done` or `error` — the full result is present in the response body.

Scan Record Schema

Every endpoint that returns scan data uses the following JSON structure.

string

PocketBase record ID — unique alphanumeric identifier for this scan.

slug

string

Human-readable identifier composed of the scanned hostname and a Unix timestamp, e.g. example.com-1714000000.

url

string

The URL that was submitted for scanning.

status

string

Current lifecycle state of the scan. One of pending, running, done, or error.

created

string

ISO 8601 timestamp of when the scan record was created.

updated

string

ISO 8601 timestamp of when the scan record was last updated.

errorMessage

string

Human-readable error details. Only populated when status is error.

html

array of strings

File IDs for captured HTML artifacts. The first element (html[0]) is the page HTML; the second (html[1]), when present, is the network trace JSON (also served by the /trace endpoint).

screenshots

array of strings

File IDs for screenshot images captured during the scan.

files

array of strings

File IDs for any additional artifacts attached to this scan record.

done_at

string

ISO 8601 timestamp of when the scan completed. Empty while the scan is still in progress.

final_url

string

The URL the browser landed on after following all redirects. May differ from url when redirects occur.

options

object

The ScanOptions object that was used for this scan (see below).

scanData

object

A ScanDataV1_1 object containing detailed document, request, response, and metadata captured during the scan (see below).

ScanOptions Object

scannerId

string

ID of the scanner instance to run this scan. Omit to let Webhood assign one automatically.

rate

string

Scanning speed vs. resource-wait tradeoff. One of slow, balanced, or fast.

screenshotSize

string | object

Either the string "full" for a full-page screenshot, or an object with width and height string fields specifying pixel dimensions.

ScanData Object (ScanDataV1_1)

The scanData field is only populated when the scan has status: "done". It follows schema version "1.1".

version

string

Schema version string. Always "1.1" for current scans.

document

object

Information about the scanned document.

Show document fields

title

string

Page title from the DOM.

url

string

Final URL of the document as seen by the browser.

origin

string

Origin (scheme + host + port) of the document.

protocol

string

Network protocol used, e.g. h2, http/1.1.

links

array of strings

All hyperlinks found on the page.

request

object

The primary HTTP request made by the browser.

Show request fields

type

string

Always "request".

url

string

Request URL.

headers

object

Request headers as key-value pairs.

method

string

HTTP method, e.g. GET.

resourceType

string

Puppeteer resource type, e.g. document.

redirectChain

array of strings

Ordered list of URLs in the redirect chain leading to this request.

number

Timestamp (ms since epoch) when the request was made.

response

object

The HTTP response received for the primary request.

Show response fields

type

string

Always "response".

url

string

Response URL (may differ from request URL after redirects).

number

Timestamp (ms since epoch) when the response was received.

status

number

HTTP status code, e.g. 200.

statusText

string

HTTP status text, e.g. "OK".

headers

object

Response headers as key-value pairs.

timing

object

Puppeteer ResourceTiming object with detailed timing breakdown. null if not available.

remoteAddress

object

Server IP and port the browser connected to.

securityDetails

object

TLS certificate details: issuer, protocol, subjectName, subjectAlternativeNames, validFrom, validTo. null for non-HTTPS responses.

scanOptions

object

The ScanOptions used for this scan (mirrors the top-level options field).

scannerConfig

object

A safe excerpt of the scanner’s configuration at the time of the scan. Sensitive fields such as API keys are excluded.

Show scannerConfig fields

string

User-agent string used by the browser.

lang

string

Browser language setting.

useStealth

boolean

Whether stealth mode was enabled.

Whether cookie consent prompts were automatically dismissed.

Example Scan Response

{
  "id": "abc123xyz789",
  "slug": "example.com-1714000000",
  "url": "https://example.com",
  "status": "done",
  "created": "2024-04-25T10:00:00.000Z",
  "updated": "2024-04-25T10:00:12.000Z",
  "errorMessage": "",
  "html": ["file_id_html_abc", "file_id_trace_xyz"],
  "screenshots": ["file_id_screenshot_abc"],
  "files": [],
  "done_at": "2024-04-25T10:00:12.000Z",
  "final_url": "https://example.com/",
  "options": {
    "rate": "balanced"
  },
  "scanData": {
    "version": "1.1",
    "document": {
      "title": "Example Domain",
      "url": "https://example.com/",
      "origin": "https://example.com",
      "protocol": "h2",
      "links": ["https://www.iana.org/domains/example"]
    },
    "request": {
      "type": "request",
      "url": "https://example.com/",
      "headers": { "user-agent": "Mozilla/5.0 ..." },
      "method": "GET",
      "resourceType": "document",
      "redirectChain": [],
      "ts": 1714000001234
    },
    "response": {
      "type": "response",
      "url": "https://example.com/",
      "ts": 1714000001890,
      "status": 200,
      "statusText": "OK",
      "headers": { "content-type": "text/html; charset=UTF-8" },
      "timing": null,
      "remoteAddress": { "ip": "93.184.216.34", "port": 443 },
      "securityDetails": {
        "issuer": "DigiCert TLS RSA SHA256 2020 CA1",
        "protocol": "TLS 1.3",
        "subjectName": "www.example.com",
        "subjectAlternativeNames": ["www.example.com", "example.com"],
        "validFrom": 1705968000,
        "validTo": 1737590400
      }
    },
    "scanOptions": { "rate": "balanced" },
    "scannerConfig": {
      "ua": "Mozilla/5.0 ...",
      "lang": "en-US",
      "useStealth": false,
      "useSkipCookiePrompt": false
    },
    "meta": {
      "scannedByScanner": "scanner_id_001",
      "initiatedBy": "user_id_001",
      "initiatedByType": "api",
      "initiatedAt": "2024-04-25T10:00:00.000Z",
      "startedAt": "2024-04-25T10:00:01.000Z",
      "completedAt": "2024-04-25T10:00:12.000Z",
      "duration": 11000
    }
  }
}

Overview

Scans

Webhood REST API Reference — Overview and Schema

Base URL

Available Endpoints

GET /api/v1/scans — Query Parameters

POST /api/v1/scans — Request Body

HTTP Status Semantics

Scan Record Schema

ScanOptions Object

ScanData Object (ScanDataV1_1)

Example Scan Response

Build docs developers (and LLMs) love

Overview

Scans

Documentation Index

​Base URL

​Available Endpoints

​GET /api/v1/scans — Query Parameters

​POST /api/v1/scans — Request Body

​HTTP Status Semantics

​Scan Record Schema

​ScanOptions Object

​ScanData Object (ScanDataV1_1)

​Example Scan Response

Build docs developers (and LLMs) love

Base URL

Available Endpoints

GET /api/v1/scans — Query Parameters

POST /api/v1/scans — Request Body

HTTP Status Semantics

Scan Record Schema

ScanOptions Object

ScanData Object (ScanDataV1_1)

Example Scan Response