> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elanotes.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Search and list return handles, provenance, and coverage. Fetch a body only with GET /v1/notes/{note} (line slice) or /raw.
> Read coverage before treating a result set as complete. Zero hits with coverage is a valid answer.
> Follow error hint. Writes need an Idempotency-Key header and agent_id.
> The user creates personal access tokens in web Settings → Access tokens. Read is included; authenticated note mutations require notes.write. Supplying agent_id does not grant permission.
> Reuse an Idempotency-Key only for an identical retry. After VERSION_MOVED, re-read and submit the changed operation with a new key.
> Local MCP is read-only. Authenticated Cloud MCP adds write_note and edit_note only with notes.write and connected write storage; open local mode skips the permission check. Inspect tools/list before calling conditional tools.
> A queued write has not changed the note. Record pending_id. Authenticated GET /v1/writes/{id} also requires notes.review; write-only tokens must hand the ID to a reviewer.
> Leave approval to a human. Agents must not approve their own proposals or request review permission merely to finish a task. The API permits review-scoped personal tokens; this is a workflow rule.
> Cloud search and note reads do not return Private plaintext. Coverage says Private notes not searched. Sync may still carry ciphertext.
> Production origin is https://api.elanotes.com. baseUrl has no /v1 suffix.

# Quickstart

> Open Ela, search your notes, or call the HTTP API.

Ela is notes that remember. Search returns **handles + provenance + coverage**, never full bodies. Every write is idempotent. Every error carries a plain-English `hint`.

## Agents

Connect over [MCP](https://docs.elanotes.com/agents.md), the [HTTP API](https://docs.elanotes.com/api/overview.md), or `notes --remote` ([CLI](https://docs.elanotes.com/cli.md)).

This host serves `/llms.txt`, `/llms-full.txt`, and `/skill.md`. The machine-readable contract is OpenAPI 3.1:

* Served spec: `GET https://api.elanotes.com/openapi.json` (unauthenticated)
* Docs copy: this site’s API reference, production origin first

The stable HTTP path is `/v1`. Production: `https://api.elanotes.com`. Local clone: `http://127.0.0.1:4000`. `GET /openapi.json` and `GET /healthz` are unauthenticated. `/v1` and `/mcp` need a bearer in production.

Create a [personal access token](https://docs.elanotes.com/access-tokens.md) in web **Settings → Access tokens**. Read is included; select **Write notes** for authenticated note mutations. Keep review under human control. Use the copied token through `ELA_API_TOKEN` for HTTP, CLI, or SDK examples, or **Copy config** for Cloud MCP.

### Production

```bash theme={null}
curl -sf https://api.elanotes.com/healthz
curl -sS -o /dev/null -w "%{http_code}\n" https://api.elanotes.com/openapi.json
curl -sS -o /dev/null -w "%{http_code}\n" https://api.elanotes.com/v1/vault
```

`/healthz` returns `{"status":"ok"}`. `/openapi.json` returns `200`. `/v1/vault` and `POST /mcp` with no token return `401` and `reason: AUTH_MISSING`. A `503` means storage did not come up. Do not add a trailing slash.

The served spec is `https://api.elanotes.com/openapi.json`. This site’s API reference uses that origin first, then `http://127.0.0.1:4000`.

### Local API in five commands

```bash theme={null}
pnpm install
docker compose up -d
pnpm --filter @elanotes/api dev
curl -sf localhost:4000/healthz
curl -sf "localhost:4000/v1/search?q=Paddle"
```

Point `VAULT_PATH` at a markdown folder (the in-repo fixture is
`packages/evals/fixtures/vault-small`). Leave auth unset for an open local
path. Details: engineering [day-to-day setup](https://github.com/elavize/elanotes/blob/main/docs/setup/day-to-day.md).

On vault-small, `q=Paddle` returns slug `payments-provider-decision` plus a
coverage block. `private/` is excluded from cloud-shaped results.

### First write

```bash theme={null}
curl -sS -X POST localhost:4000/v1/notes \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"path":"inbox/hello.md","content":"# Hello\n","agent_id":"quickstart"}'
```

Applied receipts embed `note` (GET shape without `lines`). Queued receipts
are followable at `GET /v1/writes/{id}` with `notes.review` in authenticated mode. With a write-only token, report `pending_id` and hand it to a reviewer. The example above uses open local mode. A `409` `VERSION_MOVED` means
re-read, then retry with the current `version_id` and a fresh
`Idempotency-Key`. Follow `hint`.

## Surfaces

> [card] [Notes](https://docs.elanotes.com/using-notes.md)
>
> Create, edit, delete. The folder is the note.

> [card] [Agents](https://docs.elanotes.com/agents.md)
>
> MCP, HTTP, CLI. Coverage on every response.

> [card] [Web](https://docs.elanotes.com/web.md)
>
> Next.js three-pane notes app on `:3000`.

> [card] [Desktop](https://docs.elanotes.com/desktop.md)
>
> Unsigned Electron. Local vault first.

> [card] [CLI](https://docs.elanotes.com/cli.md)
>
> `notes --remote` through `@elanotes/sdk`.

> [card] [MCP](https://docs.elanotes.com/mcp-local.md)
>
> Local stdio or cloud `POST /mcp`.

> [card] [API overview](https://docs.elanotes.com/api/overview.md)
>
> Host, auth, errors, filters, masks, limits.

> [card] [Typed SDKs](https://docs.elanotes.com/sdk-ts.md)
>
> TypeScript `@elanotes/sdk` and Python `elanotes`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.