# Elide Developer Resources

> Read the Elide documentation from code and AI agents: llms.txt, Markdown pages, a search API with OpenAPI, and an MCP server that also takes bug and performance reports.

Every surface on this page is public and needs no API key. Responses allow any origin. Only the MCP server's
`submit_report` tool writes anything, and only after the developer agrees.

| Resource | URL |
| --- | --- |
| Documentation index for LLMs | [/llms.txt](https://elide.help/llms.txt) |
| Every page in one file | [/llms-full.txt](https://elide.help/llms-full.txt) |
| Docs API (OpenAPI 3.1) | [/openapi.json](https://elide.help/openapi.json) |
| API catalog (RFC 9727) | [/.well-known/api-catalog](https://elide.help/.well-known/api-catalog) |
| MCP server (Streamable HTTP) | `https://elide.help/mcp` |
| MCP server card | [/mcp/server-card](https://elide.help/mcp/server-card) |
| AI catalog | [/.well-known/ai-catalog.json](https://elide.help/.well-known/ai-catalog.json) |
| Sitemap | [/sitemap-index.xml](https://elide.help/sitemap-index.xml) |

## Markdown pages

Append `.md` to any page URL, or request the page with `Accept: text/markdown`:

```bash
curl https://elide.help/docs/installation.md
curl -H 'Accept: text/markdown' https://elide.help/docs/installation
```

HTML pages link to their Markdown version with `<link rel="alternate" type="text/markdown">` and a `Link` response
header. A missing page requested as Markdown returns a Markdown 404 that links to `/llms.txt`.

## Docs API

Base URL `https://elide.help`. Every operation is a `GET`.

| Operation | Request | Returns |
| --- | --- | --- |
| `getApiIndex` | `/api/v1` | Version, status, every operation, the rate limit and the versioning policy |
| `listPages` | `/api/v1/pages?section=toolchain` | Every page (or one section) with slug, URLs, title and description |
| `getPage` | `/api/v1/pages/{slug}` | One page with its headings and Markdown |
| `searchDocs` | `/api/v1/search?q=…&limit=…` | Ranked pages with a snippet and the best-matching heading |
| `getReportStatus` | `/api/v1/reports/{id}` | The status of a report sent with `submit_report`, and its issue URL once filed |

```bash
curl 'https://elide.help/api/v1/search?q=kotlin%20compiler&limit=3'
curl https://elide.help/api/v1/pages/installation
curl 'https://elide.help/api/v1/pages?section=api'
```

### Versioned search

The default search remains local structural search over current English documentation. Hosted search is opt-in on
deployments with a published [search manifest](https://elide.help/_agent/search-manifest.json) and a configured provider. It never
silently substitutes local results for hosted results.

| `mode` | Matches |
| --- | --- |
| `local` | Current English pages and sections using the shared local ranking |
| `bm25` | Full text, with titles and headings weighted above body text |
| `vector` | Semantic similarity using the snapshot's embedding model |
| `hybrid` | BM25 and vector candidates combined by reciprocal rank fusion |
| `phrase` | Consecutive indexed tokens, ranked with BM25 |
| `regex` | Rust regular expressions within indexed text chunks |
| `glob` | Case-sensitive glob patterns within indexed text chunks |

Use `version=latest` or an exact published documentation version and `locale=en`. The manifest identifies the
immutable namespace and revision behind each version; unavailable versions and locales return `404`. The API path
version (`/api/v1`) is separate from the documentation version. Only published snapshots are available.

`section=api` or `kind=page|section|sample|release|gap` narrows results. `limit` is 1–50 and `q` is at most 200
characters. Regex does not support look-around or backreferences; regex, glob and phrase matches cannot span chunk
boundaries. Regex and glob return matches in stable ID order. Other modes rank by relevance. Scores are normalized
within each response and should not be compared across queries or modes. Optional `rerank=true` uses model reranking
for BM25, vector or hybrid candidates, adding provider work and latency.

```bash
curl 'https://elide.help/api/v1/search?mode=hybrid&q=call%20Python%20from%20JavaScript&version=latest'
curl -H 'Accept: text/markdown' 'https://elide.help/api/v1/search?mode=bm25&q=compiler&section=toolchain'
curl 'https://elide.help/api/v1/search?mode=regex&q=elide%20%28run%7Cbuild%29&format=text'
```

`format=json|markdown|text` overrides the `Accept` header. All formats represent the same result set; JSON includes
the resolved `docsVersion`, `locale`, `mode`, `backend` and hosted `revision`. Explicit search responses support
`HEAD`, `ETag`, `If-None-Match` and `Vary: Accept`. Successful hosted responses are cached for five minutes per
immutable snapshot, complete query options and format. `X-Search-Cache` reports `HIT`, `MISS` or `BYPASS`; provider
errors are never cached. `X-Search-Backend-Cache` reports the regional cache status, or `BYPASS` on an edge cache hit.
A regional private Worker can share provider results across formats and edge locations
without exposing the database credential. Requests remain subject to the public API rate limit.

### Streaming search

The experimental service accepts WebSocket connections at
`wss://elide-docs-search.elidecloud.workers.dev/search/ws` with subprotocol `elide-search.v1`.
It needs no cookies or authentication. Each JSON text message is a search with a fresh UUID `id` and string-valued
`params`, or a cancellation for that ID:

```json
{"type":"search","id":"953f081d-b824-4a2a-8b82-e4dc533ee738","params":{"q":"call Java libraries","mode":"vector","version":"latest","locale":"en","limit":"8","telemetry":"off"}}
{"type":"cancel","id":"953f081d-b824-4a2a-8b82-e4dc533ee738"}
```

The server sends `ready` with the protocol, then `accepted` with the search ID. Results carry
`{type:"results",id,phase,complete,status,headers,body}`. The body follows the JSON search response, and headers
include its request ID, count, version, locale and revision. The ID is also the search request ID; an optional
`request_id` parameter must match it. Messages with invalid envelopes receive `type:"error"` with `code` and `message`.
Search validation failures retain the HTTP status and problem body in a terminal results message.

`phase:"preview"` is an early shortlist of at most three matches from the same snapshot's compact structural index
at the edge, with `mode:"local"` and `backend:"local"`. It is available for relevance modes when a matching English
preview is bundled. Streaming vector cache misses also start one parallel BM25 search for at most three results.
If it completes first, another `preview` arrives with `mode:"bm25"` and `backend:"turbopuffer"`; its results can be
merged with the structural shortlist. Each retrieval leg uses the existing shared cache. Preview frames have
`complete:false`. Optional `phase:"retrieval"` is reserved for cumulative provider results when a provider transport
can deliver them incrementally; the current transport returns completed result sets. `phase:"complete"` with
`complete:true` is the canonical result, or terminal HTTP error. A cache hit can go directly to completion.
The structural shortlist does not wait for provider work. Completion or cancellation suppresses late lexical frames;
cancellation also suppresses pending telemetry. Already issued events cannot be recalled.

The channel supports JSON only; use HTTP for Markdown or plain text. Search parameters, five-minute result caching,
and per-IP rate limits match HTTP. Each handshake and search consumes admission. Only completed results enter the
shared cache. `telemetry=off` in search parameters or the connection URL disables analytics; DNT and GPC from the
handshake also apply to every search. Headers and cookies cannot be supplied through message parameters.
Sessions allow two concurrent searches, 120 unique searches, 256 messages, and 4 KiB per text message. Cancelled work
retains its concurrency slot until it settles. Sessions close after 60 seconds idle or five minutes total; reconnect
when needed. Stop using partial results after their search is cancelled, superseded, or fails snapshot or response
integrity validation. Validated previews may remain usable when the provider fails transiently.

### Errors

Errors use `application/problem+json` (RFC 9457). Each has a stable `code` and a `resolution` that says what to
change.

| Status | `code` | When |
| --- | --- | --- |
| 400 | <span id="error-invalid-parameter">`invalid_parameter`</span> | `q` is missing or too long, `limit` is out of range, or `section` is unknown |
| 404 | <span id="error-page-not-found">`page_not_found`</span> | No page has the requested slug |
| 404 | <span id="error-report-not-found">`report_not_found`</span> | No report has the requested id |
| 404 | <span id="error-api-route-not-found">`api_route_not_found`</span> | No operation exists at the path |
| 404 | <span id="error-search-version-not-found">`search_version_not_found`</span> | No search snapshot exists for the requested documentation version and locale |
| 405 | <span id="error-method-not-allowed">`method_not_allowed`</span> | The method is not `GET` or `HEAD`; see the `Allow` header |
| 406 | <span id="error-not-acceptable">`not_acceptable`</span> | Search cannot provide a representation allowed by `Accept` |
| 429 | <span id="error-rate-limited">`rate_limited`</span> | More than 120 requests in 60 seconds; wait for `Retry-After` |
| 502 | <span id="error-search-upstream-failure">`search_upstream_failure`</span> | The search provider returned an invalid response |
| 503 | <span id="error-search-unavailable">`search_unavailable`</span> | Hosted search is unconfigured, has no published snapshot, is unavailable or timed out |

```json
{
  "type": "https://elide.help/developers#error-page-not-found",
  "title": "Page not found",
  "status": 404,
  "detail": "No documentation page has the slug \"instalation\".",
  "instance": "https://elide.help/api/v1/pages/instalation",
  "code": "page_not_found",
  "resolution": "List slugs with GET /api/v1/pages, or find a page with GET /api/v1/search?q=<terms>.",
  "documentation_url": "https://elide.help/developers#errors"
}
```

### Rate limits

The API and the MCP server allow 120 requests per 60 seconds per client IP. Every response carries
`RateLimit-Policy: "docs";q=120;w=60`. Over the limit, the response is a `429` with `Retry-After` and
`RateLimit: "docs";r=0;t=60`. For bulk reads, fetch [/llms-full.txt](https://elide.help/llms-full.txt) once.

### Versioning

The version is in the path: `/api/v1`. Changes within `v1` only add fields and operations. A breaking change ships as
`/api/v2`; `v1` then sends `Deprecation` and `Sunset` headers (RFC 9745, RFC 8594) for at least 180 days before it is
removed.

## MCP server

`https://elide.help/mcp` serves the docs over the Model Context Protocol with the Streamable HTTP transport and needs no
authentication. It is stateless, except that a `2025-06-18` or `2025-11-25` client that declares elicitation gets an
`Mcp-Session-Id` so `submit_report` can ask the developer for consent. Supported protocol versions: `2026-07-28`,
`2025-11-25`, `2025-06-18` and `2025-03-26`.

| Tool | Does |
| --- | --- |
| `search_docs` | Search pages, sections, code samples, release notes and documented gaps; returns slugs, headings, anchors and 0–1 scores. |
| `get_page` | Return one page as Markdown, by slug, path or URL. |
| `list_pages` | List pages with slugs and descriptions, optionally for one section. |
| `find_samples` | Find runnable code samples by query, language, tag or level, with their command and output. |
| `compare_runtimes` | Compare Elide with Node, Bun, Deno, CPython, Java or Kotlin; every claim cites its source and measurement. |
| `get_benchmarks` | Every published benchmark number with its command, machine, date and recording. |
| `check_known_issue` | Find open Elide issues and earlier reports that match a problem. |
| `preview_report` | Validate and redact an `elide.report/1` report, find duplicates, list missing evidence, and show the issue it would become. Stores nothing. |
| `submit_report` | Send a report after the developer agrees; it becomes a public issue in `elide-dev/elide`. |
| `report_status` | The status of a sent report: queued, filed, duplicate, declined or needs_human. |

Every page is also a resource with a `text/markdown` body, and the benchmark, comparison and compatibility data are
JSON resources under `https://elide.help/_agent/`. The `compare` and `migrate` prompts wrap the comparison and
migration workflows. Client config:

```json
{
  "mcpServers": {
    "elide-docs": { "type": "http", "url": "https://elide.help/mcp" }
  }
}
```

Claude Code:

```bash
claude mcp add --transport http elide-docs https://elide.help/mcp
```

### Reporting problems

Agents report Elide bugs, slow runs, unexpected behavior and missing features with the developer's consent:

1. `elide agent bug --kind <bug|perf|expectation|feature> --json` prints an `elide.report/1` skeleton with the Elide
   version and platform filled in. For a slow run, `elide agent perf --json [--baseline "<cmd>"] -- <cmd>` prints the
   measured `perf` block.
2. `check_known_issue` finds an existing issue; `submit_report` with `duplicate_of` adds a +1 to it.
3. `preview_report` redacts home paths, tokens, keys, emails and IP addresses, shows the issue body, and returns a
   `confirm_token` for an accepted report.
4. `submit_report` with that `confirm_token`, once the developer agrees, stores the report; headless runs such as
   `claude -p` and `codex exec` must use it, because they answer consent prompts themselves. Without a token,
   `submit_report` asks the developer through elicitation when the client supports it, or returns a `confirm_token` to
   pass on a second call.

Reports become public issues in `elide-dev/elide`, usually within the hour; `report_status` and
`GET /api/v1/reports/{id}` track them. Each client IP can send 10 report calls a minute and 20 reports an hour.

[Docs MCP server](https://elide.help/docs/mcp-docs) lists every tool, including the reporting tools, with prompts, resources and rate
limits; [Report a problem](https://elide.help/docs/agentic-reporting) covers report kinds and consent.

This server answers questions about Elide and takes reports. To give an agent Elide's build and run tools inside a
project, run `elide mcp`; see [Project MCP server](https://elide.help/docs/mcp).

## Elide in agents and scripts

Install the CLI:

```bash
curl -sSL --tlsv1.2 elide.sh | bash -s -     # Linux and macOS
brew install elide-dev/elide/elide           # Homebrew
```

[Installation](https://elide.help/docs/installation) covers Windows, packages and containers.

- [Elide for AI Agents](https://elide.help/docs/agents): non-interactive flags, commands that need a terminal, and exit codes.
- `elide help <topic> --format=markdown` prints any page of these docs from an installed `elide`.
- [CLI Reference](https://elide.help/docs/cli-references) lists every command.

Report problems with the MCP server's `submit_report` tool or on
[GitHub issues](https://github.com/elide-dev/elide/issues). For immediate help, join the
[Elide Discord](https://elide.dev/discord).