Quickstart

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.

1. Create an API key

   Generate the credential every later call signs with.

   1. Open Settings. Sign in to 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.

   Copy your key now

   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:

   You have an API key that starts with lev_sk_ saved somewhere safe.
2. Validate the key and inspect scopes

   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

   Request body:

   {
     "api_key": "lev_sk_abc123def456..."
   }

   Response (200):

   {
     "request_id": "...",
     "data": {
       "valid": true,
       "user_id": 1234,
       "account_id": 56,
       "scopes": ["deals:read", "deals:write", "contacts:read"],
       "tier": "standard"
     }
   }

   A 200 OK response with "valid": true, a user_id, an account_id, and a non-empty scopes array.
3. Fetch your first page of deals

   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:

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

   A 200 OK with up to five deal objects and a pagination.has_more flag.

Next: 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.

1. Confirm the auth model you want

   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.

   You know which auth path to configure and what X-Origin-App string to send.
2. Add Lev to your MCP client

   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://api.levcapital.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.

   Cursor / Claude-style JSON

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

   2 examples. View source for the rest.

   Lev appears as a connected MCP server in your client's integrations list.
3. Verify the connection with a safe read

   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.

   Account-aware replies to all three prompts, with scope data that matches your setup.

Next: 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.

1. Install the CLI

   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 for Homebrew, standalone binaries, and Windows installers.

   Running lev --version in any new terminal returns a version string.
2. Authenticate

   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 under Settings → API Keys.

   lev auth login

   The CLI confirms it is authenticated and shows which user / account it is connected to.
3. Verify and fetch deals

   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.

   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'

   A formatted table when running interactively, and structured JSON when piping to another command.

Next: CLI Setup for the full walkthrough and CI/CD patterns.

Next steps

Go one level deeper based on what you are building:

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