> ## 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 title="Manage Secret Keys" icon="key" href="https://lava.so/dashboard/gateway/secrets">
  Create and manage your API secret keys in the Secrets page. New keys are auto-generated and shown only once—copy them immediately.
</Card>

<Warning>
  Keep your secret keys secure and never expose them in client-side code or public repositories.
</Warning>

### 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:

<CardGroup cols={2}>
  <Card title="Node.js" icon="node-js" href="https://www.npmjs.com/package/@lavapayments/nodejs">
    ```bash theme={null}
    npm install @lavapayments/nodejs
    ```
  </Card>

  <Card title="React Checkout" icon="react" href="https://www.npmjs.com/package/@lavapayments/checkout">
    ```bash theme={null}
    npm install @lavapayments/checkout
    ```
  </Card>
</CardGroup>

## 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

<CardGroup cols={2}>
  <Card title="Forward Endpoint" icon="arrows-left-right" href="/api-reference/core-endpoints/forward-post-request">
    Proxy AI requests with automatic metering and billing
  </Card>

  <Card title="Rewrite Endpoint" icon="code-branch" href="/gateway/rewrite-proxy">
    Use one SDK format against any provider (OpenAI ↔ Anthropic, Bedrock, Google)
  </Card>

  <Card title="Requests API" icon="list" href="/api-reference/requests/list-requests">
    Track and analyze API usage across customers
  </Card>

  <Card title="Checkout Sessions" icon="credit-card" href="/api-reference/checkout-sessions/create-checkout-session">
    Create checkout flows for subscriptions and credit bundles
  </Card>

  <Card title="Plans" icon="repeat" href="/api-reference/plans/list-plans">
    Configure recurring plans
  </Card>
</CardGroup>