# Ezel

> Ezel is an AI legal platform for drafting documents, researching U.S. case law, and managing legal matters. The Ezel REST API and MCP server give programmatic, authenticated access to your matters, documents, cited Q&A grounded in your own files, real U.S. case law search, and review tables (document-by-question extraction grids).

Base URL for the API: https://app.ezel.ai/api/v1
Authentication: send a personal API key as the header `Authorization: Bearer ezel_live_...` (the header `X-API-Key` is also accepted). Keys carry `read` and/or `write` scopes and are created in the Ezel app under Settings > Connector. The same key works for both the REST API and the MCP server.

Key facts for agents:
- Everything is organised around "matters" (cases/projects) and the documents inside them. All responses are JSON.
- Beyond a typical assistant API, Ezel exposes real citable U.S. case law (via CourtListener, not a model's memory) and keyword/regex search across the user's own uploaded documents.
- The `/ask` endpoints accept a `stream` flag for Server-Sent Events.
- Errors are `{"error":{"type","message"}}` with standard HTTP status codes (401 unauthorized, 403 forbidden/insufficient_scope, 404 not_found, 429 usage_limit/rate_limited).

## Documentation
- [API reference, full markdown](https://ezel.ai/llms-full.txt): The complete REST API + MCP reference as a single plain-markdown file. Best starting point for an LLM, one fetch gives you every endpoint, parameter, and example.
- [API reference, web](https://ezel.ai/docs): The human-readable, three-column API reference.
- [OpenAPI 3.0 specification](https://app.ezel.ai/api/v1/openapi.json): Machine-readable OpenAPI document for codegen and tooling.

## Getting started
- [Authentication](https://ezel.ai/docs#authentication): How to send your API key as a bearer token.
- [Scopes](https://ezel.ai/docs#scopes): The `read` and `write` permission scopes on a key.
- [Rate limits](https://ezel.ai/docs#rate-limits): Per-key, per-category request limits and the `RateLimit-*` headers.
- [Errors](https://ezel.ai/docs#errors): The error envelope and status codes.

## REST API endpoints
- [GET /whoami](https://ezel.ai/docs#whoami): Verify a key; returns the account, plan, the key's scopes, and enabled features.
- [GET /usage](https://ezel.ai/docs#usage): Storage usage and current message-limit status.
- [GET /matters](https://ezel.ai/docs#list-matters): List the user's matters, each with a document count.
- [POST /matters](https://ezel.ai/docs#create-matter): Create a matter (scope: write).
- [GET /matters/{matter_id}](https://ezel.ai/docs#get-matter): Get one matter.
- [DELETE /matters/{matter_id}](https://ezel.ai/docs#delete-matter): Delete a matter; its files/chats are released, not deleted (scope: write).
- [GET /matters/{matter_id}/files](https://ezel.ai/docs#list-files): List a matter's documents.
- [POST /matters/{matter_id}/files](https://ezel.ai/docs#upload-file): Upload a document (multipart, indexed for search, OCR for scans; scope: write).
- [DELETE /matters/{matter_id}/files/{file_id}](https://ezel.ai/docs#delete-file): Delete a document (scope: write).
- [POST /ask](https://ezel.ai/docs#ask): General U.S. legal question with research mode; optional SSE streaming.
- [POST /matters/{matter_id}/ask](https://ezel.ai/docs#ask-matter): Cited answer grounded only in a matter's documents; optional SSE streaming.
- [POST /matters/{matter_id}/search](https://ezel.ai/docs#search-matter): Keyword or regex search across a matter's documents (AND/OR, count-only).
- [GET /caselaw/search](https://ezel.ai/docs#caselaw-search): Search real U.S. case law (CourtListener), ranked by relevance.
- [GET /cases/{cluster_id}](https://ezel.ai/docs#get-case): Fetch the full opinion text for a case.
- [POST /matters/{matter_id}/review-tables](https://ezel.ai/docs#create-review-table): Create and run a document-by-question extraction grid (scope: write).
- [GET /review-tables/{table_id}](https://ezel.ai/docs#get-review-table): Read a review table's columns, rows, and extracted cells.
- [POST /review-tables/{table_id}/run](https://ezel.ai/docs#run-review-table): Re-run a review table (scope: write).

## MCP
- [Connect over MCP](https://ezel.ai/docs#mcp): Use Ezel from Claude (claude.ai/Desktop), Cursor, Claude Code, and ChatGPT. Server URL: https://app.ezel.ai/mcp. Claude connects via OAuth; other clients use the same API key as a bearer token. Read-only tools: ezel_list_matters, ezel_ask_matter, ezel_ask, ezel_search_caselaw, ezel_get_case.