Integration Guide for AI and Crawlers

What the GoGuides Trust Layer Provides

GoGuides publishes public records designed to remain inspectable across crawls, updates, ownership changes, and changes in a website's current status. A consuming system can use these records as independent evidence while continuing to apply its own ranking, safety, and trust policies.

How to Interpret GoGuides Evidence

GoGuides publishes both observed or normalized web evidence and GoGuides-derived assessments. These are different categories of information and should not be treated as interchangeable.

GoGuides Machine-Readable Endpoint Overview

Workflow 1: Discover the Public Machine Endpoints

curl -sS \
  'https://www.goguides.com/machine-use.json'

Independent Comparison for Exact URLs

Exact-URL Evaluate may include an independent_comparison object with capability goguides.independent_comparison and API version comparison-v1.

The current deterministic classifier is publisher-declaration-v2. It separates the factual observation that a publisher made a claim from the separate question of whether that claim can responsibly be compared with GoGuides' independently derived exact-page assessment.

{
  "independent_comparison": {
    "capability_id": "goguides.independent_comparison",
    "api_version": "comparison-v1",
    "classification_method": "deterministic_ruleset",
    "classification_version": "publisher-declaration-v2",
    "declaration_state": "ambiguous_namespace_trust_claim",
    "directly_comparable": false,
    "observation": {
      "score_scope": "exact_page",
      "score_derivation": "independently_page_computed",
      "source_scope": "stored_exact_requested_url_observation",
      "comparison_eligible": false
    },
    "source_alignment": {
      "method": "exact_url_rank_status_title_text_hash_v1",
      "aligned": true,
      "reason_code": "CRYPTOGRAPHIC_SNAPSHOT_MATCH"
    },
    "comparison": null,
    "abstained": true
  }
}

Workflow 2: Batch Evaluate Multiple Exact URLs

GET + POST /evaluate-batch exposes capability goguides.evaluate_batch using API version evaluate-batch-v1. Both transports call one internal service and reuse normal exact-URL Evaluate authority.

GET example

curl -sS --get \
  --data-urlencode 'url=https://www.goguides.com/data-license' \
  --data-urlencode 'url=https://www.iana.org/help/example-domains' \
  'https://www.goguides.com/evaluate-batch'

POST example

curl -sS \
  -H 'Content-Type: application/json' \
  --data '{"urls":["https://www.goguides.com/data-license","https://www.iana.org/help/example-domains"]}' \
  'https://www.goguides.com/evaluate-batch'

V1 applies bounded public request, input, and response limits. Clients that reach a public limit receive a structured error or retry guidance. Operational queue, cooldown, and emergency-control details remain internal.

Focused documentation: /docs/evaluate-batch.html.

Claim Support V1 — source-grounded model-assisted judgment

POST /claim-support analyzes one claim against one fixed current GoGuides stored source observation. The capability is goguides.claim_support and the API version is claim-support-v1.

Verdicts are supported, contradicted, unaddressed, insufficient_evidence, and source_unavailable. This is model-assisted analysis, not a certificate of truth, not cryptographic verification, and not a replacement for independent review.

curl -sS \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{"url":"https://www.goguides.com/data-license","claim":"GoGuides publishes a data license."}' \
  'https://www.goguides.com/claim-support'

Claim Support uses stored GoGuides evidence and does not synchronously fetch the target website. It does not create explicit POST /request-url adoption. Unknown or unavailable sources abstain and can be followed through Evaluate or Request URL as a separate caller-controlled workflow.

Responses use Cache-Control: no-store. V1 exposes no public numeric model confidence and does not publish private model, prompt, threshold, queue, or abuse-control internals.

Claim Support Feedback V1 — bounded governance feedback

POST /claim-support/feedback records structured feedback about one existing Claim Support analysis_id. The capability is goguides.claim_support_feedback and the API version is claim-support-feedback-v1.

curl -sS \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{"analysis_id":"gca_...","reason_code":"evidence_mismatch"}' \
  'https://www.goguides.com/claim-support/feedback'

Accepted reason codes are verdict_disputed, evidence_mismatch, source_mismatch, source_stale, insufficient_context, and analysis_other_issue. Repeated equivalent feedback may be deduplicated.

Feedback is a review signal, not a vote on truth. Submission does not automatically change the original verdict, source observation, or analysis lifecycle state.

Claim Support Status V1 — durable analysis lifecycle

GET /claim-support/status/{analysis_id} reports the current lifecycle state of one previously issued Claim Support analysis. The capability is goguides.claim_support_status and the API version is claim-support-status-v1.

States are active, flagged, superseded, and withdrawn. A superseded record can point to a public replacement analysis. A withdrawn record can expose a safe reason category.

Status polling is observational only. It does not crawl the source, create a URL Request, trigger re-analysis, or rewrite the historical verdict. Persisted verdicts are versioned analysis results rather than permanently current truth, so consumers should re-check lifecycle status according to their own risk and freshness needs.

Workflow 2: Request GoGuides Intelligence for a URL

For a client whose operator, application, integration, or tool policy has explicitly authorized this capability, POST /request-url provides GoGuides intelligence for a full public HTTP or HTTPS URL. This is the explicit URL-request surface for crawl-on-miss behavior, with request attribution and status tracking. Domain/root Evaluate can act as a demand signal: eligible machine lookups may asynchronously schedule domain discovery or contribute to throttled hot-recrawl freshness for a known record. For an eligible machine exact-URL lookup that misses stored page intelligence, GoGuides asynchronously schedules both the authoritative domain root and the requested exact URL. Ordinary non-machine exact-URL reads do not create crawl work. POST /request-url remains the explicit attributed acquisition and status workflow. State and Changes return stored observations; freshness maintenance is asynchronous.

Request example

curl -sS \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"url":"https://example.com/article","freshness":"use-current-or-crawl-on-miss"}' \
  'https://www.goguides.com/request-url'

Full contract and examples: URL Request API documentation · OpenAPI specification

Workflow 3: Inspect a Specific Domain Trust Record

Use the evaluation endpoint when the task concerns a named domain. Unlike the general /signal.json sample, this request explicitly selects the domain being evaluated. When deeper objective state evidence is needed, inspect the returned state_url and follow it to the Web State V3 endpoint.

curl -sS \
  'https://www.goguides.com/evaluate.php?domain=goguides.com&format=json'

Workflow 4: Follow Evaluate to Web State V3

Domain evaluation provides the decision-oriented record. Its state_url points to the compact JSON-only Web State endpoint when a consuming system needs deeper objective evidence about the latest observation.

curl -sS \
  'https://www.goguides.com/evaluate.php?domain=goguides.com&format=json'

curl -sS \
  'https://www.goguides.com/state/goguides.com'

Workflow 5: Inspect Historical Change Intelligence

Use /changes/{domain} when the task is not merely to inspect the latest state, but to determine what changed between consecutive stored observations of the same requested URL.

curl -sS   'https://www.goguides.com/changes/goguides.com?limit=10'

Workflow 6: Follow the Public Trust Record

A domain evaluation provides the current machine-readable result. Web State provides deeper objective observation evidence, while the profile and history routes provide the surrounding public record needed to understand what that result represents, including available verification evidence.

curl -sS \
  'https://www.goguides.com/evaluate.php?domain=goguides.com&format=json'

curl -sS \
  'https://www.goguides.com/state/goguides.com'

curl -sS \
  'https://www.goguides.com/profile/goguides.com'

curl -sS \
  'https://www.goguides.com/history/goguides.com'

Workflow 7: Find and Verify a Text Record

Topic request

curl -sS \
  'https://www.goguides.com/verified-text.php?q=gravity&format=json'

Complete direct record request

curl -sS \
  'https://www.goguides.com/verified-text.php?source_key=britannica_1926&chunk_id=1926%3Ag%20t%20b%20boxing%3Aa37e28623831&format=json'

Independent Python hash check

import hashlib
import json
from urllib.request import urlopen

url = (
    "https://www.goguides.com/verified-text.php"
    "?source_key=britannica_1926"
    "&chunk_id=1926%3Ag%20t%20b%20boxing%3Aa37e28623831"
    "&format=json"
)

with urlopen(url) as response:
    record = json.load(response)

computed_sha256 = hashlib.sha256(
    record["verified_text"].encode("utf-8")
).hexdigest()

assert computed_sha256 == record["hash_sha256"]
assert record["integrity"]["hash_check"] == "match"

Purposeful Verified-Text Test Queries

These examples cover different retrieval conditions without repeating every topic in both long lists.

Response Handling and Troubleshooting

What These Machine Signals Do Not Prove

• A SHA-256 match proves text integrity against the stored normalized record; it does not prove that every statement in the source is current or factually correct.
• A trust, profile, history, evaluation, Web State, Change Intelligence, or URL Request response is evidence published by GoGuides. It does not prove that another crawler, model provider, search engine, or AI system accepts or uses that evidence downstream.
• AI Rank, grade, trust state, policy conclusions, and refresh guidance are GoGuides-derived assessments. They are not universal ground truth and do not require another system to reach the same conclusion.
• Publishing integration instructions does not authorize an autonomous client to create side effects. An eligible machine exact-URL Evaluate miss can schedule root and exact-page crawl work, while POST /request-url provides explicit attributed acquisition and status tracking. Side-effect-capable use must be permitted by the client's operator, application, integration, or tool policy.
• A verified Web Bot Auth signature proves cryptographic control of the signing identity used for that request. It does not by itself prove endorsement, benign intent, model training, citation, recommendation, dependency, or commercial intent.
• Source-grounded retrieval can improve auditability and reduce unsupported source selection, but it cannot guarantee that an AI system will interpret or use the record correctly.
• Historical material may contain outdated language, facts, assumptions, or viewpoints.
• Licensed records must retain the attribution and license information returned with the record.

Related Documentation and Public Records