{"openapi":"3.1.0","info":{"title":"Beatnik Hiway Literary Places & Counterculture Evidence API","version":"1.0.0","description":"Six read-only tools for discovering cultural entities, inspecting evidence, evaluating scheduled access, planning evidence-constrained walks, building research packs, and measuring actual dataset coverage. Empty results describe this index, not reality. Scheduled access is not a live guarantee."},"servers":[{"url":"https://beatnikhiway.com"}],"tags":[{"name":"Cultural evidence tools","description":"The complete public business-tool surface: exactly six tools."}],"paths":{"/api/v1/entities":{"get":{"operationId":"search_cultural_entities","summary":"Search the published cultural entity index","description":"Find published cultural entities by name, alias, type, city, or theme. Use this tool to discover stable identifiers and inspect what the current dataset covers. Do not treat an empty result as proof that a real-world entity does not exist. Results include matched fields, coverage, a version-bound cursor, sources, freshness, and one usage unit. This is a read-only deterministic database query with no external network or model call.","tags":["Cultural evidence tools"],"security":[{},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Complete, partial, or unknown domain result.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Applicable per-minute unit limit."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining units in the minute window."},"RateLimit-Reset":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the applicable minute quota window resets."},"X-Request-Id":{"schema":{"type":"string"},"description":"Server-generated request identifier."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-cost-units":1,"x-side-effects":"none","parameters":[{"name":"query","in":"query","required":false,"description":"Name or alias text to find.","schema":{"description":"Name or alias text to find.","type":"string","minLength":1,"maxLength":200},"example":"City Lights Bookstore"},{"name":"entity_type","in":"query","required":false,"description":"Restrict results to one entity type.","schema":{"description":"Restrict results to one entity type.","type":"string","enum":["place","person","work","organization","movement","historical_event"]}},{"name":"city_id","in":"query","required":false,"description":"Stable city identifier.","schema":{"description":"Stable city identifier.","type":"string","minLength":1,"maxLength":100},"example":"sf_city_san_francisco"},{"name":"themes","in":"query","required":false,"description":"Up to five theme filters.","style":"form","explode":true,"schema":{"description":"Up to five theme filters.","maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"example":["literary-counterculture"]},{"name":"limit","in":"query","required":true,"description":"Maximum results to return, from 1 to 50.","schema":{"default":10,"description":"Maximum results to return, from 1 to 50.","type":"integer","minimum":1,"maximum":50},"example":10},{"name":"cursor","in":"query","required":false,"description":"Opaque version-bound pagination cursor.","schema":{"description":"Opaque version-bound pagination cursor.","type":"string","minLength":1,"maxLength":2000}}]}},"/api/v1/entities/{entity_id}":{"get":{"operationId":"get_entity_evidence","summary":"Retrieve claims and evidence for one entity","description":"Retrieve published claims, direct relationships, source locators, review dates, and known unknowns for one stable entity ID. Use it after search when a task requires traceable evidence. Do not use it to infer visits, quotations, membership, or page numbers absent from the published record. The response preserves disputes and rights limits and costs one usage unit. It is read-only and makes no live upstream request.","tags":["Cultural evidence tools"],"security":[{},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Complete, partial, or unknown domain result.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Applicable per-minute unit limit."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining units in the minute window."},"RateLimit-Reset":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the applicable minute quota window resets."},"X-Request-Id":{"schema":{"type":"string"},"description":"Server-generated request identifier."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-cost-units":1,"x-side-effects":"none","parameters":[{"name":"entity_id","in":"path","required":true,"description":"Stable entity identifier.","schema":{"type":"string","minLength":1,"maxLength":160,"description":"Stable entity identifier."},"example":"sf_place_landmark_228"},{"name":"include","in":"query","required":false,"style":"form","explode":true,"schema":{"maxItems":5,"type":"array","items":{"type":"string","enum":["claims","relationships","sources","operations","rights"]}},"example":["claims","sources","operations"]},{"name":"claims_limit","in":"query","required":true,"schema":{"default":20,"type":"integer","minimum":1,"maximum":100},"example":20},{"name":"claims_cursor","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":2000}}]}},"/api/v1/visitability/check":{"post":{"operationId":"check_place_visitability","summary":"Evaluate scheduled access at a specified time","description":"Evaluate reviewed access rules for 1–20 places at an offset-aware RFC3339 time and explicit IANA timezone. Use it before proposing an indoor visit. Do not describe scheduled_open as live or guaranteed availability, and do not use max_age_seconds=0 to force a fetch. Temporary closures and restrictions take precedence over regular hours; unknown or stale evidence remains visible. Cost is one unit per distinct place. This read-only calculation makes no map, model, ticketing, or live-source call.","tags":["Cultural evidence tools"],"security":[{},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Complete, partial, or unknown domain result.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Applicable per-minute unit limit."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining units in the minute window."},"RateLimit-Reset":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the applicable minute quota window resets."},"X-Request-Id":{"schema":{"type":"string"},"description":"Server-generated request identifier."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-cost-units":"one unit per distinct place_id","x-side-effects":"none","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"place_ids":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":160}},"visit_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$","description":"RFC3339 date-time with an explicit UTC offset."},"timezone":{"type":"string","minLength":1,"maxLength":100,"description":"IANA timezone used to express visit_at."},"max_age_seconds":{"type":"integer","minimum":0,"maximum":31536000}},"required":["place_ids","visit_at","timezone"],"additionalProperties":false},"example":{"place_ids":["sf_place_landmark_228","sf_place_landmark_295"],"visit_at":"2026-10-15T10:00:00-07:00","timezone":"America/Los_Angeles"}}}}}},"/api/v1/walks/plan":{"post":{"operationId":"build_cultural_walk","summary":"Build an evidence- and time-constrained cultural walk","description":"Build a deterministic cultural walk from reviewed places, visit rules, themes, accessibility constraints, and stored directed route segments. Use it for planning within 30–360 minutes. Do not use it as turn-by-turn navigation or infer missing pedestrian geometry. Each stop is checked at arrival and departure; missing segments produce a partial result with null totals. The read-only calculation costs ten units and calls no commercial map or model API.","tags":["Cultural evidence tools"],"security":[{},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Complete, partial, or unknown domain result.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Applicable per-minute unit limit."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining units in the minute window."},"RateLimit-Reset":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the applicable minute quota window resets."},"X-Request-Id":{"schema":{"type":"string"},"description":"Server-generated request identifier."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-cost-units":10,"x-side-effects":"none","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"start_place_id":{"type":"string","minLength":1,"maxLength":160},"visit_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"timezone":{"type":"string","minLength":1,"maxLength":100},"duration_minutes":{"type":"integer","minimum":30,"maximum":360},"themes":{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"max_stops":{"default":4,"type":"integer","minimum":1,"maximum":8},"accessibility_requirement":{"default":"none","type":"string","enum":["none","wheelchair"]}},"required":["start_place_id","visit_at","timezone","duration_minutes","max_stops","accessibility_requirement"],"additionalProperties":false},"example":{"start_place_id":"sf_place_landmark_228","visit_at":"2026-10-16T10:00:00-07:00","timezone":"America/Los_Angeles","duration_minutes":120,"themes":["literary-counterculture"],"max_stops":4,"accessibility_requirement":"none"}}}}}},"/api/v1/research-packs/build":{"post":{"operationId":"build_research_pack","summary":"Build a deterministic, source-backed research pack","description":"Create a JSON, Markdown, or BibTeX research pack for 1–20 published entities, with at most 100 claims. Use it when a writing or research task needs citations, disputes, unknowns, dates, and reuse limits kept together. Do not expect copyrighted source text, fabricated quotations, missing bibliographic fields, or unreviewed translations. Unknown rights deny export of the underlying asset while permitted metadata and links remain. This read-only synchronous tool costs twenty units and stores no pack.","tags":["Cultural evidence tools"],"security":[{},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Complete, partial, or unknown domain result.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Applicable per-minute unit limit."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining units in the minute window."},"RateLimit-Reset":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the applicable minute quota window resets."},"X-Request-Id":{"schema":{"type":"string"},"description":"Server-generated request identifier."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-cost-units":20,"x-side-effects":"none","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entity_ids":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1,"maxLength":160}},"topic":{"type":"string","maxLength":500},"language":{"default":"en","type":"string","enum":["en","zh-CN"]},"format":{"default":"json","type":"string","enum":["json","markdown","bibtex"]}},"required":["entity_ids","language","format"],"additionalProperties":false},"example":{"entity_ids":["sf_place_landmark_228"],"topic":"San Francisco literary landmarks","language":"en","format":"json"}}}}}},"/api/v1/coverage":{"get":{"operationId":"get_dataset_coverage","summary":"Inspect current dataset scope and gaps","description":"Return computed counts, scope, gaps, freshness distribution, demo status, and known limitations for the current published snapshot, optionally filtered by city or theme. Use it to interpret search misses or decide whether this service covers a task. Do not confuse maintenance targets with live monitoring or target counts with records. Empty reviewed production data returns honest zeros. This read-only query costs one usage unit.","tags":["Cultural evidence tools"],"security":[{},{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Complete, partial, or unknown domain result.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Applicable per-minute unit limit."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Remaining units in the minute window."},"RateLimit-Reset":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the applicable minute quota window resets."},"X-Request-Id":{"schema":{"type":"string"},"description":"Server-generated request identifier."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/TooLarge"},"422":{"$ref":"#/components/responses/ValidationError"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"},"503":{"$ref":"#/components/responses/Unavailable"}},"x-cost-units":1,"x-side-effects":"none","parameters":[{"name":"city_id","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":100},"example":"sf_city_san_francisco"},{"name":"theme","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":80}}]}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"Beatnik Hiway API key","description":"Optional for higher quotas. Public low-volume reads do not require authentication."}},"schemas":{"DomainEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"request_id":{"type":"string"},"schema_version":{"type":"string"},"dataset_version":{"type":["string","null"]},"result":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"sources":{"type":"array","items":{"type":"object","properties":{"source_id":{"type":"string"},"publisher":{"type":"string"},"source_url":{"type":"string"},"source_type":{"type":"string"},"published_at":{"type":["string","null"]},"retrieved_at":{"type":["string","null"]},"locator":{"type":["string","null"]},"support_type":{"type":["string","null"]},"is_demo":{"type":"boolean"}},"required":["source_id","publisher","source_url","source_type","published_at","retrieved_at","is_demo"],"additionalProperties":false}},"served_at":{"type":"string"},"freshness":{"type":"object","properties":{"evaluated_at":{"type":"string"},"basis":{"type":"string"},"reviewed_at":{"type":["string","null"]},"age_seconds":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"effective_max_age_seconds":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"status":{"type":"string","enum":["fresh","stale","unknown","mixed"]}},"required":["evaluated_at","basis","reviewed_at","age_seconds","effective_max_age_seconds","status"],"additionalProperties":false},"cache":{"type":"object","properties":{"hit":{"type":"boolean"},"age_seconds":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"scope":{"type":"string","enum":["none","public","private"]}},"required":["hit","age_seconds","scope"],"additionalProperties":false},"coverage":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"warnings":{"type":"array","items":{"type":"string"}},"next_actions":{"maxItems":2,"type":"array","items":{"type":"object","properties":{"tool":{"type":"string"},"reason":{"type":"string"},"requires_auth":{"type":"boolean"},"estimated_cost_units":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["tool","reason","requires_auth","estimated_cost_units"],"additionalProperties":false}},"usage":{"type":"object","properties":{"cost_units":{"type":"integer","minimum":0,"maximum":9007199254740991},"metering":{"type":"string"},"quota_scope":{"type":"string","enum":["anonymous","client","internal_test"]},"remaining_minute_units":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"remaining_monthly_units":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]}},"required":["cost_units","metering","quota_scope","remaining_minute_units","remaining_monthly_units"],"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"},"field_errors":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"retry_after_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["code","message","retryable"],"additionalProperties":false}},"required":["success","request_id","schema_version","dataset_version","result","sources","served_at","freshness","cache","coverage","warnings","next_actions","usage"],"additionalProperties":false},"Error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"},"field_errors":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"retry_after_seconds":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["code","message","retryable"],"additionalProperties":false}},"responses":{"BadRequest":{"description":"Request syntax or JSON is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEnvelope"}}}},"Unauthorized":{"description":"The supplied API key is invalid, expired, or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEnvelope"}}}},"NotFound":{"description":"The requested stable entity is not present in this published index.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEnvelope"}}}},"Conflict":{"description":"The cursor or request dataset version is incompatible with the current release.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEnvelope"}}}},"TooLarge":{"description":"The request body exceeds the configured 64 KiB limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEnvelope"}}}},"ValidationError":{"description":"Input is syntactically valid but fails semantic validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEnvelope"}}}},"RateLimited":{"description":"The stricter applicable minute or monthly unit quota was exhausted.","headers":{"Retry-After":{"schema":{"type":"integer","minimum":1}},"RateLimit-Reset":{"schema":{"type":"integer","minimum":1},"description":"Seconds until the exhausted quota window resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEnvelope"}}}},"InternalError":{"description":"An unexpected internal error occurred; implementation details are not exposed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEnvelope"}}}},"Unavailable":{"description":"A required dependency is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainEnvelope"}}}}}},"externalDocs":{"description":"Beatnik Hiway developer documentation","url":"https://beatnikhiway.com/docs"}}