{"openapi":"3.1.0","info":{"title":"Michiyomi scenery search","version":"explore-v1","description":"Bounded scenery discovery over released Japanese VLM observations. Jev is the category selector and relevance judge, not a web search or image recognizer. Source observations remain available in full. See /explore/llms.txt for agent workflows."},"servers":[{"url":"https://michiyomi.dev"}],"paths":{"/explore/api/meta":{"get":{"operationId":"search_metadata","summary":"Discover municipalities, presets, defaults, provenance and capabilities.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Metadata"}}}},"400":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Expired cursor; restart without cursor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Respect Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/explore/api/search":{"post":{"operationId":"search_scenes","summary":"Search physical scenery or evocative impressions; returns evidence and continuation.","description":"Server clients need Content-Type: application/json; no UI-specific header or API key. Browser origin must match. Default capture years are 2018 and later. At most 20 requests/minute/IP. All conditions must be repeated when using cursor, including limit. Lower limit bounds returned images, not a promise of proportional inference savings.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"},"examples":{"impression":{"value":{"query":"夏っぽいところ","limit":3}},"physical":{"value":{"query":"並木や樹冠に囲まれた緑の多い道","ward":"調布市","year_from":2024,"limit":3}},"historical":{"value":{"query":"古い街並み","year_from":0,"year_to":2010,"mode":"text"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Expired cursor; restart without cursor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Respect Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/explore/api/scene/{scene_id}":{"get":{"operationId":"get_scene","summary":"Read one full original observation by string ID, including provenance and source links.","parameters":[{"name":"scene_id","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{5,25}$"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Detail"}}}},"400":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Expired cursor; restart without cursor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. Respect Retry-After.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Machine-readable error; inspect code and field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"SearchRequest":{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S","description":"Japanese scenery request. Free wording is mapped to 168 physical scenery categories; not a general web search or a live-status service."},"preset":{"type":["string","null"],"enum":["green_walk","waterside","retro","arcade","steps","flowers","shrine","brick",null],"description":"Optional preset ID from metadata. A supplied query takes precedence."},"ward":{"type":"string","maxLength":30,"default":"","description":"Exact municipality label from metadata. Empty means all indexed areas, including Tama and islands."},"year_from":{"type":"integer","anyOf":[{"const":0},{"minimum":2000,"maximum":2026}],"default":2018,"description":"Inclusive capture-year lower bound, 2000–2026; 0 includes older captures. Omission means 2018, not all years."},"year_to":{"type":["integer","null"],"minimum":1900,"maximum":2026,"default":null,"description":"Optional inclusive capture-year upper bound. Use year_from=0 to search before 2000."},"mode":{"type":"string","enum":["jev","text"],"default":"jev","description":"jev ranks candidates against full observations and may fall back to text if unavailable. text uses indexed words/tags and makes no Jev calls; it does not verify all query conditions."},"bbox":{"type":["array","null"],"items":{"type":"number"},"minItems":4,"maxItems":4,"description":"WGS84 [west longitude, south latitude, east longitude, north latitude], inclusive. Not [lat,lon]. Cannot cross the antimeridian."},"cursor":{"type":["string","null"],"pattern":"^[a-f0-9]{64}$","description":"Opaque next_cursor from the previous response. Repeat exactly the same query and filters. Expires after one hour."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":24,"description":"Maximum results on this page. Does not increase the 60-candidate/14-call work budget. Small limits reduce response size; inference is still batched."}},"anyOf":[{"required":["query"]},{"required":["preset"],"properties":{"preset":{"type":"string"}}}]},"SearchResponse":{"type":"object","required":["api_version","source_release","results","applied_filters","interpretation","coverage","pagination","usage","license"],"properties":{"api_version":{"const":"explore-v1"},"source_release":{"type":"string"},"data_language":{"const":"ja"},"query":{"type":"string"},"results":{"type":"array","maxItems":24,"items":{"type":"object","required":["id","year","capture_year","lat","lon","coordinate_role","generation","source_release","links"],"properties":{"id":{"type":"string","pattern":"^\\d{5,25}$"},"year":{"type":["integer","null"],"description":"Capture year; not generation time."},"capture_year":{"type":["integer","null"]},"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"ward":{"type":["string","null"]},"title":{"type":"string"},"coordinate_role":{"const":"image_capture_position"},"generation":{"type":"object","required":["id","status","version"],"properties":{"id":{"type":["string","null"]},"status":{"const":"released"},"version":{"type":["integer","null"]}}},"source_release":{"type":"string"},"is_pano":{"type":["boolean","null"]},"camera_type":{"type":["string","null"]},"position_source":{"type":["string","null"]},"observation_model":{"type":["string","null"]},"prompt_version":{"type":["string","null"]},"generated_at":{"type":["string","null"]},"links":{"type":"object","required":["detail","observation","image","source"],"properties":{"detail":{"type":"string","format":"uri"},"observation":{"type":"string","format":"uri"},"image":{"type":"string","format":"uri"},"source":{"type":"string","format":"uri"}}},"quotes":{"type":"array","items":{"type":"object","required":["text","source_pointer","source_layer"],"properties":{"text":{"type":"string"},"path":{"type":"string"},"source_pointer":{"type":["string","null"]},"source_layer":{"const":"vlm_observation"},"section":{"type":"string"}}}},"match_score":{"type":"number","minimum":0,"maximum":1,"description":"Rubric position normalized to 0–1, NOT correctness probability. Present only for semantic matches."},"match_confidence":{"type":["number","null"],"minimum":0,"maximum":1},"match_probabilities":{"type":["object","null"],"additionalProperties":{"type":"number","minimum":0,"maximum":1}},"tags":{"type":"array","items":{"type":"string"}},"observation":{"type":"object","additionalProperties":true}}}},"applied_filters":{"type":"object","additionalProperties":true},"interpretation":{"type":"object","additionalProperties":true},"coverage":{"type":"object","required":["exhaustive","matching_total","unit"],"properties":{"exhaustive":{"const":false},"matching_total":{"type":"null"},"unit":{"const":"image_observation"}}},"pagination":{"type":"object","required":["has_more","next_cursor","next_request","stop_reason","cursor_expires_at"],"properties":{"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]},"next_request":{"anyOf":[{"type":"object","additionalProperties":false,"properties":{"query":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S","description":"Japanese scenery request. Free wording is mapped to 168 physical scenery categories; not a general web search or a live-status service."},"preset":{"type":["string","null"],"enum":["green_walk","waterside","retro","arcade","steps","flowers","shrine","brick",null],"description":"Optional preset ID from metadata. A supplied query takes precedence."},"ward":{"type":"string","maxLength":30,"default":"","description":"Exact municipality label from metadata. Empty means all indexed areas, including Tama and islands."},"year_from":{"type":"integer","anyOf":[{"const":0},{"minimum":2000,"maximum":2026}],"default":2018,"description":"Inclusive capture-year lower bound, 2000–2026; 0 includes older captures. Omission means 2018, not all years."},"year_to":{"type":["integer","null"],"minimum":1900,"maximum":2026,"default":null,"description":"Optional inclusive capture-year upper bound. Use year_from=0 to search before 2000."},"mode":{"type":"string","enum":["jev","text"],"default":"jev","description":"jev ranks candidates against full observations and may fall back to text if unavailable. text uses indexed words/tags and makes no Jev calls; it does not verify all query conditions."},"bbox":{"type":["array","null"],"items":{"type":"number"},"minItems":4,"maxItems":4,"description":"WGS84 [west longitude, south latitude, east longitude, north latitude], inclusive. Not [lat,lon]. Cannot cross the antimeridian."},"cursor":{"type":["string","null"],"pattern":"^[a-f0-9]{64}$","description":"Opaque next_cursor from the previous response. Repeat exactly the same query and filters. Expires after one hour."},"limit":{"type":"integer","minimum":1,"maximum":24,"default":24,"description":"Maximum results on this page. Does not increase the 60-candidate/14-call work budget. Small limits reduce response size; inference is still batched."}},"anyOf":[{"required":["query"]},{"required":["preset"],"properties":{"preset":{"type":"string"}}}]},{"type":"null"}]},"stop_reason":{"enum":["upstream_unavailable","page_limit","page_ready","request_budget","candidate_sources_exhausted"]},"cursor_expires_at":{"type":["string","null"],"format":"date-time"},"cursor_ttl_s":{"const":3600}}},"usage":{"type":"object","additionalProperties":true},"license":{"type":"object","additionalProperties":true},"mode":{"enum":["jev","text","related"]},"warning":{"type":["string","null"]},"has_more":{"type":"boolean"},"cached":{"type":"boolean"},"inference_calls":{"type":"integer","minimum":0,"maximum":14},"inference_input_tokens":{"type":"integer","minimum":0},"search_complete":{"type":"boolean","description":"Exhausted the bounded retrieval streams, NOT all corpus observations."}}},"Scene":{"type":"object","required":["id","year","capture_year","lat","lon","coordinate_role","generation","source_release","links"],"properties":{"id":{"type":"string","pattern":"^\\d{5,25}$"},"year":{"type":["integer","null"],"description":"Capture year; not generation time."},"capture_year":{"type":["integer","null"]},"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"ward":{"type":["string","null"]},"title":{"type":"string"},"coordinate_role":{"const":"image_capture_position"},"generation":{"type":"object","required":["id","status","version"],"properties":{"id":{"type":["string","null"]},"status":{"const":"released"},"version":{"type":["integer","null"]}}},"source_release":{"type":"string"},"is_pano":{"type":["boolean","null"]},"camera_type":{"type":["string","null"]},"position_source":{"type":["string","null"]},"observation_model":{"type":["string","null"]},"prompt_version":{"type":["string","null"]},"generated_at":{"type":["string","null"]},"links":{"type":"object","required":["detail","observation","image","source"],"properties":{"detail":{"type":"string","format":"uri"},"observation":{"type":"string","format":"uri"},"image":{"type":"string","format":"uri"},"source":{"type":"string","format":"uri"}}},"quotes":{"type":"array","items":{"type":"object","required":["text","source_pointer","source_layer"],"properties":{"text":{"type":"string"},"path":{"type":"string"},"source_pointer":{"type":["string","null"]},"source_layer":{"const":"vlm_observation"},"section":{"type":"string"}}}},"match_score":{"type":"number","minimum":0,"maximum":1,"description":"Rubric position normalized to 0–1, NOT correctness probability. Present only for semantic matches."},"match_confidence":{"type":["number","null"],"minimum":0,"maximum":1},"match_probabilities":{"type":["object","null"],"additionalProperties":{"type":"number","minimum":0,"maximum":1}},"tags":{"type":"array","items":{"type":"string"}},"observation":{"type":"object","additionalProperties":true}}},"Detail":{"type":"object","required":["id","year","capture_year","lat","lon","coordinate_role","generation","source_release","links","api_version","observation","license"],"properties":{"id":{"type":"string","pattern":"^\\d{5,25}$"},"year":{"type":["integer","null"],"description":"Capture year; not generation time."},"capture_year":{"type":["integer","null"]},"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"ward":{"type":["string","null"]},"title":{"type":"string"},"coordinate_role":{"const":"image_capture_position"},"generation":{"type":"object","required":["id","status","version"],"properties":{"id":{"type":["string","null"]},"status":{"const":"released"},"version":{"type":["integer","null"]}}},"source_release":{"type":"string"},"is_pano":{"type":["boolean","null"]},"camera_type":{"type":["string","null"]},"position_source":{"type":["string","null"]},"observation_model":{"type":["string","null"]},"prompt_version":{"type":["string","null"]},"generated_at":{"type":["string","null"]},"links":{"type":"object","required":["detail","observation","image","source"],"properties":{"detail":{"type":"string","format":"uri"},"observation":{"type":"string","format":"uri"},"image":{"type":"string","format":"uri"},"source":{"type":"string","format":"uri"}}},"quotes":{"type":"array","items":{"type":"object","required":["text","source_pointer","source_layer"],"properties":{"text":{"type":"string"},"path":{"type":"string"},"source_pointer":{"type":["string","null"]},"source_layer":{"const":"vlm_observation"},"section":{"type":"string"}}}},"match_score":{"type":"number","minimum":0,"maximum":1,"description":"Rubric position normalized to 0–1, NOT correctness probability. Present only for semantic matches."},"match_confidence":{"type":["number","null"],"minimum":0,"maximum":1},"match_probabilities":{"type":["object","null"],"additionalProperties":{"type":"number","minimum":0,"maximum":1}},"tags":{"type":"array","items":{"type":"string"}},"observation":{"type":"object","additionalProperties":true},"api_version":{"const":"explore-v1"},"license":{"type":"object","additionalProperties":true}}},"Metadata":{"type":"object","required":["api_version","source_release","manifest","wards","links","search_features"],"properties":{"api_version":{"const":"explore-v1"},"source_release":{"type":"string"},"manifest":{"type":"object","additionalProperties":true},"wards":{"type":"array","items":{"type":"object","additionalProperties":true}},"links":{"type":"object","additionalProperties":true},"search_features":{"type":"object","additionalProperties":true}}},"Error":{"type":"object","required":["error","code","retryable"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"field":{"type":["string","null"]},"retryable":{"type":"boolean"},"retry_after_s":{"type":"integer"},"recovery":{"type":"string"}}}}},"externalDocs":{"url":"https://michiyomi.dev/explore/llms.txt","description":"Agent workflow, evidence semantics and core API links"}}