---
title: "Agent report API, Markdown & MCP docs · Waymark"
canonical: "https://waymark.genedai.me/docs"
last-updated: "2026-09-08"
---

# Waymark developer docs

Waymark offers a free public report API, Markdown reports, and MCP tools. Report retrieval is read-only and requires no API key. The MCP server also exposes scan_domain, which starts or reuses a scan; it is not a read-only tool. The public board lists clean completed scans. There are no webhooks.

## 1. JSON report API

`GET https://waymark.genedai.me/api/v1/report?url=https%3A%2F%2Fexample.com` returns the latest completed report. It never starts a scan. GET retrieve has idempotency: repeating a read does not start work; the snapshot changes only when a new completed scan is stored.

Fields: `target`, `display_target`, `report_url`, `score`, `score_label`, `scanned_at`, `eligible_checks`, `score_breakdown` (discovery / access / usability / payments with earned, available, passing, total), and `issues[]` for failed and partial checks only (`id`, `name`, `result`, `layer`, `details`, `recommendation`).

Errors use RFC 9457 `application/problem+json` with `code`, `detail`, and `hint`:

- 400 invalid URL
- 404 no completed report
- 405 method not allowed
- 429 quota
- 503 storage unavailable

The alias `GET https://waymark.genedai.me/api/report` returns the same body.

Scan-start endpoints are unchanged and separate: `POST /api/scan`, `GET /api/scan/stream`, `POST /api/scan/checks`. Those are not the retrieve API.

See https://waymark.genedai.me/openapi.json and https://waymark.genedai.me/.well-known/api-catalog.

## Citing a snapshot

Include display_target, score, scanned_at, and report_url. The canonical URL serves the latest completed snapshot and can change after a rescan. Save the JSON or Markdown when the original evidence must be retained. A missing report is not a zero score.

## 2. Markdown URLs

Home, docs, methodology, pricing, research, and `/scan/{domain}` honor `Accept: text/markdown`. Responses use `Content-Type: text/markdown; charset=utf-8` and `Vary: Accept`. Machine-readable pricing is also at https://waymark.genedai.me/pricing.md.

## 3. MCP

Connect a Streamable HTTP client to https://waymark.genedai.me/api/mcp. Read-only tools:

- `waymark_get_report` — completed report text plus structured data
- `waymark_get_methodology` — how the score is computed
- `waymark_get_developer_docs` — this page

These tools do not start a scan. Server card: https://waymark.genedai.me/mcp/server-card. Discovery: https://waymark.genedai.me/.well-known/mcp.json and https://waymark.genedai.me/.well-known/ai-catalog.json.

## Versioning and rate limits

Stable retrieve operations live under `/api/v1`. Breaking retrieve changes would use a new major path. Report GET allows 120 requests per IP per 60 seconds. Scan-start stays at 20 scans per minute per IP. Responses send IETF `RateLimit-Policy` and `RateLimit`; 429 includes `Retry-After`.

## Authentication and writes

The documented retrieve API and MCP tools are public and read-only. These retrieve operations require no API key or OAuth scopes and provide no webhooks. The separate scan_domain MCP tool and scan-start endpoints can initiate work. Start a new scan from https://waymark.genedai.me/ in a browser (or the existing scan-start endpoints), then read the completed snapshot.

## CLI

`node scripts/waymark.mjs <domain>` prints a completed report, or tells you to open `/score/{domain}` if none exists. It does not start a scan and is not published to npm. Add `--json` for the retrieve API body.

## More

- Methodology: https://waymark.genedai.me/methodology
- Pricing: https://waymark.genedai.me/pricing.md
- Site guide: https://waymark.genedai.me/llms.txt
- OpenAPI: https://waymark.genedai.me/openapi.json

## 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.