# Lava Documentation

## Docs

- [Authenticate an Agent](https://lava.so/docs/agents/authenticate.md): Choose the right auth flow for MCP-hosted agents versus SDK code
- [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
- [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
- [Supported Providers](https://lava.so/docs/agents/supported-providers.md): Provider-level catalog generated from Lava's shared services source of truth
- [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.
- [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.
- [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.
- [Get credit bundle](https://lava.so/docs/api-reference/credit-bundles/get-credit-bundle.md): Get a specific credit bundle by ID
- [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.
- [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.
- [Delete customer](https://lava.so/docs/api-reference/customers/delete-customer.md): Delete a customer by ID
- [Get customer](https://lava.so/docs/api-reference/customers/get-customer.md): Get a customer by ID
- [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.
- [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
- [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.
- [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.
- [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
- [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.
- [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.
- [Get meter](https://lava.so/docs/api-reference/meters/get-meter.md): Get a specific meter by ID
- [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.
- [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 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 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.
- [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_*).
- [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.
- [Delete plan](https://lava.so/docs/api-reference/plans/delete-plan.md): Soft-delete a plan and cascade to its credit bundles.
- [Get plan](https://lava.so/docs/api-reference/plans/get-plan.md): Get a specific plan by ID, including linked meters and credit bundles
- [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.
- [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.
- [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
- [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 secret key](https://lava.so/docs/api-reference/secret-keys/create-secret-key.md): Create a new API secret key. The full secret_key value is returned only once in the creation response. Maximum 100 keys per merchant.
- [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.
- [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.
- [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 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.
- [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.
- [Create spend key](https://lava.so/docs/api-reference/spend-keys/create-spend-key.md): Create a new spend key for the authenticated wallet. The raw key is returned once in the response — store it securely. Requires a merchant secret key (aks_live_* / aks_test_*).
- [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_*).
- [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_*).
- [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. The new raw key is returned once in the response. 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_*).
- [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.
- [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.
- [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.
- [Update subscription](https://lava.so/docs/api-reference/subscriptions/update-subscription.md): Update a subscription. Currently supports changing the auto top-up credit bundle.
- [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.
- [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_…
- [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_*).
- [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.
- [Delete webhook](https://lava.so/docs/api-reference/webhooks/delete-webhook.md): Permanently delete a webhook.
- [Get webhook](https://lava.so/docs/api-reference/webhooks/get-webhook.md): Get a specific webhook by ID
- [List webhooks](https://lava.so/docs/api-reference/webhooks/list-webhooks.md): List all webhooks for the authenticated merchant.
- [Update webhook](https://lava.so/docs/api-reference/webhooks/update-webhook.md): Update a webhook name or URL.
- [A/B Test Pricing](https://lava.so/docs/cookbook/ab-test-pricing.md): Run pricing experiments by routing different user cohorts to different meters
- [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
- [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
- [Usage Analytics](https://lava.so/docs/cookbook/usage-analytics.md): Build dashboards, billing reports, and cost breakdowns from aggregated usage data
- [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
- [How Lava Gateway Works](https://lava.so/docs/gateway/how-lava-gateway-works.md)
- [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
- [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
- [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
- [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
- [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
- [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
- [Multi-Provider Routing](https://lava.so/docs/integration/multi-provider.md): Abstract provider logic, implement fallback strategies, and route requests across AI providers
- [Webhooks](https://lava.so/docs/integration/webhooks.md): Receive real-time notifications when customers are created, updated, or deleted
- [Welcome to Lava](https://lava.so/docs/introduction.md)
- [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.
- [Quickstart: Add Lava to Your AI Chat](https://lava.so/docs/mcp/quickstart.md): Install the Lava MCP in your AI chat tool, connect a service, and run your first ask in under 5 minutes.
- [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.
- [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
- [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
- [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
- [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
- [Plans](https://lava.so/docs/monetize/plans.md): Configure recurring billing with included credits, rollovers, linked meters, and credit bundles
- [Checkout SDK](https://lava.so/docs/sdk/checkout.md): React SDK for embedding Lava's hosted checkout flow in your application
- [Node.js SDK](https://lava.so/docs/sdk/nodejs.md): Official Node.js SDK for integrating Lava's monetization and AI proxy APIs

## OpenAPI Specs

- [openapi](https://lava.so/docs/openapi.json)