One evidence architecture, multiple public interfaces

Architecture: Evidence → Interpretation → Decision

Discovery and formal contracts

/machine-use.json is the machine-readable capability-discovery document. /docs/openapi.yaml is the formal OpenAPI 3.1 contract. Human documentation explains purpose, evidence meaning, examples, and limits.

Evaluate — authoritative assessment resolution by scope

GET /evaluate/example.com
GET /evaluate.php?domain=example.com&format=json
GET /evaluate.php?url=https%3A%2F%2Fexample.com%2Fpage&format=json

Evaluate resolves a supported normalized root/domain or exact-URL scope through the authoritative GoGuides evaluation path. Root/domain and exact-page scopes can legitimately differ. The same normalized scope should not receive conflicting GoGuides values from different public interfaces.

Depending on the record, Evaluate can expose identity, AI Rank, grade, trust state, eligibility/policy context, verification context, freshness, history links, provenance, machine-use context, and links to related evidence surfaces.

Batch Evaluate — transport changes, authority does not

/evaluate-batch reduces network round trips for exact-URL evaluation. Every item still resolves through the same exact-URL evaluation authority used by single Evaluate. Batch transport does not create a second scoring or policy system.

Web State V3 — latest supported stored observation

GET /state/example.com

Web State exposes stored objective evidence for supported fields such as text similarity, structured-data state, schema-type state, normalized headers, word count, internal and external link counts, outbound-link fingerprints, AI-policy state, and observation metadata.

Conditional absence is not zero. Consumers should preserve omitted/unknown states rather than manufacturing replacement values.

Change Intelligence V1 — deterministic longitudinal comparison

GET /changes/example.com

Change Intelligence compares supported stored observation pairs. It can expose exact observation identifiers/timestamps, mechanical field-change flags, simhash distance where defined, and numeric deltas where supported.

URL Request — explicit attributed request intent

POST /request-url
GET  /request-url/status/{request_id}

URL Request lets a client explicitly request GoGuides intelligence for one public URL and follow the public request lifecycle. The caller records request intent; it does not write the resulting GoGuides observation or assessment.

A usable result can be returned immediately. An accepted asynchronous request can return a public request ID, status URL, and retry guidance under the documented contract.

Verification, profile, and history

Claim Support — bounded model-assisted analysis

POST /claim-support
GET  /claim-support/status/{analysis_id}
POST /claim-support/feedback

Claim Support analyzes one caller claim against one fixed stored source observation. The source observation remains evidence; the verdict is a separate model-assisted analysis record. Feedback is governance input, not truth voting, and lifecycle status does not erase historical output.

Content Relationships — conservative exact-URL comparison

Content Relationships uses stored evidence to compare two exact public URLs. Relationship evidence can establish supported similarity or other documented states without proving common ownership, coordination, deception, copying intent, or publisher motive.

Verified Text — source attribution and integrity

GET /verified-text.php?q=gravity&format=json

Verified Text exposes source-attributed normalized text with record identifiers, source and license metadata, canonical record links, and SHA-256 integrity values. A successful hash check establishes integrity against the stored normalized record, not factual truth.

Signal and AI Discovery — lightweight discovery surfaces

/signal.json and /ai-discovery help automated consumers discover relevant GoGuides records and deeper evidence surfaces. They are not substitutes for the authoritative scope-specific evaluation and evidence endpoints.

Favicon North Star — deterministic record-state visualization

The GoGuides favicon is a compact deterministic visualization of supported resolved record-state inputs. The same supported inputs should produce the same output.

Source-use context is not universal clearance

GoGuides can publish granular source-use context for actions such as reading, summarizing, citation, recommendation, transactions, and sensitive advice. Those fields are GoGuides decision context under its methodology. Another system remains responsible for its own source-use policy.

What these endpoints do not prove

• A crawler request does not prove indexing, training, retrieval, citation, recommendation, or reliance.
• Verification does not prove every published claim is true.
• A high AI Rank does not override a consumer's policy or safety rules.
• A deterministic comparison does not establish publisher intent.
• A hash match establishes integrity against its defined record, not factual correctness.
• A GoGuides assessment does not require another system to reach the same conclusion.

Endpoint quick reference

Related resources