# Quickstart

> Start with a REST API request in under 5 minutes, connect Lev to an MCP client in about 10, or install the CLI and query deals from the terminal in under 5.

Source: https://www.lev.com/docs/build/getting-started

Last updated: May 2026

---
## Choose a path

Three branches, same destination: a working connection to Lev that you can trust for the rest of the build.

  
  
  

Before you start

- A **Lev account** with API access enabled.
- A way to generate an API key — the Lev web app or the API itself.
- A client you want to test with: `curl`, `fetch`, `requests`, Cursor, Claude, or the Lev CLI.

## Path A: First REST API call

Three phases: create a key, confirm it works, then fetch your first page of deals.

Generate the credential every later call signs with.

1. **Open Settings.** Sign in to [app.lev.com](https://app.lev.com), click your name at the bottom of the sidebar, then click **Settings**.
2. **Create the key.** Select the **API Keys** tab, click **Create key**, enter a label like "Quickstart Key", and click **Create**.
3. **Copy the key immediately.** The full value is only shown once — store it in a secret manager before closing the dialog.

The full API key is only displayed at creation time. If you lose it, revoke it and create a new one.

If you are automating key provisioning instead of using the web app, create a key via the API:

Prove the key works and see exactly which resources it can reach before you ship any real calls.

1. **Send the validation request.** Call `POST /api/external/v2/auth/validate-api-key` with the key in the request body.
2. **Confirm `valid: true`.** A `200` response with `"valid": true` means Lev accepted the key.
3. **Read the `scopes` array.** The scopes list tells you which endpoints this key can call — save it for the next phase.

### `POST /api/external/v2/auth/validate-api-key`

Validate an API key and receive authentication details

Response: `200`

Hit a real read endpoint so you know end-to-end auth, routing, and pagination are working.

1. **Send a paginated read.** Call `GET /api/external/v2/build/deals?limit=5` with your API key in the `Authorization` header.
2. **Verify the payload shape.** Confirm the response includes a `data` array and a `pagination` object with `has_more` and `next_cursor`.
3. **Troubleshoot failures by status.** A `401` means your `Authorization` header is wrong; a `403` means the key's scopes don't cover deals — inspect `granted_scopes` from `GET /me` or the previous validation response.

**Example response:**

```json
{
  "request_id": "a1b2c3d4-...",
  "timestamp": "2026-03-20T15:30:45Z",
  "data": [
    {
      "id": 101,
      "title": "123 Main St Acquisition",
      "loan_amount": 5000000.0,
      "loan_type": "heavy_bridge",
      "transaction_type": "acquisition",
      "created_at": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 5,
    "cursor": "eyJpZCI6IDEwMX0=",
    "has_more": true,
    "next_cursor": "eyJpZCI6IDEwNn0="
  }
}
```

**Next:** [Authentication](/build/authentication) for the full auth model, required headers, and every failure mode.

## Path B: First MCP integration

Three phases: choose the right auth model, point your MCP client at Lev, then verify the connection with a safe read.

Decide whether the MCP client will sign in interactively or carry a long-lived credential — the choice drives the rest of the config.

1. **Use JWT / OAuth for interactive clients.** If the user signs in through the client UI (Cursor, Claude), pick JWT / OAuth so each session is scoped to that user.
2. **Use an API key only for server bridges.** Reserve API keys for server-side bridges that can safely hold a long-lived credential in a secret store.
3. **Plan your `X-Origin-App` value.** Always send a meaningful `X-Origin-App` header so Lev can identify the calling surface in logs and rate limits.

Wire the client to Lev — the exact config shape varies by client, but the core pieces are the same.

1. **Point the client at the Lev MCP URL.** Use `https://mcp.lev.com/mcp` as the server URL in your client's MCP configuration.
2. **Enable OAuth or paste a token.** Follow the client's prompt for OAuth, or paste an API key if you are running a server bridge.
3. **Set the origin header.** Include `X-Origin-App` with a descriptive value like `cursor-lev-quickstart`.

**Example MCP client config**

### Cursor / Claude-style JSON

```json
{
  "mcpServers": {
    "lev": {
      "url": "https://mcp.lev.com/mcp",
      "headers": {
        "X-Origin-App": "cursor-lev-quickstart"
      }
    }
  }
}
```

### What to verify

```markdown
- The client can see the Lev server
- OAuth or token auth completes successfully
- Tool discovery succeeds
- A simple read action returns account-aware data
```

Confirm the connection is account-aware before you trust it with real work.

1. **Ask an identity question.** Prompt the client: "What account am I connected to in Lev?" — the answer should name your workspace.
2. **Request a small read.** Ask for "my first five deals" and confirm the client returns real, scoped data.
3. **Inspect granted scopes.** Ask "Which scopes are granted to this connection?" — compare against the scopes you expected from Path A or your config.

**Next:** [MCP Setup](/build/mcp/setup) for client-specific configuration and troubleshooting.

## Path C: First CLI query

Three phases: install the binary, authenticate once, then fetch deals from the terminal.

Put the `lev` binary on your PATH so every later command resolves.

1. **Install with pipx.** Run `pipx install lev-cli` (requires Python 3.13+).
2. **Verify the binary resolves.** Run `lev --version` and confirm you see a version string.
3. **Pick an alternative install if needed.** See [CLI Setup](/build/cli-setup) for Homebrew, standalone binaries, and Windows installers.

Store your API key in the OS keychain so later commands don't have to prompt.

1. **Start the login flow.** Run `lev auth login`.
2. **Paste your API key when prompted.** The key is stored in your OS keychain — never written to a file.
3. **Create a key first if you don't have one.** If you skipped Path A, create a key in [app.lev.com](https://app.lev.com) under **Settings → API Keys**.

```bash
lev auth login
```

Confirm the CLI is connected and see the agent-friendly JSON output mode.

1. **Check auth status.** Run `lev auth status` and confirm the connection is active.
2. **List deals.** Run `lev deals list` — the CLI prints a formatted table in an interactive terminal.
3. **Pipe to JSON for agents.** When piped, the CLI auto-switches to JSON, which an LLM coding agent can parse directly.

```bash
lev auth status        # Confirm connection
lev deals list         # Fetch your deals (table)

# Example: an agent or script capturing JSON output
lev deals list -o json | jq '.data[0].title'
```

**Next:** [CLI Setup](/build/cli-setup) for the full walkthrough and CI/CD patterns.

## Next steps

Go one level deeper based on what you are building:

- **[Authentication](/build/authentication)** — Learn the auth model, required headers, and failure modes in detail.
- **[Deals](/build/deals)** — Start with the core deal resource if you are building a product integration.
- **[MCP Setup](/build/mcp/setup)** — Continue from the MCP path with client-specific setup and troubleshooting.
- **[CLI Commands](/build/cli-commands)** — Full command reference with syntax, flags, and output examples.
- **[Data Sync Patterns](/build/data-sync-patterns)** — Use the production sync recipe when you are moving data into another system.