FRESH
Know whether to fetch again.
FRESH is shared URL freshness intelligence for AI agents. Before re-fetching, re-scraping, re-rendering, or re-embedding a URL, ask whether the previously seen version is probably still fresh enough to reuse.
Production base URL: https://fresh-api-production-c783.up.railway.app
MCP endpoint: https://fresh-api-production-c783.up.railway.app/mcp
FRESH returns one of three decisions:
REUSE— cached knowledge is probably still fresh enoughREFETCH— the URL is likely stale enough to justify another retrievalUNKNOWN— evidence is insufficient; FRESH prefers uncertainty over false confidence
Why FRESH exists
A local cache knows when you last fetched something. It does not know whether the outside resource changed since then, nor what other callers recently observed. FRESH builds shared, privacy-safe URL change history from timestamps, ETags, Last-Modified values, and content hashes.
REST
POST /v1/check
{"url":"https://example.com/docs/api","lastSeenAt":"2026-08-13T12:00:00Z","toleranceSeconds":3600}
POST /v1/observe
{"url":"https://example.com/docs/api","observedAt":"2026-08-13T13:00:00Z","etag":"abc123","lastModified":"Wed, 13 Aug 2026 12:45:00 GMT","contentHash":"sha256:..."}
Raw page content is not required.
MCP
fresh_check— decide whether to retrieve a URL againfresh_observe— report privacy-safe freshness evidence after retrieval
Privacy
FRESH does not need raw page contents, cookies, target-site credentials, or customer payloads. URL keys are stored as one-way hashes with aggregate observation metadata.
Stranger verification
A core-tool invocation is evidence of use, not automatically proof of a genuine stranger. FRESH classifies candidate activity as KNOWN_VALIDATOR, LIKELY_VALIDATOR, CONTROLLED_TEST, UNKNOWN_MACHINE, or CREDIBLE_REAL_USE. Only CREDIBLE_REAL_USE advances stranger milestones.
Our acceptance/smoke traffic uses X-Tollbooth-Internal: 1 or X-Fresh-Internal: 1 so it cannot earn stranger credit.
Production acceptance gate
Every Railway deployment now performs live internal checks against the running service before /health can return 200. The gate exercises REST, UNKNOWN, REUSE, REFETCH, persistent observation reload, MCP initialize, MCP tool discovery, MCP fresh_check, and verifies that the controlled self-test does not increase the verified-stranger count.
Status
v0.1.2 experimental production infrastructure. Priorities: conservative decisions, low latency, sub-penny economics, privacy-safe shared learning, REST + MCP, durable observations, and auditable real-use analytics.
