{"openapi":"3.1.0","info":{"title":"sourvillo.ru read-only agent API","version":"2026-05-24","description":"Public read-only API for agents exploring Ivan Sourvillo's archive. Responses are structured for retrieval, citation and navigation, not for destructive actions."},"servers":[{"url":"https://sourvillo.ru"}],"externalDocs":{"description":"LLM context","url":"https://sourvillo.ru/llms.txt"},"paths":{"/api/agent/search":{"get":{"operationId":"searchArchive","summary":"Search public archive materials","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2}},{"name":"section","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":30}}],"responses":{"200":{"description":"Successful read-only response","content":{"application/json":{"schema":{"type":"object","required":["ok","query","results"],"properties":{"ok":{"type":"boolean","const":true},"query":{"type":"string"},"section":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}}}}}}},"400":{"description":"Invalid input or missing public material","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/context":{"get":{"operationId":"getAuthorContext","summary":"Return site identity, policies, endpoints and high-level routes","responses":{"200":{"description":"Successful read-only response","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object"}}}}}}}}},"/api/agent/collections":{"get":{"operationId":"listCollections","summary":"List public collections and counts","responses":{"200":{"description":"Successful read-only response","content":{"application/json":{"schema":{"type":"object","required":["ok","collections"],"properties":{"ok":{"type":"boolean","const":true},"collections":{"type":"array","items":{"type":"object"}}}}}}}}}},"/api/agent/topics":{"get":{"operationId":"getTopicRoutes","summary":"List topic routes or return one route by id","parameters":[{"name":"id","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful read-only response","content":{"application/json":{"schema":{"type":"object","required":["ok","topics"],"properties":{"ok":{"type":"boolean","const":true},"topics":{"type":"array","items":{"type":"object"}}}}}}},"404":{"description":"Invalid input or missing public material","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/material":{"get":{"operationId":"getMaterial","summary":"Return a material card with citation and related graph","parameters":[{"name":"id","in":"query","required":false,"schema":{"type":"string"}},{"name":"url","in":"query","required":false,"schema":{"type":"string"}},{"name":"slug","in":"query","required":false,"schema":{"type":"string"}},{"name":"section","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful read-only response","content":{"application/json":{"schema":{"type":"object","required":["ok","material"],"properties":{"ok":{"type":"boolean","const":true},"material":{"$ref":"#/components/schemas/MaterialCard"}}}}}},"404":{"description":"Invalid input or missing public material","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/related":{"get":{"operationId":"getRelatedMaterials","summary":"Return topic routes and related materials for one material","parameters":[{"name":"id","in":"query","required":false,"schema":{"type":"string"}},{"name":"url","in":"query","required":false,"schema":{"type":"string"}},{"name":"slug","in":"query","required":false,"schema":{"type":"string"}},{"name":"section","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20}}],"responses":{"200":{"description":"Successful read-only response","content":{"application/json":{"schema":{"type":"object","required":["ok","related"],"properties":{"ok":{"type":"boolean","const":true},"related":{"type":"object","properties":{"material":{"$ref":"#/components/schemas/MaterialSummary"},"relatedTopics":{"type":"array","items":{"$ref":"#/components/schemas/RelatedTopic"}},"relatedMaterials":{"type":"array","items":{"$ref":"#/components/schemas/RelatedMaterial"}}}}}}}}},"404":{"description":"Invalid input or missing public material","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/answer":{"get":{"operationId":"answerArchive","summary":"Return a non-generative answer card with citations","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2}},{"name":"section","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10}}],"responses":{"200":{"description":"Successful read-only response","content":{"application/json":{"schema":{"type":"object","required":["ok","answerCard"],"properties":{"ok":{"type":"boolean","const":true},"answerCard":{"type":"object"}}}}}},"400":{"description":"Invalid input or missing public material","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"SearchResult":{"type":"object","required":["id","url","path","title","section","sectionLabel","description","score"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"path":{"type":"string"},"title":{"type":"string"},"section":{"type":"string"},"sectionLabel":{"type":"string"},"description":{"type":"string"},"excerpt":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"date":{"type":"string"},"score":{"type":"number"},"matches":{"type":"array","items":{"type":"string"}}}},"MaterialCard":{"allOf":[{"type":"object","required":["id","title","url","path","section","sectionLabel"],"properties":{"id":{"type":"string","examples":["travel:madeira-2025"]},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"path":{"type":"string"},"section":{"type":"string"},"sectionLabel":{"type":"string"}}},{"type":"object","properties":{"description":{"type":"string"},"date":{"type":"string"},"image":{"type":"string","format":"uri"},"people":{"type":"array","items":{"type":"string"}},"places":{"type":"array","items":{"type":"string"}},"topics":{"type":"array","items":{"type":"string"}},"evidence":{"type":"object"},"citation":{"type":"object"},"related":{"type":"array","items":{"type":"object"}},"relatedTopics":{"type":"array","items":{"type":"object","required":["id","title","url","path","reason"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"path":{"type":"string"},"reason":{"type":"string"}}}},"relatedMaterials":{"type":"array","items":{"type":"object","required":["id","title","url","path","section","sectionLabel","description","relation","score"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"path":{"type":"string"},"section":{"type":"string"},"sectionLabel":{"type":"string"},"description":{"type":"string"},"relation":{"type":"string"},"score":{"type":"number"},"sharedTopics":{"type":"array","items":{"type":"string"}}}}},"summaryText":{"type":"string"}}}]},"MaterialSummary":{"type":"object","required":["id","title","url","path","section","sectionLabel"],"properties":{"id":{"type":"string","examples":["travel:madeira-2025"]},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"path":{"type":"string"},"section":{"type":"string"},"sectionLabel":{"type":"string"}}},"RelatedTopic":{"type":"object","required":["id","title","url","path","reason"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"path":{"type":"string"},"reason":{"type":"string"}}},"RelatedMaterial":{"type":"object","required":["id","title","url","path","section","sectionLabel","description","relation","score"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"path":{"type":"string"},"section":{"type":"string"},"sectionLabel":{"type":"string"},"description":{"type":"string"},"relation":{"type":"string"},"score":{"type":"number"},"sharedTopics":{"type":"array","items":{"type":"string"}}}},"Error":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string"}}}}}}