# Effect Grep public API

Read-only corpus retrieval. No authentication is required. All query parameters must be URL encoded.

The machine-readable contract is at /openapi.json. Public retrieval endpoints require no token; admin indexing operations are separate.

Start with GET /api/status. It returns ready, generation, and files. When ready is false, retrieval is unavailable. Copy generation into every corpus query below. A 409 response means the generation changed: fetch status and restart instead of mixing results. A 503 means the index is unavailable.

- GET /api/catalog?generation=GEN lists packages. Add package=effect to list modules; add module=Effect to list members. This is the indexed Effect API inventory, distinct from the site's discovery catalog.
- GET /api/repositories lists the ready published generation's repositories, pinned commits, source URLs, register classification, indexed file counts, and graphAvailable. It takes no parameters. A published graph artifact does not guarantee complete coverage.
- GET /api/uses?generation=GEN&symbol=Effect.gen lists source-addressable uses. Optional repo and offset filter and paginate results. Other packages use symbols such as @effect/platform/HttpServer.serve.
- GET /api/graphs?generation=GEN&repo=REPO returns the repository's indexed application graph artifact.
- GET /api/source?generation=GEN&repo=REPO&path=PATH&startLine=1&endLine=40 reads authored source. Ranges are 1-based and at most 80 lines. Use repository names and paths from retrieved results.

Successful responses are JSON. Errors use RFC 9457 application/problem+json with type, title, status, detail, code, message, and resolution. The legacy error string is preserved. Generation and source diagnostics remain present when available. A stale_generation error requires restarting discovery; a not_ready error requires waiting for readiness. Invalid queries return 400; missing indexed data returns 404. Generation-addressed successful responses may be cached immutably. Source provenance is pinned to repository commits; partial or unresolved graph facts do not establish complete runtime behavior.

For capability discovery, repository discovery, bounded examples, and graph inspection, connect an MCP client to /mcp using Streamable HTTP. Discover the read-only tools through tools/list: find_capabilities, list_repositories, find_examples, get_application_graph, inspect_graph_part, get_source. Omit query from find_capabilities to browse responsibilities before selecting APIs. The server is stateless and requires no session affinity. Its server card is at /mcp/server-card. The downloadable retrieval skill is at /.well-known/agent-skills/effect-grep/SKILL.md.