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.

All Webhood API endpoints — both /api/v1/ and the legacy /api/beta/ — require a valid Bearer token passed in the Authorization header. Requests that omit the header, or supply an invalid or expired token, receive a 401 Unauthorized response. There are two ways to obtain a token: a short-lived session token via the PocketBase auth endpoint, or a long-lived API token created in the Webhood UI for programmatic access.

​
Step 1 — Obtain a Session Token

You can authenticate as a Webhood user and receive a session token by calling the PocketBase auth-with-password endpoint directly: 
curl -X POST http://localhost:8000/api/collections/users/auth-with-password \
  -H 'Content-Type: application/json' \
  -d '{"identity": "user@example.com", "password": "yourpassword"}'
A successful response includes a token field: 
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "record": {
    "id": "abc123",
    "email": "user@example.com",
    "role": "admin"
  }
}
Extract the token value and use it as your Bearer token in subsequent requests. Session tokens are shorter-lived than API tokens and are better suited for interactive or one-off use. For automation and programmatic access, create a dedicated API token through the Webhood UI:
  1. Log in to the Webhood web interface.
  2. Navigate to Settings → Accounts.
  3. Create a new API token and copy the generated value.
API tokens are valid for 1 year from creation and are stored in the api_tokens PocketBase collection with the scanner role.
API tokens are stored in the api_tokens PocketBase collection. Each token record includes an expires field (ISO 8601) and a role field. Tokens created through the Webhood UI carry the scanner role, which is required to authenticate against all /api/v1/ endpoints. Tokens generated specifically for scanner instances (internal scanner agents) also carry the scanner role, but are linked to a scanner configuration record rather than being free-standing.
API tokens are long-lived (valid for 1 year). Treat them like passwords — do not commit them to source control or share them in plaintext. If a token is compromised, revoke it immediately by navigating to Settings → Accounts in the Webhood UI and deleting the token record.

​
Step 3 — Use the Token in Requests

Pass your token (session or API) as a Bearer token in the Authorization header on every request: 
curl http://localhost:8000/api/v1/scans \
  -H 'Authorization: Bearer <your-token>'
The Authorization: Bearer <token> header is required on all /api/v1/ and /api/beta/ endpoints. There is no cookie-based or query-parameter authentication for the REST API.

​
Required Header

​
Authorization
string
required
Bearer token for authentication. Format: Bearer <your-token>. Required on every /api/v1/ and /api/beta/ request.

​
Scanner Tokens

The Webhood scanner agent uses a token type with the scanner role. These tokens are generated via the admin route: 
POST /api/beta/admin/scanner/:id/token
This route requires a logged-in user with the admin role. It creates a 1-year JWT signed with the api_tokens record’s token key. Scanner tokens are intended for internal use by the scanner process, though they carry the same scanner role required to call all /api/v1/ endpoints.
The /api/v1/ endpoints require RequireRecordAuth("users", "api_tokens") combined with RequireCustomRoleAuth("scanner"). This means the caller must be authenticated as either a users or api_tokens collection record, and that record’s role field must equal scanner. PocketBase admins bypass the role check entirely. Regular users records with role admin or user can access the /api/ui/ internal routes but not /api/v1/ directly unless their role is scanner.

​
Full Example — Submit a Scan

The following example shows a complete authenticated request to submit a URL for scanning using an API token: 
curl -X POST http://localhost:8000/api/v1/scans \
  -H 'Authorization: Bearer <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com"}'
A successful submission returns 202 Accepted with the new scan record in the response body: 
{
  "id": "abc123xyz789",
  "slug": "example.com-1714000000",
  "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": null,
  "scanData": null
}
Poll GET /api/v1/scans/:id with the same Authorization header until the response status changes from 202 Accepted (scan in progress) to 200 OK (scan complete).
Store your API token in an environment variable (e.g. WEBHOOD_TOKEN) rather than hard-coding it in scripts. Then reference it as -H "Authorization: Bearer $WEBHOOD_TOKEN" in your curl commands or as a secret in your CI/CD pipeline.

Build docs developers (and LLMs) love

Get started for freeTalk to us