{"openapi":"3.1.1","info":{"title":"Effect Grep public retrieval API","version":"1.0.0","description":"Read-only retrieval over pinned Effect repositories. Start with status and repositories. Preserve generation across queries; never combine evidence from different generations. No authentication is required for these endpoints."},"servers":[{"url":"https://effect-grep.timhanlon.com"}],"externalDocs":{"description":"Retrieval workflow and MCP access","url":"https://effect-grep.timhanlon.com/api/docs"},"security":[],"components":{"schemas":{"ApiProblem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"error":{"type":"string"},"resolution":{"type":"string"},"generation":{"type":"string"},"source":{"type":"object","properties":{"reason":{"type":"string","enum":["file_not_found","range_out_of_bounds"]},"repo":{"type":"string","enum":["effect","effect-solutions","rat-stack","opencode","maple","alchemy-effect","executor","foldkit","effect-agent","t3code","tardigrade","yielded-auth","effect-machine","effect-orm"]},"path":{"type":"string"},"commit":{"type":"string"},"effectVersion":{"anyOf":[{"type":"string"},{"type":"null"}]},"startLine":{"type":"integer"},"endLine":{"type":"integer"},"totalLines":{"type":"integer"}},"required":["reason","repo","path","commit","effectVersion","startLine","endLine"],"additionalProperties":true}},"required":["type","title","status","detail","code","message","error","resolution"],"additionalProperties":true}}},"paths":{"/api/status":{"get":{"operationId":"getStatus","summary":"Check corpus readiness and generation","security":[],"responses":{"200":{"description":"Readiness; generation is null before publication.","content":{"application/json":{"schema":{"type":"object","properties":{"ready":{"type":"boolean"},"generation":{"anyOf":[{"type":"string"},{"type":"null"}]},"files":{"type":"integer"}},"required":["ready","generation","files"],"additionalProperties":true}}}},"500":{"description":"Unexpected server failure.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}}}}},"/api/repositories":{"get":{"operationId":"listRepositories","summary":"Discover the published repositories and graph availability","security":[],"responses":{"200":{"description":"Published generation and pinned repository provenance. Graph availability does not guarantee complete coverage.","content":{"application/json":{"schema":{"type":"object","properties":{"generation":{"type":"string"},"repositories":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","enum":["effect","effect-solutions","rat-stack","opencode","maple","alchemy-effect","executor","foldkit","effect-agent","t3code","tardigrade","yielded-auth","effect-machine","effect-orm"]},"url":{"type":"string"},"sourceUrl":{"type":"string"},"commit":{"type":"string"},"register":{"type":"string","enum":["canonical","pedagogical","production","library"]},"category":{"type":"string","enum":["official-effect","third-party-library","example-application"]},"files":{"type":"integer"},"graphAvailable":{"type":"boolean"}},"required":["name","url","sourceUrl","commit","register","category","files","graphAvailable"],"additionalProperties":true}}},"required":["generation","repositories"],"additionalProperties":true}}}},"500":{"description":"Unexpected server failure.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"502":{"description":"Corpus lookup failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"503":{"description":"The corpus is unavailable or not ready.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}}}}},"/api/catalog":{"get":{"operationId":"getCatalog","summary":"Browse packages, modules, and API members","description":"The response shape depends on package and module filters.","parameters":[{"name":"generation","in":"query","required":true,"description":"Copy the published generation from GET /api/status. A 409 means it changed; restart discovery.","schema":{"type":"string","minLength":1}},{"name":"package","in":"query","required":false,"description":"Omit to list packages; use effect for the core package.","schema":{"type":"string","minLength":1}},{"name":"module","in":"query","required":false,"description":"Omit to list modules. Requires package when supplied.","schema":{"type":"string","minLength":1}}],"security":[],"responses":{"200":{"description":"Successful retrieval.","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["packages"],"properties":{"packages":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["package","modules"],"properties":{"package":{"type":"string"},"modules":{"type":"array","items":{"type":"object","required":["name","members"],"properties":{"name":{"type":"string"},"members":{"type":"integer"}}}}}},{"type":"object","required":["package","module","path","members","stale"],"properties":{"package":{"type":"string"},"module":{"type":"string"},"path":{"type":"string"},"members":{"type":"object","additionalProperties":{"type":"string","enum":["value","type"]}},"stale":{"type":"array","items":{"type":"string"}}}}]}}}},"400":{"description":"Invalid query parameters.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"404":{"description":"The requested indexed resource does not exist.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"409":{"description":"Stale generation. Fetch status and restart discovery.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"500":{"description":"Unexpected server failure.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"503":{"description":"The corpus is unavailable or not ready.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}}}}},"/api/uses":{"get":{"operationId":"findUses","summary":"Find source-addressable API usage","description":"Returns at most 50 uses per page. Read their authored source with getSource.","parameters":[{"name":"generation","in":"query","required":true,"description":"Copy the published generation from GET /api/status. A 409 means it changed; restart discovery.","schema":{"type":"string","minLength":1}},{"name":"symbol","in":"query","required":true,"description":"Module.member or @effect/package/Module.member, for example Effect.gen.","schema":{"type":"string","minLength":1}},{"name":"repo","in":"query","required":false,"description":"Repository name from GET /api/repositories.","schema":{"type":"string","enum":["effect","effect-solutions","rat-stack","opencode","maple","alchemy-effect","executor","foldkit","effect-agent","t3code","tardigrade","yielded-auth","effect-machine","effect-orm"]}},{"name":"offset","in":"query","required":false,"description":"Advance by the returned result count while hasMore is true; preserve symbol, repo, and generation.","schema":{"type":"integer","minimum":0,"default":0}}],"security":[],"responses":{"200":{"description":"Successful retrieval.","content":{"application/json":{"schema":{"type":"object","properties":{"hasMore":{"type":"boolean"},"results":{"type":"array","items":{"type":"object","properties":{"repo":{"type":"string"},"path":{"type":"string"},"line":{"type":"integer"},"column":{"anyOf":[{"type":"integer"},{"type":"null"}]},"endColumn":{"anyOf":[{"type":"integer"},{"type":"null"}]},"commit":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["repo","path","line","column","endColumn"],"additionalProperties":true}}},"required":["hasMore","results"],"additionalProperties":true}}}},"400":{"description":"Invalid query parameters.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"404":{"description":"The requested indexed resource does not exist.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"409":{"description":"Stale generation. Fetch status and restart discovery.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"500":{"description":"Unexpected server failure.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"503":{"description":"The corpus is unavailable or not ready.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}}}}},"/api/graphs":{"get":{"operationId":"getGraphArtifact","summary":"Retrieve a repository's published application graphs","description":"Returns the complete graph artifact, potentially large. Prefer MCP get_application_graph and inspect_graph_part for bounded inspection. Partial or unresolved compiler facts do not establish complete runtime behavior.","parameters":[{"name":"generation","in":"query","required":true,"description":"Copy the published generation from GET /api/status. A 409 means it changed; restart discovery.","schema":{"type":"string","minLength":1}},{"name":"repo","in":"query","required":true,"description":"Repository name from GET /api/repositories.","schema":{"type":"string","enum":["effect","effect-solutions","rat-stack","opencode","maple","alchemy-effect","executor","foldkit","effect-agent","t3code","tardigrade","yielded-auth","effect-machine","effect-orm"]}}],"security":[],"responses":{"200":{"description":"Successful retrieval.","content":{"application/json":{"schema":{"type":"object","properties":{"format":{"type":"string","enum":["worker-layer-graph-v1","application-graph-v2"]},"repo":{"type":"string"},"commit":{"type":"string"},"types":{"type":"object","properties":{"format":{"anyOf":[{"type":"string","enum":["layer-type-facts-v1"]}]},"repo":{"type":"string"},"commit":{"type":"string"},"compiler":{"type":"object","properties":{"typescript":{"type":"string"},"effectTsgo":{"type":"string"}},"required":["typescript","effectTsgo"],"additionalProperties":true},"projects":{"type":"array","items":{"type":"string"}},"types":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"declarations":{"type":"array","items":{"type":"string"}},"request":{"anyOf":[{"type":"string","enum":["Requires","GlobalRequires","Error","GlobalError"]},{"type":"null"}]},"parameter":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["id","name","declarations"],"additionalProperties":true}},"facts":{"type":"array","items":{"type":"object","properties":{"nodeId":{"type":"string"},"status":{"type":"string","enum":["resolved","partial","unresolved"]},"role":{"type":"string","enum":["layer","program","carrier","callback"]},"typeName":{"type":"string"},"returns":{"type":"string","enum":["program","layer"]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"producesLayer":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"innerRequires":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"provides":{"type":"array","items":{"type":"string"}},"errors":{"type":"array","items":{"type":"string"}},"requires":{"type":"array","items":{"type":"string"}}},"required":["nodeId","status","provides","errors","requires"],"additionalProperties":true}},"composition":{"anyOf":[{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"file":{"type":"string"},"span":{"type":"object","properties":{"start":{"type":"integer"},"end":{"type":"integer"}},"required":["start","end"],"additionalProperties":true},"line":{"type":"integer"},"column":{"type":"integer"},"label":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"library":{"anyOf":[{"type":"string"},{"type":"null"}]},"reference":{"anyOf":[{"type":"string","enum":["module","effect","external"]},{"type":"null"}]},"local":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"layer":{"type":"boolean"},"combinator":{"anyOf":[{"type":"string"},{"type":"null"}]},"provides":{"type":"array","items":{"type":"string"}},"requires":{"type":"array","items":{"type":"string"}},"actualProvides":{"type":"array","items":{"type":"string"}}},"required":["id","file","span","line","column","label","layer","provides","requires","actualProvides"],"additionalProperties":true}},"edges":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"relationship":{"type":"string","enum":["pipe","call","arrayLiteral","symbol"]},"index":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["from","to","relationship"],"additionalProperties":true}},"anchors":{"type":"array","items":{"type":"object","properties":{"nodeId":{"type":"string"},"composition":{"type":"string"}},"required":["nodeId","composition"],"additionalProperties":true}}},"required":["nodes","edges","anchors"],"additionalProperties":true},{"type":"null"}]}},"required":["format","repo","commit","compiler","projects","types","facts"],"additionalProperties":true},"graphs":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"entryFile":{"type":"string"},"within":{"anyOf":[{"type":"string"},{"type":"null"}]},"instanceOf":{"type":"string"},"graph":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["root","layer","effect","service"]},"role":{"type":"string","enum":["layer","program","carrier","callback"]},"typeName":{"type":"string"},"body":{"type":"string","enum":["function","generator"]},"label":{"type":"string"},"location":{"type":"object","properties":{"file":{"type":"string"},"line":{"type":"integer"},"column":{"type":"integer"}},"required":["file","line","column"],"additionalProperties":true},"span":{"anyOf":[{"type":"object","properties":{"start":{"type":"integer"},"end":{"type":"integer"}},"required":["start","end"],"additionalProperties":true},{"type":"null"}]},"typeSource":{"anyOf":[{"type":"string","enum":["effect-tsgo","unresolved"]},{"type":"null"}]},"expansion":{"anyOf":[{"type":"string","enum":["dynamic","depth-limit"]},{"type":"null"}]},"scope":{"anyOf":[{"type":"string","enum":["isolate","invocation","global","location"]},{"type":"null"}]},"binding":{"anyOf":[{"anyOf":[{"type":"string","enum":["unbound"]}]},{"type":"null"}]},"reference":{"anyOf":[{"type":"string","enum":["module","local","parameter","effect","external"]},{"type":"null"}]},"declaration":{"anyOf":[{"type":"string"},{"type":"null"}]},"bound":{"anyOf":[{"type":"string"},{"type":"null"}]},"value":{"anyOf":[{"anyOf":[{"type":"string","enum":["yielded"]}]},{"type":"null"}]},"calls":{"anyOf":[{"type":"string"},{"type":"null"}]},"inside":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","kind","label","location"],"additionalProperties":true}},"edges":{"type":"array","items":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"kind":{"type":"string","enum":["provides","requires","provideMerge","providedTo","launch","merge","provide","uses","unwrap","branch","acquire","release","replaces","pipe","call","arrayLiteral","fallback"]},"meaning":{"type":"string","enum":["runs","callback","contains","provides"]},"location":{"type":"object","properties":{"file":{"type":"string"},"line":{"type":"integer"},"column":{"type":"integer"}},"required":["file","line","column"],"additionalProperties":true},"parameter":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"location":{"type":"object","properties":{"file":{"type":"string"},"line":{"type":"integer"},"column":{"type":"integer"}},"required":["file","line","column"],"additionalProperties":true}},"required":["id","name","location"],"additionalProperties":true},{"type":"null"}]}},"required":["from","to","kind","location"],"additionalProperties":true}}},"required":["nodes","edges"],"additionalProperties":true}},"required":["name","entryFile","graph"],"additionalProperties":true}}},"required":["format","repo","commit","graphs"],"additionalProperties":true}}}},"400":{"description":"Invalid query parameters.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"404":{"description":"The requested indexed resource does not exist.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"409":{"description":"Stale generation. Fetch status and restart discovery.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"500":{"description":"Unexpected server failure.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"503":{"description":"The corpus is unavailable or not ready.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}}}}},"/api/source":{"get":{"operationId":"getSource","summary":"Read a pinned source range","description":"Read at most 80 lines. Ranges crossing EOF return remaining lines; starts beyond EOF return 404 with source diagnostics. Use pinned line numbers, not local package line numbers.","parameters":[{"name":"generation","in":"query","required":true,"description":"Copy the published generation from GET /api/status. A 409 means it changed; restart discovery.","schema":{"type":"string","minLength":1}},{"name":"repo","in":"query","required":true,"description":"Repository name from GET /api/repositories.","schema":{"type":"string","enum":["effect","effect-solutions","rat-stack","opencode","maple","alchemy-effect","executor","foldkit","effect-agent","t3code","tardigrade","yielded-auth","effect-machine","effect-orm"]}},{"name":"path","in":"query","required":true,"description":"Use a source path returned by discovery.","schema":{"type":"string","minLength":1}},{"name":"startLine","in":"query","required":true,"description":"Inclusive 1-based start line.","schema":{"type":"integer","minimum":1}},{"name":"endLine","in":"query","required":true,"description":"Inclusive end line, at least startLine and at most startLine + 79.","schema":{"type":"integer","minimum":1}}],"security":[],"responses":{"200":{"description":"Successful retrieval.","content":{"application/json":{"schema":{"type":"object","properties":{"generation":{"type":"string","minLength":1},"repo":{"type":"string","enum":["effect","effect-solutions","rat-stack","opencode","maple","alchemy-effect","executor","foldkit","effect-agent","t3code","tardigrade","yielded-auth","effect-machine","effect-orm"]},"commit":{"type":"string"},"path":{"type":"string"},"sourceUrl":{"type":"string"},"totalLines":{"type":"integer"},"lines":{"type":"array","items":{"type":"object","properties":{"line":{"type":"integer","minimum":1},"text":{"type":"string"}},"required":["line","text"],"additionalProperties":true}}},"required":["generation","repo","commit","path","sourceUrl","totalLines","lines"],"additionalProperties":true}}}},"400":{"description":"Invalid query parameters.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"404":{"description":"The requested indexed resource does not exist.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"409":{"description":"Stale generation. Fetch status and restart discovery.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"500":{"description":"Unexpected server failure.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}},"503":{"description":"The corpus is unavailable or not ready.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ApiProblem"}}}}}}}}}