GoGuides URL Request API
The URL Request API gives a client an explicit, attributed way to request GoGuides intelligence for one public HTTP or HTTPS URL.
The caller requests intelligence; it does not write an authoritative GoGuides record, choose an AI Rank, set a grade, or dictate a trust or policy outcome. Any resulting GoGuides observation and assessment remain GoGuides-produced evidence.
Capability: goguides.url_request
API version: url-request-v1
Data License: 2.0
Request
POST https://www.goguides.com/request-url
Content-Type: application/json
{
"url": "https://example.com/article",
"freshness": "use-current-or-crawl-on-miss"
}
The freshness value above is part of the public request contract.
It expresses the caller's request policy. It is not a description of GoGuides'
private scheduling, capacity, or crawler-control implementation.
Known intelligence
When GoGuides already has usable intelligence for the exact requested URL,
the endpoint can return HTTP 200 with an available result.
The response can link to the authoritative exact-URL Evaluate record and
separately to root/domain context.
Exact-page and root/domain scopes remain distinct. A page result must not silently inherit another page's AI Rank, and a child-page result does not replace the authoritative root/domain record.
Accepted request
When the requested public URL does not yet have a usable result under the
request contract, the endpoint can return HTTP 202 Accepted
with a high-entropy gur_... request ID and a public status URL.
Location: /request-url/status/gur_... Retry-After: 5
HTTP 202 means the request was accepted for asynchronous
processing. It does not mean that a favorable GoGuides assessment is
guaranteed, and it does not guarantee any action by an outside AI system,
search engine, crawler, or model provider.
Status
GET https://www.goguides.com/request-url/status/gur_...
The status resource lets a client follow the public lifecycle of the request. Status lookup is observational: clients should use the returned public state, links, and retry guidance rather than attempting to infer private processing or infrastructure state.
Result surfaces
| Surface | Purpose |
|---|---|
| Exact URL Evaluate | The GoGuides evaluation for the normalized exact page when available. |
| Domain Evaluate | Separate authoritative root/domain evaluation context. |
| Web State | Latest supported stored observation evidence for the domain scope. |
| Change Intelligence | Deterministic comparison of supported stored observations. |
| History | Longitudinal observation and provenance context. |
Evaluate versus URL Request
Evaluate resolves the authoritative GoGuides evaluation available for a requested normalized scope. URL Request is the explicit attributed request workflow for a client that wants to request intelligence for one public URL and follow a request lifecycle.
These are different public contracts. Consumers should not treat an ordinary evaluation lookup as proof that an explicit URL Request was submitted.
Safety and validation
URL Request accepts supported public HTTP or HTTPS targets under the published interface. Unsupported schemes, credentials, unsupported ports, and non-public network targets can be rejected. A rejection means the request cannot proceed under the public contract; it does not imply a broader judgment about the website.
Machine identity
A User-Agent or Signature-Agent claim alone is not treated as cryptographically verified identity. When supported HTTP Message Signature fields are supplied, GoGuides can attempt Web Bot Auth verification using the documented public identity mechanism.
A successful signature check establishes request-attribution evidence for that signed identity. It does not prove endorsement, benign intent, model training, citation, recommendation, commercial intent, or downstream use.
Evidence → Interpretation → Decision
URL Request records explicit request intent. GoGuides observations remain evidence. GoGuides-derived scores and policy fields remain interpretation. The consuming system remains responsible for its own source-use decision.