Lighthouse Audit Skill

Run Lighthouse audits and retrieve performance, accessibility, best-practices, and SEO issues for any website using the Foghorn API.

Overview

Foghorn is a site-health monitoring service built on Lighthouse. You register a site, Foghorn crawls its sitemap, audits every page, and exposes the results through a REST API. This skill lets you interact with that API using curl.

Base URL: https://foghorn-api.artgaard.workers.dev

Authentication

All endpoints (except sign-up, sign-in, and health check) require a Bearer token in the Authorization header.

Step 1 — Check for a stored API key

Read ~/.foghorn. If the file exists and its contents start with fh_, you already have a valid API key. Set the auth header and skip to Setup Workflow:

AUTH="Authorization: Bearer <key from ~/.foghorn>"

Step 2 — First-time setup (only if ~/.foghorn is missing or empty)

If no stored key is found, ask the user for their email and password, then run through sign-up, sign-in, and key creation.

Sign up (first time only)

curl -s -X POST https://foghorn-api.artgaard.workers.dev/auth/sign-up \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"min8chars"}'

Sign in (get a JWT)

curl -s -X POST https://foghorn-api.artgaard.workers.dev/auth/sign-in \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"min8chars"}'

Returns { "token": "eyJ...", "expiresIn": 86400, "user": {...} }.

Create an API key

curl -s -X POST https://foghorn-api.artgaard.workers.dev/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent-key"}'

Returns the full key once in apiKey.key.

Save the key

Write the fh_... key to ~/.foghorn so it is reused in future sessions. Then set the auth header:

AUTH="Authorization: Bearer <key>"

Setup Workflow

Before you can retrieve issues you need a team and a site.

1. Create a team

curl -s -X POST https://foghorn-api.artgaard.workers.dev/teams \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Team"}'

2. Add a site

curl -s -X POST https://foghorn-api.artgaard.workers.dev/sites \
  -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"teamId":"TEAM_ID","domain":"www.example.com"}'

The sitemapPath defaults to /sitemap.xml. Override it if your sitemap lives elsewhere.

3. Wait for the crawl

Foghorn periodically scrapes sitemaps and audits discovered pages. Check progress:

curl -s https://foghorn-api.artgaard.workers.dev/sites/SITE_ID \
  -H "$AUTH"

When hasScrapedTheSitemap is true, the sitemap has been processed. Then check pages:

curl -s "https://foghorn-api.artgaard.workers.dev/pages?siteId=SITE_ID" \
  -H "$AUTH"

Pages with a non-null lastAuditedAt have completed audits.

Querying Issues

The /issues endpoint aggregates audit failures across all audited pages.

# All issues for a site
curl -s "https://foghorn-api.artgaard.workers.dev/issues?siteId=SITE_ID" \
  -H "$AUTH"

# Filter by category
curl -s "https://foghorn-api.artgaard.workers.dev/issues?siteId=SITE_ID&category=accessibility" \
  -H "$AUTH"

Categories: performance, accessibility, bestPractices, seo

Response shape

{
  "issues": [
    {
      "auditId": "uses-responsive-images",
      "title": "Properly size images",
      "category": "performance",
      "pages": [
        {
          "pageId": "page-id",
          "url": "https://www.example.com/about",
          "path": "/about",
          "score": 0.45,
          "displayValue": "Potential savings of 120 KiB"
        }
      ]
    }
  ]
}

• •Issues are sorted by number of affected pages (most widespread first).
• •Pages within each issue are sorted by score ascending (worst first).
• •Scores range from 0 (fail) to 1 (pass).

Searching Pages

Find specific pages by URL or path using regex search:

curl -s "https://foghorn-api.artgaard.workers.dev/pages?siteId=SITE_ID&search=blog" \
  -H "$AUTH"

Quick Reference

See references/api-reference.md for full request/response schemas.