Lev API Documentation

Overview

The Lev External API v2 is a RESTful API that exposes the core Lev platform capabilities to external consumers. It uses JSON request and response bodies, standard HTTP methods, and Bearer token authentication.

The API serves two complementary use cases:

• Direct REST integration — build custom workflows, sync data with other systems, or automate deal management
• MCP (Model Context Protocol) server — power AI-assisted CRE workflows through Claude Desktop, Cursor, and other MCP-compatible clients

Both paths use the same endpoints, the same authentication, and the same authorization policies.

Machine-readable Docs

Use these surfaces when you want an agent, a code generator, or your own tooling to consume the docs directly:

• /docs/llms.txt — compact index of the docs corpus, plus agent instructions, machine-readable resource links, and a per-section endpoint reference parsed from this site.
• /docs/llms-full.txt — every doc page concatenated as cleaned markdown in a single bundle, suitable for a one-shot context drop into an LLM.
• /docs/openapi.json — OpenAPI 3.1 specification reconstructed from the documented endpoints. Use this to drive code generation or to populate an API client like Postman.
• /<page>.md — per-page markdown output with JSX components translated or stripped. For example, /build/deals.md returns clean markdown for the Deals reference page.

Core Integration Patterns

These patterns appear throughout the API and are worth understanding before you implement against a single resource:

• Authentication — every request uses Authorization: Bearer <token> and X-Origin-App.
• Stable reads — list endpoints use a shared pagination pattern designed for predictable reads and syncs.
• Structured envelopes — responses include request_id, timestamp, and data.
• Bounded writes — write endpoints may support Idempotency-Key and should be handled with explicit retries.
• Narrow payloads — use fields, include, filtering, and sorting to keep responses intentional.

API Surface

All API requests use the same base URL:

https://api.levcapital.com/api/external/v2

The v2 API is organized into these domains:

Response Format

All successful responses use a consistent envelope:

Single object

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2026-03-20T15:30:45Z",
  "data": {
    "id": 123,
    "title": "Example Deal"
  }
}

List with pagination

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "timestamp": "2026-03-20T15:30:45Z",
  "data": [
    { "id": 1, "title": "Deal A" },
    { "id": 2, "title": "Deal B" }
  ],
  "pagination": {
    "total": 142,
    "limit": 50,
    "cursor": "eyJpZCI6IDJ9",
    "has_more": true,
    "next_cursor": "eyJpZCI6IDUyfQ=="
  }
}

Every response includes a request_id (UUID v4) for support correlation and a timestamp (ISO 8601) indicating when the response was generated.

Health Check

curl https://api.levcapital.com/api/external/v2/health

{
  "request_id": "...",
  "timestamp": "2026-03-20T15:30:45Z",
  "data": {
    "status": "ok",
    "version": "2.0.0",
    "timestamp": "2026-03-20T15:30:45Z"
  }
}

This is distinct from the MCP server's own /health endpoint, which reports MCP-specific state (backend reachability, circuit-breaker state). See MCP Errors & Limits for that surface.