Skip to main content

​
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.lavapayments.com/v1/

​
Authentication

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

​
Getting Your API Key

Manage Secret Keys

Create and manage your API secret keys in the Secrets page. New keys are auto-generated and shown only once—copy them immediately.
Keep your secret keys secure and never expose them in client-side code or public repositories.

​
Forward Endpoint Authentication

The /forward endpoint uses a special authentication format to support AI proxy requests: 
{
  "secret_key": "YOUR_SECRET_KEY",
  "connection_secret": "CONNECTION_SECRET",
  "product_secret": "PRODUCT_SECRET"  // optional
}
This JSON object must be base64-encoded and sent as a Bearer token: 
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

{
  "data": {
    // Response data here
  }
}

​
Error Response

{
  "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: 
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: 
{
  "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: 
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: 
?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: 
x-lava-metadata: {"user_id":"123","session_id":"abc"}

​
SDK Libraries

We provide official SDKs for popular languages:

Node.js

npm install @lavapayments/nodejs

React Checkout

npm install @lavapayments/checkout

​
Status Codes

The API uses standard HTTP status codes:
CodeMeaning
200Success
201Created successfully
204Success with no content
400Bad request (invalid parameters)
401Unauthorized (invalid API key)
402Payment required (insufficient wallet balance)
404Resource not found
429Too many requests (rate limited)
500Internal server error

​
Need Help?

​
Next Steps

Forward Endpoint

Proxy AI requests with automatic metering and billing

Requests API

Track and analyze API usage across connections

Checkout Sessions

Create wallet onboarding flows for your users

Subscriptions

Configure recurring subscription plans