API Reference

The Levered API gives you full programmatic control over optimizations, models, warehouse connections, and metrics. Every operation available in the dashboard is also available through the API, making it suitable for automation, CI/CD pipelines, and AI agent workflows.

Base URL

https://api.levered.dev

All endpoint paths in this reference are relative to the base URL. For example, GET /api/v2/optimizations means GET https://api.levered.dev/api/v2/optimizations.

Authentication

Protected endpoints require a Clerk OAuth bearer token in the Authorization header:

curl https://api.levered.dev/api/v2/optimizations \
  -H "Authorization: Bearer <token>"

Tokens are issued by Clerk and scoped to your organization. If the token is missing or invalid, the API returns 401 Unauthorized.

Public endpoints

The following endpoints do not require authentication:

• POST /api/v2/optimizations/:id/serve -- Serve the best variant for a user
• POST /api/v2/optimizations/best-variant -- SDK-facing variant endpoint

These are designed for client-side and edge usage where embedding a secret is not appropriate.

Rate limiting

When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header.

Response format

All responses include a meta object with a unique request ID and the resolved organization:

{
  "...": "...",
  "meta": {
    "request_id": "req_abc123",
    "organization_id": "org_xyz"
  }
}

Response fields are at the top level alongside meta — there is no data wrapper.

Error format

Errors use standard HTTP status codes with a JSON body:

{
  "error": {
    "code": "not_found",
    "message": "Optimization not found"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

MCP Integration

Levered exposes an MCP (Model Context Protocol) endpoint at /mcp for direct integration with AI agents. Agents that support MCP can manage optimizations, query results, and serve variants through MCP tools without constructing HTTP requests manually.

This means tools like Claude Code, Cursor, and other MCP-compatible agents can interact with Levered natively -- creating optimizations, checking model state, and pulling results as part of an agentic workflow.

To connect, point your MCP client at:

https://api.levered.dev/mcp

The MCP endpoint uses the same Clerk authentication as the REST API.

Endpoints

• Optimizations -- Create, update, serve variants, and view results
• Models -- Train models and inspect model state
• Warehouse -- Manage data warehouse connections and tables
• Metrics -- Define reward and assignment metrics