# Lev developer resources

Build on Lev with the REST API, OpenAPI description, MCP server, authentication model, and agent-facing docs. This page is the predictable index for developer tools so a name-based search for Lev API, Lev MCP, or Lev OpenAPI lands on a real resource instead of a marketing shell.

## Resources

### [Lev API overview](https://www.lev.com/docs/build/api-overview)

REST JSON API at https://api.lev.com/api/external/v2 for deals, documents, CRM, lenders, term sheets, and market data.

### [OpenAPI description](https://www.lev.com/docs/openapi.json)

OpenAPI 3.1 spec reconstructed from the documented endpoints. Also linked from /.well-known/api-catalog.

### [Authentication and API keys](https://www.lev.com/docs/build/authentication)

Bearer API keys (lev_sk_) for server-to-server jobs and Auth0 JWTs for interactive and MCP clients.

### [Scoped permissions](https://www.lev.com/developers#scoped-permissions)

OAuth scopes, API key inheritance, workspace roles, and the ai:actions platform scope for credit-charging writes.

### [Rate limits](https://www.lev.com/docs/build/rate-limits)

Per-account and per-endpoint request budgets and 429 retry_after_seconds.

### [Versioning and deprecation](https://www.lev.com/developers#versioning-and-deprecation)

URL versioning under /api/external/v2, breaking-change policy, and Sunset/Deprecation signaling.

### [Lev MCP](https://www.lev.com/docs/build/mcp)

Streamable HTTP MCP at https://mcp.lev.com/mcp. Tool catalog, OAuth, and setup for Claude, Cursor, and ChatGPT.

### [MCP tools](https://www.lev.com/docs/build/mcp/tools)

Public listing of the 60 registered tools across 13 groups, with read/write classification and REST counterparts.

### [CLI setup](https://www.lev.com/docs/build/cli-setup)

Documented Lev CLI command surface. The pipx package is not on PyPI yet; use the REST API or MCP until GA.

### [Docs for agents](https://www.lev.com/docs/llms.txt)

Compact docs index plus /docs/llms-full.txt and per-page .md representations from the docs site.

## Scoped permissions

Agents should request only the access they need. Lev separates identity scopes from resource authorization.

### OAuth scopes (MCP)

The Lev MCP server asks Auth0 for two identity scopes during the authorization-code + PKCE flow:

- `openid` — identifies the signed-in user so the server can read the Auth0 subject claim.
- `email` — correlates the Auth0 identity with the Lev user record.

Those scopes authenticate the session. They do not expand what the user can do. Every MCP tool call is authorized against the live Lev workspace role. A 403 means the Lev user cannot access that resource. Role changes take effect on the next tool call; the server does not cache authorization decisions. Call `get_my_profile` to inspect the active account and platform-level scopes for the session.

### API keys and workspace roles

API keys are prefixed `lev_sk_` and inherit the creating user's account permissions. A key cannot access resources the user cannot access. Workspace admins manage keys. Key presets are `full_access` and `read_only`. Workspace and Vault roles (Full Access, View Only, Invite Only, Limited Access, and Read-Only) are separate from those key presets. Revocation is immediate and subsequent requests return 401.

### Platform scopes

Some writes are additionally gated by platform scopes. `POST /contacts/{contact_id}/actions/unlock` charges credits and requires the `ai:actions` scope. Treat credit-charging or irreversible external actions as confirming writes: preview first, then require an explicit user confirmation.

Use the narrowest path that matches the job: a read-only API key for sync jobs, an OAuth MCP session for interactive agents, and a user whose workspace role already matches the resources the agent should see.


## Versioning and deprecation

Stable Lev REST operations live under the major path `/api/external/v2` on `https://api.lev.com`. Breaking changes require a new major path. Additive fields, new endpoints, and new optional parameters may appear on the current major version without a path change.

When an operation or field is deprecated, Lev will:

1. Document the replacement in the API reference and changelog.
2. Keep the old operation available for at least one stable major version after the announcement.
3. Signal deprecation on affected responses with RFC 9745 `Deprecation` and, when a removal date is scheduled, `Sunset` headers.

Agents should treat the presence of a `Deprecation` header as a warning to migrate. RFC 9745 values are dates (for example `@1688169599`); parse that date when present. Honor `Sunset` as the last-response date, and prefer `operationId` values from the OpenAPI description over hand-written paths. The health endpoint `GET /api/external/v2/health` is unauthenticated and is the liveness probe for the current major version.

The marketing site's machine-readable catalogs (`/openapi.json`, `/.well-known/api-catalog`, `/llms.txt`) point at the current documented major version. Do not integrate against undocumented preview hosts.


## Rate limit headers

Authenticated Lev API endpoints apply per-account and per-endpoint request-per-minute budgets. Default authenticated buckets:

| API tier | Account-wide | Per-endpoint |
| --- | --- | --- |
| free | 30/minute | 10/minute |
| standard | 100/minute | 20/minute |
| enterprise | 500/minute | 60/minute |

Public unauthenticated endpoints: `POST /api/external/v2/auth/validate-api-key` is 10/minute; `GET /api/external/v2/health` is 100/minute.

A 429 body includes `retry_after_seconds`. Agents should back off on 429, honor `Retry-After` when present, and use `GET /me` `platform.rate_limits` for the configured budget. Do not require RFC `RateLimit` headers until the API documents them.