waymark

Waymark developer docs

Waymark provides public, keyless retrieval of completed agent readiness reports through JSON, Markdown, and MCP read tools.

Read completed reports through JSON, Markdown, or MCP. Public retrieval is free and needs no API key.

Overview

Report retrieval does not start a scan. The MCP server also includes scan_domain, which starts or reuses a scan. Start a scan from the homepage or POST /api/scan, then read the stored snapshot. The official number is Discovery 20 / Access 30 / Usability 40 / Payments 10. Journey never changes that number.

Public report API

GET /api/v1/report returns the latest completed report for a URL. It does not start a scan. Alias: GET /api/report. GET retrieve has idempotency: repeating a read does not start work; the snapshot changes only when a new completed scan is stored. A 200 body includes target, display_target, report_url, score, score_label, scanned_at, eligible_checks, score_breakdown, and issues[] (failed and partial only).

curl -s https://waymark.genedai.me/api/v1/report?url=https%3A%2F%2Fvercel.com

Open the same snapshot as HTML at /score/vercel.com, or as JSON at the report URL.

Cite a report

Include the domain, score, scanned_at, and report_url. The report URL serves the latest completed snapshot, so it can change after a rescan. Save the JSON or Markdown alongside a citation when you need the original evidence. A missing report is not a zero score.

Structured errors

Failures use RFC 9457 application/problem+json.

Rate limits

Scan-start routes (/api/scan, stream, checks, notify) allow 20 requests per minute per IP. Report GET allows 120 requests per minute per IP. Journey is 4 walks per 10 minutes per IP. A 429 includes Retry-After.

Versioning

The retrieve path is /api/v1/report. /api/report is the same handler. Breaking changes land on a new prefix, not a silent rewrite of v1. /openapi.json describes the current surface.

Other GET helpers that also do not start a scan: /api/score/:domain, /api/checks, /api/leaderboard, /api/badge/:domain, /openapi.json, /llms.txt. POST /api/scan and GET /api/scan/stream start or reuse a scan. POST /api/journey is a supporting walk and does not change the official number.

Authentication, webhooks, and writes

There is no API key on public reads. There are no webhooks. GET /api/leaderboard lists clean published scans, excluding degraded results. We do not publish a write retrieve API. Start a scan on the homepage or with POST /api/scan.

Do not submit private URLs. Retrieve tools must not be used to launch a scan.

CLI

A repo helper, not published to npm. Retrieve-only by default. Default origin is https://waymark.genedai.me. It prints a completed report or the browser score URL. It does not start a scan.

node scripts/waymark.mjs vercel.com
node scripts/waymark.mjs vercel.com --json

MCP

Streamable HTTP / JSON-RPC at the origin below. No key. Read-only retrieve tools that do not start a scan are waymark_get_report, waymark_get_methodology, and waymark_get_developer_docs.

https://waymark.genedai.me/api/mcp

Also available: scan_domain, get_score, get_leaderboard, discover_products, get_journey, list_checks, get_essentials.

Agent skill

The skills index is published at the well-known path. It is a catalog pointer, not a paid installer.

https://waymark.genedai.me/.well-known/agent-skills/index.json

Markdown content negotiation

Home, docs, methodology, pricing, research, and /score/{domain} answer Accept: text/markdown.

curl -H 'Accept: text/markdown' https://waymark.genedai.me/score/vercel.com

Embed and share a score badge

GET /api/badge/{domain}.svg returns the stored domain, score and grade as SVG. The suffixless route also works. Missing reports return 404; unavailable storage returns 503. Reads never start scans. Badges refresh after rescans, with up to 60 seconds of caching.

[![Waymark: vercel.com](https://waymark.genedai.me/api/badge/vercel.com.svg)](https://waymark.genedai.me/score/vercel.com)

The score page can copy badge Markdown, HTML, image URL and a dated share blurb. Keep the report link and scan timestamp when citing evidence. A badge is not a certification.

Report discovery and IndexNow

After a public, non-degraded report is durably saved, Waymark makes a best-effort IndexNow submission of its canonical score URL. Network failures never fail the scan. The dynamic sitemap uses stored scan times. Submission helps discovery by participating engines; it does not guarantee crawling, Google indexing or ranking.

Monitoring waitlist

Monitoring is not active. The score-page form saves email, domain, creation time and waitlist consent for up to 180 days; it sends no email and schedules no scans. Contact us to request removal. One-time “Email this report” remains separate.

POST /api/monitor accepts JSON {"domain":"vercel.com","email":"you@company.com","consent":true} for a completed report. A successful response has status: "waitlist". Invalid input returns 400, absent report 404, oversized request 413, rate limit 429 and storage failure 503. The best-effort limit is five requests/minute/IP per Worker instance.

Pricing

One plan: free. Public scans, stored scores, badge, board, directory, research cut, MCP, and optional journey. No checkout. No API key. See /pricing and /pricing.md.

Retrieve and cite a completed Waymark report

  1. Choose a completed report

    Find a published domain on the Board. A missing report means no completed snapshot is stored, not a score of zero.

  2. Retrieve the snapshot

    Send GET /api/v1/report?domain=vercel.com for JSON, or GET /score/vercel.com with Accept: text/markdown. These reads need no key and do not start a scan.

  3. Cite the evidence

    Include the domain, score, grade, scanned_at timestamp, and canonical report URL. Save the returned snapshot if the original evidence must be retained after later rescans.