# HostedScan Documentation > Technical documentation for HostedScan (https://hostedscan.com), an online vulnerability scanning platform with a REST API. Every guide below is linked as a plain-markdown URL (the page route plus `.md`) — prefer those over the HTML pages. The interactive API reference lives at https://docs.hostedscan.com/api/. Agent skills for working with HostedScan are published at https://docs.hostedscan.com/.well-known/skills/index.json. If you are an agent integrating the HostedScan API, load the `hostedscan-api` skill or read the "Instructions for LLM agents" section below before writing code — do not rely on memorized API shapes. ## Getting started - [Introduction](https://docs.hostedscan.com/index.md): Platform overview — scanners, dashboards, alerts, and reports. - [Developer API + Webhooks](https://docs.hostedscan.com/developer-api.md): Entry point for programmatic access. - [AI Agents guide](https://docs.hostedscan.com/ai-agents.md): How to find and use HostedScan's llms.txt files, markdown docs, and agent skills. - [API reference](https://docs.hostedscan.com/api/): Full REST API reference (Redoc, HTML only), generated from the OpenAPI spec. ## Scanning guides - [API scanning](https://docs.hostedscan.com/api-scanning.md): Import an OpenAPI/Swagger definition and scan every endpoint of a REST API with the ZAP scanner. - [Agent-based scanning](https://docs.hostedscan.com/endpoint-agent-scanning.md): Install lightweight Nessus agents on laptops, desktops, and servers, including devices behind firewalls. ## Authenticated scanning Scan behind the login page of websites and web applications with the ZAP scanner. - [Header authentication](https://docs.hostedscan.com/authenticated-scanning/header.md): Authenticate scans with Basic Auth, bearer tokens, or other custom request headers. - [Session cookie](https://docs.hostedscan.com/authenticated-scanning/session-cookie.md): Authenticate scans with a fixed session cookie — best for one-time scans since cookies expire. - [Recorded login](https://docs.hostedscan.com/authenticated-scanning/recorded-login.md): Record a Selenium login sequence for playback during scans — the most flexible method, works with complex login flows. - [Selenium troubleshooting](https://docs.hostedscan.com/authenticated-scanning/recorded-login/selenium-troubleshooting.md): Diagnose recorded-login playback failures using logs and screenshots. ## Internal network scanning - [Internal network scanning](https://docs.hostedscan.com/internal-network-scanning.md): Run the HostedScan Internal Scanner inside your network — no open ports or tunnels required — with centralized management and reporting. - [Install the Internal Scanner on Linux](https://docs.hostedscan.com/internal-network-scanning/install-agent-on-linux.md): Installation steps for x64 and ARM Linux systems. - [Authenticated OpenVAS scanning](https://docs.hostedscan.com/internal-network-scanning/authenticated-scanning.md): Let the internal scanner log into systems for deeper, credentialed vulnerability checks. ## SAML single sign-on - [SAML SSO overview](https://docs.hostedscan.com/saml-sso.md): SAML 2.0 SSO with your existing identity provider. - [Integration steps](https://docs.hostedscan.com/saml-sso/integration-steps.md): Generic IdP setup walkthrough. - [Microsoft Entra ID](https://docs.hostedscan.com/saml-sso/microsoft-entra.md): Step-by-step Entra ID (Azure AD) configuration. - [Automatic provisioning](https://docs.hostedscan.com/saml-sso/automatic-provisioning.md): Create accounts automatically on first SAML login. ## Vulnerability management - [Advanced risk acceptance rules](https://docs.hostedscan.com/vulnerability-management/advanced-rules.md): Bulk-accept expected or low-priority findings with rule-based matching to reduce noise. - [Health score modeling](https://docs.hostedscan.com/vulnerability-management/health-score-modeling.md): How target health scores are computed from open risks. ## Instructions for LLM agents: integrating the HostedScan API The API base URL is `https://api.hostedscan.com/v1`. Authenticate every request with the `X-HOSTEDSCAN-API-KEY` header — not an `Authorization: Bearer` header. Users create API keys in the dashboard at https://hostedscan.com/settings/api; the developer API and webhooks require a Premium or higher plan. To explore the API with sample data before using a real key, use the literal API key `test-data-key` — it returns realistic sample responses for the targets, scans, scheduled scans, risks, and sources endpoints (result downloads return a sample PDF; reports, result uploads, OpenAPI uploads, and stopping scans are not stubbed and need a real key). Scans are asynchronous. `POST /v1/scans` requires a `type` and exactly one of `targets` (raw values like `example.com`), `target_ids`, or `tags`, and returns immediately. Poll `GET /v1/scans/{id}` until the scan reaches a terminal state (`SUCCEEDED`, `FAILED`, `STOPPED`, or `OVER_LIMIT`); risks and result files are only available once the state is `SUCCEEDED`. Scans routinely take from minutes to many hours depending on scanner and target — see [How long will a scan take?](https://help.hostedscan.com/help/how-long-will-a-scan-take) and [Long running scans are normal](https://help.hostedscan.com/help/long-running-scans-are-normal) — so prefer webhooks over tight polling loops. Webhook endpoints are registered at https://hostedscan.com/settings/api, must use HTTPS with a signed certificate, and receive `scan.created`, `scan.updated`, `risk.created`, and `risk.updated` events (`data` is the Scan or Risk object — treat a `scan.updated` whose `data.state` is `SUCCEEDED`, `FAILED`, `STOPPED`, or `OVER_LIMIT` as the scan finishing, and fetch risks and results only for `SUCCEEDED`). The deprecated `scan.succeeded`, `risk.opened`, and `risk.closed` events are still delivered for compatibility and should be ignored. The scan `type` must be one of: `NMAP`, `NMAP_UDP`, `OPENVAS`, `OWASP_ZAP`, `OWASP_ZAP_ACTIVE`, `SSLYZE`, `NUCLEI`, `NESSUS`. `NESSUS` requires the Professional plan. When creating targets programmatically, pass `?upsert=true` on `POST /v1/targets` to avoid duplicate-target errors on re-runs. Reports are a two-step flow: `POST /v1/reports` with `{"report_format": "PDF" | "HTML" | "CSV"}` (optionally `targets_filter` with `target_ids`, `tags`, or `label`, and `risks_filter`) returns a report `id`; then `GET /v1/reports/{id}?format=` downloads the file. The `format` parameter defaults to `PDF`, so pass the format used when creating the report. If scans return fewer findings than expected, check that HostedScan's scanner IP addresses are allowlisted in firewalls and WAFs: [What IP addresses are used for the HostedScan vulnerability scanners?](https://help.hostedscan.com/help/what-ip-addresses-are-used-for-the-hostedscan-vulnerability-scanners) ## Help center - [Help center home](https://help.hostedscan.com/): Knowledge base with all support articles. - [How can I fix an unreachable target?](https://help.hostedscan.com/help/unreachable-targets): Troubleshooting targets that scans cannot reach. - [Why did a scan return a cached result?](https://help.hostedscan.com/help/cached-scan-results): When and why recent scan results are reused. - [What is Quality of Detection (QoD) in OpenVAS scans?](https://help.hostedscan.com/help/what-is-quality-of-detection-qod-in-openvas-scans): How OpenVAS scores detection reliability. - [Can HostedScan run internal network scans?](https://help.hostedscan.com/help/can-hostedscan-run-internal-network-scans): Options for scanning private networks. ## Optional - [HostedScan marketing site llms.txt](https://hostedscan.com/llms.txt): Product, pricing, and scanner overview links. - [Pricing](https://hostedscan.com/pricing): Plans and target-based pricing. - [Sign up](https://hostedscan.com/sign-up): Create an account — direct sign-ups (email magic link or OAuth login) start a 14-day free trial of the Premium plan. - [Status page](https://status.hostedscan.com/): Live service status. - Support: hello@hostedscan.com