API reference

The Quidnug node exposes a RESTful HTTP API, versioned at /api/v1 (core primitives) and /api/v2 (guardians, gossip, bootstrap, Merkle proofs).

All SDKs (Python, Go, JS/TS, Rust) are thin wrappers over this API. Direct curl calls work for anything the SDKs expose.

Authoritative specs

• OpenAPI 3.0, docs/openapi.yaml
• Postman collection, docs/postman/quidnug.postman_collection.json
• Canonical bytes spec, schemas/types/canonicalization.md

Core endpoints

Identities

Method	Path	Purpose
POST	/api/identities	Create or update a quid.
GET	/api/identities/{quidId}	Fetch a quid’s current metadata.

Trust

Method	Path	Purpose
POST	/api/trust	Declare a trust edge.
GET	/api/trust/{truster}/{trustee}	Query trust (observer-centric).
DELETE	/api/trust/{truster}/{trustee}/{domain}	Revoke a trust edge.

Titles

Method	Path	Purpose
POST	/api/titles	Mint or transfer a title.
GET	/api/titles/{titleId}	Fetch title state + ownership.

Events

Method	Path	Purpose
POST	/api/events	Append an event to a subject’s stream.
GET	/api/events?subjectId=…	Read events by subject, paginated.

Anchors + guardians (key lifecycle)

Method	Path	Purpose
POST	/api/anchors	Rotate or invalidate an epoch.
POST	/api/v2/guardians/sets	Install/replace a guardian quorum.
POST	/api/v2/guardians/recoveries/init	Initiate recovery.
POST	/api/v2/guardians/recoveries/veto	Veto an in-flight recovery.
POST	/api/v2/guardians/recoveries/commit	Commit after time-lock.
POST	/api/v2/guardians/resign	Resign from a guardian set (prospective).

Operational

Method	Path	Purpose
GET	/api/health	Liveness + readiness probe.
GET	/api/info	Node version, feature flags.
GET	/metrics	Prometheus scrape endpoint.

Error codes

See the error codes reference.