Docs · HTTP surface

The endpoints a node serves.

Two layers: the .well-known contract every GOVP issuer publishes (protocol-level), and the REST API of the reference implementation (WordPress plugin). All read endpoints are public, CORS-open and unauthenticated — evidence must verify from anywhere.

Layer A · protocol contract

.well-known endpoints

Any conforming issuer — WordPress, CLI, or your own stack — should serve these three paths (spec §11).

GET/.well-known/govp.txt

The domain's own identity record: its public key, publisher name and metadata, as a GOVP-1 record. This is what the Canonical field of every record points at, and what a verifier pins.

# try it against this very site
curl -s https://<this-host>/.well-known/govp.txt

GET/.well-known/govp/index.json

Discovery index: the list of records this domain publishes, for crawlers, witnesses and peers.

GET/.well-known/govp/<govp-id>.govp

A single self-contained record, served as text/plain; charset=utf-8. Fetching from this URL enables the canonical-binding check (spec §10.3).

Serving rules: content-type text/plain for records, Access-Control-Allow-Origin: * on all three paths, and no authentication. If your host serves .well-known statically, make sure these paths reach your application — see the integration guide.

Layer B · reference implementation

REST API (WordPress plugin)

The reference node exposes its read surface under /wp-json/govp/v1. Other implementations may mirror it; the .well-known contract above is what conformance requires.

GET/wp-json/govp/v1/records

Paginated listing of the node's published records.

Param	Meaning
page	Page number, from 1.
per_page	Items per page; maximum 200.

$ curl -s "https://node.example/wp-json/govp/v1/records?page=1&per_page=50" -i
X-WP-Total: 132
X-WP-TotalPages: 3
# body: records + total + pages

POST/wp-json/govp/v1/verify

Server-side verification fallback: submit a record and receive the per-check verdict. Used by browsers without WebCrypto Ed25519, so verification never fails "because of the browser". The server runs the same libsodium check the self-test conformance-proves.

GET/wp-json/govp/v1/badge?id=<govp-id>

Public badge data for a record — what govp-badge.js renders. Exposes only public record metadata.

Cross-cutting behavior

Aspect	Behavior
CORS	Access-Control-Allow-Origin: * on read endpoints, deliberately — evidence is public and must verify from any origin. No secrets are served.
Auth	None for reads. Issuing and administration are authenticated inside the platform, never over this surface.
Rate limits	Per-IP limiting on public endpoints; configurable, can be disabled.
Outbound calls	All node-initiated HTTP (verification, discovery, witnesses, TSA) goes through one hardened client: public IPs only, no redirects, anti-rebinding IP pinning, scheme/port allowlist.
Errors	Standard HTTP status codes; verification responses always carry the per-check breakdown, never a bare boolean.

Download OpenAPI JSON Schema Integration guide How nodes form the mesh GOVP-1 spec