canonical: https://jentic.com/apis/observatory.mdn.mozilla.net/observatory-mdn-mozilla

# Observatory Mdn Mozilla Mozilla Observatory API

The Mozilla Observatory API scans public websites for HTTP security headers and configuration best practices, returning a letter grade and per-test results. It checks Content-Security-Policy, Strict-Transport-Security, X-Frame-Options, cookie flags, referrer policy, redirection behaviour, and other transport-layer hardening signals. Maintained by Mozilla as part of the MDN Web Docs platform, the API powers the public Observatory scanner at observatory.mozilla.org.

## For AI agents

Trigger HTTP header security scans on a hostname and retrieve a graded report of policy and configuration findings.

## Scope

Does not handle TLS cipher analysis, malware detection, or content-level vulnerability scanning - use for HTTP security header grading only.

## Capabilities

- Trigger an HTTP header security scan against a public hostname and receive a graded result
- Retrieve a numeric score and letter grade summarising the target's security posture
- Inspect per-test outcomes for Content-Security-Policy, HSTS, cookie flags, and clickjacking protections
- Detect missing or misconfigured Strict-Transport-Security and Subresource Integrity policies
- Audit a portfolio of domains for transport-layer hardening before launch or release
- Monitor production sites for regressions in security header configuration over time

## Use cases

### Pre-Launch Security Header Audit

Audit a website's HTTP security headers before public launch by submitting the hostname to the Observatory scanner and reviewing the per-test breakdown. The API returns a graded report that highlights missing or weak Content-Security-Policy, HSTS, X-Frame-Options, and cookie flag configurations so engineering teams can fix issues before exposing the site to traffic. A full scan completes in under a minute and requires no authentication.

Example prompt: Submit a scan for hostname example.com and return the overall grade plus the list of failed tests with their descriptions.

### Continuous Header Regression Monitoring

Run scheduled Observatory scans against production hostnames to detect when a deployment removes or weakens an HTTP security header. The graded score makes it easy to alert on any drop, and per-test results pinpoint the exact policy that regressed. Useful for security engineering teams that want a free, public, vendor-neutral signal alongside their internal monitoring.

Example prompt: Run a scan for hostname app.example.com and flag any test where the result changed from PASS to FAIL versus the previous run.

### Bulk Domain Security Triage

Scan a list of domains across an organisation's public footprint to produce a security-posture leaderboard. Each scan returns a numeric score and grade that can be aggregated across hundreds of hostnames to prioritise remediation work. The API has no API key requirement, making bulk use straightforward subject to Mozilla's rate limits.

Example prompt: Iterate over a list of 50 hostnames, submit a scan for each, and return a sorted table of hostname, grade, and score.

### AI Agent Security Triage Workflow

An AI agent can call the Observatory API as part of a wider security-triage workflow - for example, after an SBOM check or a TLS scan - to confirm that a site's HTTP layer is hardened. Through Jentic the agent discovers the scan operation by intent, loads the schema, and submits the hostname without dealing with raw HTTP plumbing. Results are returned as structured JSON ready to feed into a downstream report.

Example prompt: Use Jentic to find the Observatory scan operation, execute it for hostname example.com, and produce a markdown summary of the grade and any failing tests.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/scan` | Trigger a new HTTP header security scan for a hostname |

## Key resources

- **Scan** — Submit a hostname for HTTP header security analysis and receive a graded report with per-test outcomes.

## Why Jentic

- **Setup:** Wiring the Mozilla Observatory API by hand means pointing at observatory-api.mdn.mozilla.net, respecting Mozilla's public-service rate limits, and coding your own retry handling for the scan endpoint. Through Jentic you install once, import the Mozilla Observatory API from the API Directory, and your agent calls it, with no key to manage because the endpoint is unauthenticated.
- **Permission scoping:** Observatory exposes a single scan operation that grades HTTP security headers, so scope it by operation: limit the agent to that scan call and nothing else. You choose which operations it may call, so no other behaviour runs unless you add it.
- **Credential handling:** The Observatory scan endpoint is unauthenticated, so there is no key for your Jentic One instance to store. Jentic still applies its own request-policy controls at execution time so agents respect Mozilla's public-service rate limits.
- **Discovery method:** Agents search Jentic by intent such as 'scan a website for security headers', and Jentic returns the Observatory /scan operation with its input schema so the agent calls the right endpoint without browsing MDN docs.

## Related APIs

- **SSL Labs API** — TLS handshake, certificate, and cipher analysis for a hostname
- **Shodan API** — Internet-wide host and service intelligence
- **BuiltWith API** — Technology fingerprinting for any public website

## FAQ

### What authentication does the Mozilla Observatory API use?

The Observatory v2 scan endpoint at observatory-api.mdn.mozilla.net/api/v2 is open and does not require an API key. Through Jentic the call is routed without credentials, but Jentic still applies its own rate-limit and request-policy controls so agents do not flood the public service.

### Can I scan any public hostname with the Observatory API?

Yes. Submit a POST to /scan with the target hostname and Mozilla's scanner will fetch the site and evaluate its HTTP headers. The host must be publicly reachable over HTTPS - internal or authentication-gated origins cannot be analysed.

### What are the rate limits for the Mozilla Observatory API?

Mozilla does not publish a hard quota in the spec, but the public scanner is intended for reasonable use - keep concurrent scans low and avoid re-scanning the same host more than once every few minutes. Cache results on your side rather than re-running scans for unchanged sites.

### How do I trigger an Observatory scan through Jentic?

Search Jentic for 'scan a website for security headers', load the schema for the /scan operation, then execute with the target hostname as the input. The Python SDK pattern is await client.search(...), await client.load(...), await client.execute(...) inside an asyncio.run wrapper.

### Is the Mozilla Observatory API free to use?

Yes. The Observatory is a free service operated by Mozilla as part of MDN Web Docs and there is no paid tier. Treat it as a community resource and do not use it as a substitute for a hosted security-monitoring product when running thousands of scans per hour.

### Does the Observatory check TLS configuration as well as headers?

No - the v2 scan focuses on HTTP-layer headers and policy configuration. For full TLS handshake and cipher analysis, pair this API with a TLS scanner such as the SSL Labs API, which Jentic also indexes.

### Can I limit what my agent is allowed to do with the Mozilla Observatory API?

Yes. Because you run Jentic One yourself, your own rules decide which operations and credentials the agent may use. The Mozilla Observatory API exposes a single scan operation that grades a hostname's HTTP security headers, so you scope the agent to that scan call and nothing else runs unless you add it. Since the scan endpoint is unauthenticated there is no key to hand over, and your self-hosted instance still applies request-policy controls so the agent respects Mozilla's public-service rate limits.