# Lava Documentation

- [What Is Lava Desktop](https://lava.so/docs/desktop/overview.md): Lava Desktop puts your work apps as live tabs in one window alongside an agent that reads them, acts across them, and charges work against your balance.
- [Install Lava Desktop](https://lava.so/docs/desktop/install.md): Download and install Lava Desktop on macOS or Windows, and verify the app launches to the sign-in screen.
- [Quickstart: Your First Agent Task](https://lava.so/docs/desktop/quickstart.md): Sign in, connect an app, and ask the Lava desktop agent to do something real, in under 5 minutes.
- [Connecting Your Apps](https://lava.so/docs/desktop/connect-apps.md): Connect providers as live app tabs and authorize the connectors the agent acts through in Lava Desktop.
- [Add Funds to Your Balance](https://lava.so/docs/desktop/funds.md): Put money into your balance and understand what costs money when the agent works.
- [Working with the Agent](https://lava.so/docs/desktop/working-with-agent.md): Give the Lava desktop agent tasks, follow its work across your connected apps, and review and approve what it does.
- [Importing Workflows](https://lava.so/docs/desktop/import-workflows.md): Bring the skills and instructions you already use in Claude, ChatGPT, Claude Code, and other AI tools into Lava as Workflows.
- [How Lava Desktop Works](https://lava.so/docs/desktop/how-it-works.md): A mental model of how the Lava desktop agent gets work done across your apps, why it pauses before high-stakes actions, and what draws down your balance, so you can predict and trust its behavior.
- [Using Lava Safely](https://lava.so/docs/desktop/using-lava-safely.md): Set honest expectations and good habits so you trust Lava appropriately: neither over-trusting it nor under-using it.
- [Interactive Apps and Agent Connectors](https://lava.so/docs/desktop/connectable-apps.md): A reference to the providers Lava Desktop connects to: which open as Interactive Apps in your sidebar, which the agent calls as Agent Connectors, and which are Included with no setup.
- [Troubleshooting Lava Desktop](https://lava.so/docs/desktop/troubleshooting.md): Fix common problems with installing, signing in, connecting apps, running the agent, adding funds, and updating Lava Desktop.
- [Quickstart: Add Lava to Your AI Chat](https://lava.so/docs/mcp/quickstart.md): Install the Lava MCP in your AI chat, connect a service, and make your first call in under 5 minutes.
- [How to Install the Lava MCP](https://lava.so/docs/mcp/install.md): Install the Lava MCP on claude.ai, Claude Desktop, or Claude Code — for a personal account or a Team or Enterprise workspace.
- [How to Connect Services through Lava MCP](https://lava.so/docs/mcp/connect-services.md): Add, verify, and remove service connections — Gmail, Slack, Notion, web search, and more — using the dashboard or the Lava MCP itself.
- [How to Fund Your Lava Account](https://lava.so/docs/mcp/funds.md): Add funds, check your balance, review usage, and recover from insufficient-balance errors — from the dashboard or your AI chat.
- [Lava MCP Tool Reference](https://lava.so/docs/mcp/tool-reference.md): Every tool the Lava MCP exposes — parameters, returns, and a canonical example for each.
- [Welcome to Lava](https://lava.so/docs/introduction.md)
- [Quickstart: Make Your First Request](https://lava.so/docs/get-started/quickstart-track.md): Make your first Lava AI gateway request in under 5 minutes
- [Quickstart: Charge Your First Customer](https://lava.so/docs/get-started/quickstart-charge.md): Set up pricing and checkout to charge customers for AI usage
- [How Lava Gateway Works](https://lava.so/docs/gateway/how-lava-gateway-works.md)
- [Forward Proxy & Authentication](https://lava.so/docs/gateway/forward-proxy.md): Route AI requests through Lava's proxy with secret key or forward token authentication
- [Rewrite Endpoint (Cross-Format Proxy)](https://lava.so/docs/gateway/rewrite-proxy.md): Use one SDK format against any provider: OpenAI SDK → Claude, Anthropic SDK → GPT, Bedrock, Google, and more
- [Supported Providers](https://lava.so/docs/gateway/supported-providers.md): Provider-level catalog generated from Lava's shared services source of truth
- [AI Spend Keys](https://lava.so/docs/guides/ai-spend-keys.md): Use Lava as a drop-in API key for AI tools and agents with built-in budget controls
- [Tool Setup Guides](https://lava.so/docs/guides/spend-key-setup-guides.md): Connect Lava spend keys to Cursor, Claude Code, Raycast, Vercel AI SDK, and more
- [How Lava Monetize Works](https://lava.so/docs/monetize/how-lava-monetize-works.md): Understand Lava's usage-based billing system: plans, meters, checkout, and customers
- [Plans](https://lava.so/docs/monetize/plans.md): Configure recurring billing with included credits, rollovers, linked meters, and credit bundles
- [Meters](https://lava.so/docs/monetize/meters.md): Configure pricing rules for your AI services using meters: fixed credits per usage unit, percentage markups on provider cost, and tiered rates
- [Checkout](https://lava.so/docs/monetize/checkout.md): Embed Lava's checkout flow for subscriptions and credit bundle purchases
- [Gateway vs Post-Request Reporting](https://lava.so/docs/monetize/gateway-vs-post-request.md): Understand the tradeoffs between routing AI calls through Lava's gateway and reporting usage after the fact for monetization
- [Meter-Only Mode & Disable Billing](https://lava.so/docs/monetize/meter-only-mode.md): Track API usage without billing customers using meter-only mode or the disable_billing flag
- [Webhooks](https://lava.so/docs/integration/webhooks.md): Receive real-time notifications when customers are created, updated, or deleted
- [Multi-Provider Routing](https://lava.so/docs/integration/multi-provider.md): Abstract provider logic, implement fallback strategies, and route requests across AI providers
- [Node.js SDK](https://lava.so/docs/sdk/nodejs.md): Official Node.js SDK for integrating Lava's monetization and AI proxy APIs
- [Checkout SDK](https://lava.so/docs/sdk/checkout.md): React SDK for embedding Lava's hosted checkout flow in your application
- [Show Credit Balance](https://lava.so/docs/cookbook/show-balance.md): Display a customer's credit balance, subscription details, and low-balance warnings in your UI
- [Request History](https://lava.so/docs/cookbook/request-history.md): Display a paginated log of AI requests with costs, models, and metadata for end users
- [Usage Analytics](https://lava.so/docs/cookbook/usage-analytics.md): Build dashboards, billing reports, and cost breakdowns from aggregated usage data
- [A/B Test Pricing](https://lava.so/docs/cookbook/ab-test-pricing.md): Run pricing experiments by routing different user cohorts to different meters
- [Build vs Buy](https://lava.so/docs/guides/integration-comparison.md): What it takes to build AI monetization yourself — and what Lava handles for you
- [Authenticate an Agent](https://lava.so/docs/agents/authenticate.md): Choose the right auth flow for MCP-hosted agents versus SDK code
- [Route Traffic Through the Gateway](https://lava.so/docs/agents/route-traffic.md): Forward AI requests through Lava to track usage and costs across providers
- [Bill Your Customers](https://lava.so/docs/agents/bill-customers.md): Set up usage-based billing with meters, plans, and checkout from code
- [Manage AI Spend & API Keys](https://lava.so/docs/agents/manage-spend.md): Create scoped API keys with spend limits for agents and developer tools
- [Supported Providers](https://lava.so/docs/agents/supported-providers.md): Provider-level catalog generated from Lava's shared services source of truth
- [API Reference](https://lava.so/docs/api-reference/introduction.md): Complete guide to the Lava REST API for usage-based billing and AI proxy services
- [Exchange CLI auth code](https://lava.so/docs/api-reference/authentication/exchange-cli-auth-code.md): Exchange a one-time authorization code for wallet and secret key credentials. The code is generated when a user authorizes CLI access through the browser. Codes expire after 60 seconds and can only be used once.
- [Forward GET request](https://lava.so/docs/api-reference/core-endpoints/forward-get-request.md): Forward a GET request to a third-party API (like OpenAI, Anthropic, etc.) with usage tracking and billing.
- [Forward POST request](https://lava.so/docs/api-reference/core-endpoints/forward-post-request.md): Forward a POST request to a third-party API (like OpenAI, Anthropic, etc.) with usage tracking and billing. This is the core functionality of Lava that allows forwarding requests to AI services.
- [List models](https://lava.so/docs/api-reference/models/list-models.md): Returns a list of available AI models in OpenAI-compatible format. When authenticated with a spend key, results are filtered by the key's allowed models and providers. No authentication is required, but authenticated requests may return filtered results.
- [List services](https://lava.so/docs/api-reference/services/list-services.md): Returns a list of all models and API services available through the Lava gateway, including provider API reference URLs, pricing, capabilities, and managed/BYOK status. This endpoint is public and does not require authentication.
- [Search providers](https://lava.so/docs/api-reference/services/search-providers.md): Searches the gateway provider catalog by keyword and returns ranked provider summaries, most relevant first. This endpoint is public and does not require authentication.
- [Get provider details](https://lava.so/docs/api-reference/services/get-provider-details.md): Returns the provider summary for a specific gateway provider, including the official upstream API reference URL. This endpoint is public and does not require authentication.
- [List requests](https://lava.so/docs/api-reference/requests/list-requests.md): Get a paginated list of AI API requests with optional filtering by customer or meter
- [Create request](https://lava.so/docs/api-reference/requests/create-request.md): Create a new API request with usage tracking and billing. This endpoint allows you to manually create requests that were made outside of the forward endpoint.
- [Get request](https://lava.so/docs/api-reference/requests/get-request.md): Get details of a specific API request
- [Get usage statistics](https://lava.so/docs/api-reference/usage/get-usage-statistics.md): Get daily aggregated usage statistics for a specific time period with optional filtering by customer or meter. Helps analyze AI usage patterns and costs.
- [Create checkout session](https://lava.so/docs/api-reference/checkout-sessions/create-checkout-session.md): Create a new checkout session. Supports two modes: subscription (start a recurring plan) and credit_bundle (one-time credit pack purchase). Pass the returned checkout_session_token to the @lavapayments/checkout SDK to open the checkout flow.
- [List customers](https://lava.so/docs/api-reference/customers/list-customers.md): List all customers for the authenticated merchant with pagination support and optional filtering
- [Create customer](https://lava.so/docs/api-reference/customers/create-customer.md): Create a customer record with merchant-scoped contact info. The customer can be assigned free plans and use the proxy immediately. To link a payment method, direct them through checkout. Idempotent when reference_id is provided (strongly recommended) — returns the existing customer if one matches.
- [Get customer subscription](https://lava.so/docs/api-reference/customers/get-customer-subscription.md): Returns the active subscription for a customer, including plan details, current cycle credits, and any pending changes (cancellation or downgrade). Use this to show subscription status and remaining credits.
- [Get customer](https://lava.so/docs/api-reference/customers/get-customer.md): Get a customer by ID
- [Delete customer](https://lava.so/docs/api-reference/customers/delete-customer.md): Delete a customer by ID
- [Update customer](https://lava.so/docs/api-reference/customers/update-customer.md): Update a customer by ID. Only provided fields are updated (partial update). Accepts either a Lava customer_id (con_xxx) or your reference_id.
- [List plans](https://lava.so/docs/api-reference/plans/list-plans.md): List all plans for the authenticated merchant. Plans define pricing that can be assigned to customers.
- [Create plan](https://lava.so/docs/api-reference/plans/create-plan.md): Create a new plan with optional meter links and credit bundles. A Stripe Price is automatically created for non-zero period amounts.
- [Get plan](https://lava.so/docs/api-reference/plans/get-plan.md): Get a specific plan by ID, including linked meters and credit bundles
- [Delete plan](https://lava.so/docs/api-reference/plans/delete-plan.md): Soft-delete a plan and cascade to its credit bundles.
- [Update plan](https://lava.so/docs/api-reference/plans/update-plan.md): Update a plan. Fields period_amount and billing_interval are immutable. Credit bundles use reconciliation: include credit_bundle_id to update, add is_deleted: true to remove, omit credit_bundle_id to create new.
- [List subscriptions](https://lava.so/docs/api-reference/subscriptions/list-subscriptions.md): List all subscriptions for the authenticated merchant. Filter by status (active, cancelled, or all) and customer_id.
- [Create subscription](https://lava.so/docs/api-reference/subscriptions/create-subscription.md): Assign a free plan to a customer. The customer can be created via POST /v1/customers or through checkout. Only free plans can be assigned via this endpoint — use checkout for paid plans.
- [Cancel subscription](https://lava.so/docs/api-reference/subscriptions/cancel-subscription.md): Schedule a subscription for cancellation at the end of the current billing cycle. The subscription remains active until the cycle ends.
- [Update subscription](https://lava.so/docs/api-reference/subscriptions/update-subscription.md): Update a subscription. Currently supports changing the auto top-up credit bundle.
- [List meters](https://lava.so/docs/api-reference/meters/list-meters.md): List all meters for the authenticated merchant. Meters define fee models for API request billing.
- [Create meter](https://lava.so/docs/api-reference/meters/create-meter.md): Create a new meter for the authenticated merchant. Meters define fee models for API request billing.
- [Get meter](https://lava.so/docs/api-reference/meters/get-meter.md): Get a specific meter by ID
- [Delete meter](https://lava.so/docs/api-reference/meters/delete-meter.md): Soft-delete a meter. A 15-second cooldown applies after creation before deletion is allowed.
- [Update meter](https://lava.so/docs/api-reference/meters/update-meter.md): Update a meter. Only name and tiers can be modified. Fields like rate_type, tier_type, and meter_slug are immutable.
- [List webhooks](https://lava.so/docs/api-reference/webhooks/list-webhooks.md): List all webhooks for the authenticated merchant.
- [Create webhook](https://lava.so/docs/api-reference/webhooks/create-webhook.md): Create a new webhook. The webhook_secret is returned only once in the creation response. Maximum 3 webhooks per merchant.
- [Get webhook](https://lava.so/docs/api-reference/webhooks/get-webhook.md): Get a specific webhook by ID
- [Delete webhook](https://lava.so/docs/api-reference/webhooks/delete-webhook.md): Permanently delete a webhook.
- [Update webhook](https://lava.so/docs/api-reference/webhooks/update-webhook.md): Update a webhook name or URL.
- [List secret keys](https://lava.so/docs/api-reference/secret-keys/list-secret-keys.md): List all active secret keys for the authenticated merchant. Keys are returned with a hint (last 4 characters) — full key values are never returned after creation.
- [Create secret key](https://lava.so/docs/api-reference/secret-keys/create-secret-key.md): Self-service creation of developer Secret Keys is temporarily paused for all accounts. Authenticated creation requests return 403 with code secret_key_issuance_paused. Existing keys continue to work. When issuance resumes, the full secret_key is returned only in the creation response, with a maximum…
- [Revoke secret key](https://lava.so/docs/api-reference/secret-keys/revoke-secret-key.md): Revoke (soft-delete) a secret key. Cannot delete the last remaining key. A 15-second cooldown applies after creation.
- [List credit bundles](https://lava.so/docs/api-reference/credit-bundles/list-credit-bundles.md): List all credit bundles for the authenticated merchant. Optionally filter by plan_id.
- [Get credit bundle](https://lava.so/docs/api-reference/credit-bundles/get-credit-bundle.md): Get a specific credit bundle by ID
- [Get wallet](https://lava.so/docs/api-reference/wallet/get-wallet.md): Get the wallet and current balance for the authenticated account. Requires a merchant secret key (aks_live_* / aks_test_*).
- [Add funds to wallet](https://lava.so/docs/api-reference/wallet/add-funds-to-wallet.md): Add funds to the authenticated wallet by charging a saved payment method. If the payment completes immediately, the new balance is returned. If 3D Secure verification is required, a redirect URL is returned for the user to complete in a browser. Requires a merchant secret key (aks_live_* / aks_test_…
- [List payment methods](https://lava.so/docs/api-reference/payment-methods/list-payment-methods.md): List all saved payment methods for the authenticated wallet. Returns card details and default status. Requires a merchant secret key (aks_live_* / aks_test_*).
- [List spend keys](https://lava.so/docs/api-reference/spend-keys/list-spend-keys.md): List spend keys for the authenticated wallet. Requires a merchant secret key (aks_live_* / aks_test_*).
- [Create spend key](https://lava.so/docs/api-reference/spend-keys/create-spend-key.md): Create a new spend key for the authenticated wallet. Spend key issuance is enabled on request: until then, requests return 403 with code spend_key_issuance_paused (email support@lava.so). When enabled, the raw key is returned once in the response — store it securely. Requires a merchant secret key (…
- [Get spend key](https://lava.so/docs/api-reference/spend-keys/get-spend-key.md): Get details of a specific spend key including current-cycle and total tracked usage. Requires a merchant secret key (aks_live_* / aks_test_*).
- [Update spend key](https://lava.so/docs/api-reference/spend-keys/update-spend-key.md): Update settings for a spend key. Requires a merchant secret key (aks_live_* / aks_test_*).
- [Revoke spend key](https://lava.so/docs/api-reference/spend-keys/revoke-spend-key.md): Soft-delete a spend key. The key will immediately stop working for proxy requests. Requires a merchant secret key (aks_live_* / aks_test_*).
- [Rotate spend key](https://lava.so/docs/api-reference/spend-keys/rotate-spend-key.md): Rotate the raw secret for an existing spend key while preserving key settings and usage. Rotation is enabled on request: until then, requests return 403 with code spend_key_issuance_paused (email support@lava.so). When enabled, the new raw key is returned once in the response. Requires a merchant se…
- [Get global fallback chain](https://lava.so/docs/api-reference/gateway-settings/get-global-fallback-chain.md): Get the account-level fallback chain applied to all rewrite requests when no per-request x-lava-fallbacks header is provided.
- [Set global fallback chain](https://lava.so/docs/api-reference/gateway-settings/set-global-fallback-chain.md): Set or clear the account-level fallback chain. When set, this chain is used as the default fallback for all rewrite requests that do not include an x-lava-fallbacks header. Pass null to clear the setting. Maximum 5 entries.
- [Upload a skill](https://lava.so/docs/api-reference/skills/upload-a-skill.md): Upload a skill as a set of files. Each file must be a supported type (md, txt, py, ts, js, json, yaml, yml, sh, toml, xml). Individual files are limited to 50KB and the total upload to 500KB. At most 20 files per upload.
- [List news articles](https://lava.so/docs/api-reference/news-data/list-news-articles.md): Returns paginated news articles with optional filtering by publication, tag, date range, and keyword search.
- [List news publications](https://lava.so/docs/api-reference/news-data/list-news-publications.md): Returns a list of available news publications with article counts and crawl metadata.
- [Aggregated search across all 9 providers](https://lava.so/docs/api-reference/search/aggregated-search-across-all-9-providers.md): Fan out a single query across 9 search providers in parallel — Tavily, Exa, Jina, Parallel, Perplexity Sonar, Firecrawl, Lava News, Serper, Brave Search — and return a unified normalized result set with explicit per-provider failure surfacing. Charges sum of upstream provider costs plus a $0.005 lav…
- [Synthesized answer with citations from the 9-provider fan-out](https://lava.so/docs/api-reference/search/synthesized-answer-with-citations-from-the-9-provider-fan-out.md): Same fan-out as /search/sources, plus an LLM synthesis pass that produces a cited answer. Returns `{ answer, citations, cost }` — the underlying sources are not echoed back; call /search/sources separately if you need the raw evidence pile. When the synthesis model fails (timeout, malformed structur…
- [Merged contact info for a person](https://lava.so/docs/api-reference/enrich/merged-contact-info-for-a-person.md): Narrow contact-info merger across Apollo, People Data Labs, and (when opted in) the caller's connected CRMs (HubSpot/Folk/Affinity). Accepts any subset of person-side identifiers (email, linkedin_url, name+company, phone, twitter_url, github_url, instagram_handle) and returns a merged `contact` with…
- [Comprehensive profile dossier for a person](https://lava.so/docs/api-reference/enrich/comprehensive-profile-dossier-for-a-person.md): Comprehensive person dossier. Runs /enrich/contact's adapter set plus Wikipedia and Apify social adapters (Twitter, GitHub, Instagram — conditional on the matching handle in the input), in parallel with a direct Lava News fetch for recent business happenings (last 90 days). xAI Grok synthesizes stru…

## OpenAPI Specs

- [openapi](/docs/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.