> ## Documentation Index
> Fetch the complete documentation index at: https://lava.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete guide to the Lava REST API for usage-based billing and AI proxy services

## Welcome to the Lava API

The Lava API provides everything you need to implement usage-based billing for AI services. Our REST API follows standard HTTP conventions and returns JSON responses.

### Base URL

```
https://api.lava.so/v1/
```

## Authentication

All API endpoints (except the forward endpoint) use **Bearer token authentication** with your secret API key.

```bash theme={null}
Authorization: Bearer YOUR_SECRET_KEY
```

### Getting Your API Key

> [card] [Request API access](mailto:support@lava.so)
>
> Secret Keys are enabled on request. Email [support@lava.so](mailto:support@lava.so) to get API access
> for your account. Self-service creation is paused for all accounts, including
> through `POST /v1/secret_keys`, which returns `403 secret_key_issuance_paused`.
> Existing keys continue to work.

> [!WARNING]
>
> Keep your secret keys secure and never expose them in client-side code or public repositories.

### Spend Key Management Authentication

For `/manage/spend_keys` endpoints, authenticate with your secret key.

```bash theme={null}
Authorization: Bearer aks_live_your_secret_key
```

You can find your secret key in **Dashboard → Gateway → Secrets**.

## Forward Endpoint Authentication

The `/forward` endpoint uses a special authentication format to support AI proxy requests:

```json theme={null}
{
  "secret_key": "YOUR_SECRET_KEY",
  "customer_id": "CUSTOMER_ID",
  "meter_slug": "METER_SLUG"  // optional
}
```

This JSON object must be **base64-encoded** and sent as a Bearer token:

```bash theme={null}
Authorization: Bearer BASE64_ENCODED_JSON
```

### Alternative Authentication Headers

For compatibility with different AI providers, the forward endpoint also accepts:

* `x-api-key` (Anthropic style)
* `x-goog-api-key` (Google style)
* `key` query parameter (Google style)
* `xi-api-key` (ElevenLabs style)

## Response Format

All API responses follow a consistent JSON structure:

### Success Response

```json theme={null}
{
  "data": {
    // Response data here
  }
}
```

### Error Response

```json theme={null}
{
  "error": {
    "message": "Human-readable error description",
    "code": "error_code_identifier",
    "status": 400
  }
}
```

## Rate Limiting

API requests are rate-limited to ensure platform stability:

* Standard endpoints: 1000 requests/minute per API key
* Forward endpoint: No fixed limit (subject to wallet balance)

Rate limit information is included in response headers:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1634567890
```

## Pagination

List endpoints support cursor-based pagination:

```bash theme={null}
GET /requests?cursor=req_01234567890&limit=50
```

**Parameters:**

* `cursor`: The ID of the last item from the previous page
* `limit`: Number of items to return (max 100, default 50)

**Response:**

```json theme={null}
{
  "data": [...],
  "next_cursor": "req_98765432100"  // null if no more pages
}
```

## Idempotency

POST requests support idempotency to prevent duplicate operations. Include an `Idempotency-Key` header with a unique value:

```bash theme={null}
Idempotency-Key: unique-request-id-12345
```

Requests with the same idempotency key within 24 hours will return the same response without creating duplicate resources.

## Metadata

Many endpoints support custom metadata for tracking and filtering:

```bash theme={null}
?metadata={"user_id":"123","session_id":"abc"}
```

**Metadata rules:**

* Maximum 100 key-value pairs
* Keys and values: 1-255 characters
* Keys: ASCII letters, numbers, underscores only (no spaces/special chars)
* Values: Any string

Alternatively, use the `x-lava-metadata` header:

```bash theme={null}
x-lava-metadata: {"user_id":"123","session_id":"abc"}
```

## SDK Libraries

We provide official SDKs for popular languages:

> [card] [Node.js](https://www.npmjs.com/package/@lavapayments/nodejs)
>
> ```bash theme={null}
> npm install @lavapayments/nodejs
> ```

> [card] [React Checkout](https://www.npmjs.com/package/@lavapayments/checkout)
>
> ```bash theme={null}
> npm install @lavapayments/checkout
> ```

## Status Codes

The API uses standard HTTP status codes:

| Code | Meaning |
| - | - |
| 200 | Success |
| 201 | Created successfully |
| 204 | Success with no content |
| 400 | Bad request (invalid parameters) |
| 401 | Unauthorized (invalid API key) |
| 402 | Payment required (insufficient wallet balance) |
| 404 | Resource not found |
| 429 | Too many requests (rate limited) |
| 500 | Internal server error |

## Need Help?

* **Documentation:** [lava.so/docs](https://lava.so/docs)
* **Support:** [support@lava.so](mailto:support@lava.so)
* **Contact:** [lava.so/contact](https://lava.so/contact)

## Next Steps

> [card] [Forward Endpoint](https://lava.so/docs/api-reference/core-endpoints/forward-post-request.md)
>
> Proxy AI requests with automatic metering and billing

> [card] [Rewrite Endpoint](https://lava.so/docs/gateway/rewrite-proxy.md)
>
> Use one SDK format against any provider (OpenAI ↔ Anthropic, Bedrock, Google)

> [card] [Requests API](https://lava.so/docs/api-reference/requests/list-requests.md)
>
> Track and analyze API usage across customers

> [card] [Checkout Sessions](https://lava.so/docs/api-reference/checkout-sessions/create-checkout-session.md)
>
> Create checkout flows for subscriptions and credit bundles

> [card] [Plans](https://lava.so/docs/api-reference/plans/list-plans.md)
>
> Configure recurring plans


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