# Beatnik Hiway developer documentation

## Purpose

A deterministic literary-place and counterculture evidence service. HTML, REST, Markdown, JSON, and MCP use the same published snapshot.

## Inputs and outputs

The public business surface consists of exactly six read-only tools. See [OpenAPI](https://beatnikhiway.com/openapi.json) for JSON schemas and [MCP](https://beatnikhiway.com/developers#mcp) for Streamable HTTP setup.

## Unified response

Responses include success, request_id, schema_version, dataset_version, result, sources, served_at, freshness, cache, coverage, warnings, next_actions, and usage. A successful request may still report an unknown or partial domain result.

## Data sources

Only registered sources and reviewed publication records are served. Source retrieval time never replaces the human review timestamp. See [Data sources](https://beatnikhiway.com/data-sources).

## Freshness

Freshness is evaluated at serve time from reviewed_at. Historical facts, access information, and operating notices have separate maintenance targets.

## API

Base path: `https://beatnikhiway.com/api/v1`. Public low-volume reads need no key. Higher quotas use `Authorization: Bearer <key>`.

## MCP

Endpoint: `https://beatnikhiway.com/mcp`. Transport: Streamable HTTP. The server is stateless and exposes exactly the same six domain tools. OAuth is not implemented.

## Protocol discovery status

ARD: [/.well-known/ard.json](https://beatnikhiway.com/.well-known/ard.json) (deferred, machine-readable 404). A2A Agent Card: [/.well-known/agent-card.json](https://beatnikhiway.com/.well-known/agent-card.json) (deferred, machine-readable 404). Supported discovery remains /llms.txt, /openapi.json, /docs/index.md, and /mcp.

## Errors

The service uses meaningful HTTP codes and structured error objects. Empty search is not an error; an unknown entity ID is 404; a stale cursor is 409; quota exhaustion is 429.

## Limitations

No live-open guarantee, map routing, ticketing, external transactions, arbitrary web fetch, or LLM inference occurs during ordinary reads. Local and preview demonstration records are synthetic; production records are reviewed public metadata and still do not guarantee live availability, historical completeness, or real-world travel outcomes.