> ## 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. # Forward POST request > 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. ## OpenAPI ````yaml /openapi.json post /forward openapi: 3.0.0 info: title: Lava API description: >- Lava API enables businesses to implement usage-based billing for AI services. This API allows tracking, managing, and billing for third-party AI API usage through a forwarding system. version: 1.0.0 contact: name: Lava support url: https://www.lava.so/contact servers: - url: https://api.lava.so/v1/ description: Lava API v1 security: [] tags: - name: Authentication - name: Core Endpoints - name: Models - name: Services - name: Requests - name: Wallet - name: Payment Methods - name: Spend Keys - name: Usage - name: Checkout Sessions - name: Customers - name: Plans - name: Subscriptions - name: Meters - name: Webhooks - name: Secret Keys - name: Credit Bundles - name: Gateway Settings - name: Skills - name: News Data - name: Search - name: Enrich paths: /forward: post: tags: - Core Endpoints summary: Forward POST request description: >- 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. parameters: - name: u in: query required: true schema: type: string example: https://api.openai.com/v1/chat/completions description: The API endpoint URL to forward the request to - name: metadata in: query required: false schema: type: string description: >- Optional metadata to associate with the request. Must be a JSON object with up to 100 key-value pairs, where both keys and values are strings between 1-255 characters. Keys must contain only ASCII letters, numbers, and underscores (no spaces or special characters). Alternative to x-lava-metadata header. example: '{"user_id": "123456", "session_id": "abc123"}' - name: x-lava-metadata in: header required: false schema: type: string description: >- Optional metadata to associate with the request. Must be a JSON object with up to 100 key-value pairs, where both keys and values are strings between 1-255 characters. Keys must contain only ASCII letters, numbers, and underscores (no spaces or special characters). Alternative to metadata query parameter. example: '{"user_id": "123456", "session_id": "abc123"}' requestBody: description: >- Request body that will be forwarded to the AI provider API. Must include the 'model' field. required: true content: application/json: schema: type: object required: - model properties: model: type: string description: The model to use for the request stream: type: boolean description: Whether to stream the response additionalProperties: true examples: chat-completion-request: summary: OpenAI chat completions example value: model: gpt-4 messages: - role: system content: >- You are a helpful customer service assistant for a tech company. - role: user content: My laptop won't turn on. What should I check first? temperature: 0.7 max_tokens: 300 anthropic-message-request: summary: Anthropic Claude messages example value: model: claude-3-opus-20240229 messages: - role: user content: Explain quantum computing to a high school student max_tokens: 1024 temperature: 0.7 system: >- You are Claude, an educational AI assistant. Give clear, accurate explanations appropriate for a high school student. google-request: summary: Google Gemini API example value: contents: - parts: - text: Explain how AI works in a few words responses: '200': description: Successful response from the provider API content: application/json: schema: type: object description: Response from the provider API additionalProperties: true examples: chat-completion-response: summary: Example /v1/chat/completions response value: id: chatcmpl-abc123 object: chat.completion created: 1677858242 model: gpt-3.5-turbo-0613 usage: prompt_tokens: 13 completion_tokens: 7 total_tokens: 20 choices: - message: role: assistant content: >- I'm doing well, thank you for asking! How can I assist you today? finish_reason: stop index: 0 anthropic-message-response: summary: Example /v1/messages response value: id: msg_012345abcdef type: message role: assistant content: - type: text text: >- I'm doing well, thank you for asking! I'm Claude, an AI assistant made by Anthropic. How can I help you today? model: claude-3-opus-20240229 stop_reason: end_turn stop_sequence: null usage: input_tokens: 25 output_tokens: 32 google-response: summary: Example Google Gemini API response value: candidates: - content: parts: - text: >- I'm doing well, thank you for asking! How can I assist you today? role: model finishReason: STOP avgLogprobs: -0.5139622211456298 usageMetadata: promptTokenCount: 6 candidatesTokenCount: 80 totalTokenCount: 86 promptTokensDetails: - modality: TEXT tokenCount: 6 candidatesTokensDetails: - modality: TEXT tokenCount: 80 modelVersion: gemini-2.0-flash '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' examples: forward_url_missing: summary: URL parameter is missing value: error: message: >- URL parameter is missing. Please include the target URL using the ?u= query parameter. code: forward_url_missing status: 400 forward_endpoint_not_supported: summary: Endpoint not supported value: error: message: >- This endpoint is not supported. Please refer to our documentation for a list of available endpoints. code: forward_endpoint_not_supported status: 400 forward_model_invalid: summary: Invalid model specified value: error: message: >- The specified model is invalid. Please check your request body and refer to our documentation for supported models. code: forward_model_invalid status: 400 forward_model_not_supported: summary: Model not supported value: error: message: >- The specified model is not supported. Please refer to our documentation for a list of supported models. code: forward_model_not_supported status: 400 forward_body_json_invalid: summary: Invalid JSON in request body value: error: message: >- Request body contains invalid JSON. Please check your request body syntax and ensure it's properly formatted. code: forward_body_json_invalid status: 400 forward_metadata_json_invalid: summary: Invalid JSON in metadata header value: error: message: >- Metadata header contains invalid JSON. Please check your metadata format. code: forward_metadata_json_invalid status: 400 forward_metadata_schema_invalid: summary: Invalid metadata schema value: error: message: >- Metadata header does not match the required schema. Please check your metadata structure. code: forward_metadata_schema_invalid status: 400 '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: forward_token_missing: summary: Forward token missing value: error: message: >- Forward token is missing. Please provide your token using one of these methods: 'Authorization: Bearer ' header, 'x-api-key: ' header, 'key' query parameter, or 'x-goog-api-key: ' header. code: forward_token_missing status: 401 '402': description: Payment required content: application/json: schema: $ref: '#/components/schemas/Error' examples: forward_token_customer_limit_reached: summary: Customer usage limit reached value: error: message: >- Your customer has reached its usage limit. Please top up your credit balance to continue using this service. code: forward_token_customer_limit_reached status: 402 '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' examples: forward_request_failed: summary: Request forwarding failed value: error: message: >- Failed to forward your request to the target service. This may be due to network issues or the target service being unavailable. code: forward_request_failed status: 500 security: - ForwardAuth: [] - ForwardAuthAnthropic: [] - ForwardAuthGoogle: [] - ForwardAuthGoogleQueryParam: [] components: schemas: Error: type: object properties: error: type: object properties: message: type: string description: Human-readable error message describing what went wrong example: Invalid authentication credentials code: type: string description: Machine-readable error code describing what went wrong example: forward_token_json_invalid status: type: integer description: HTTP status code of the error example: 400 issues: type: array items: type: object properties: path: type: array items: type: string description: Path to the field that caused the validation error message: type: string description: Error message describing the validation issue required: - path - message description: >- Optional array of specific validation issues with their paths and messages example: - path: - model message: 'Missing required field: model' - path: - messages - '0' - content message: Invalid message content format required: - message - code - status required: - error securitySchemes: ForwardAuth: type: http scheme: bearer description: >- Special authentication used for the forward endpoint. Requires a base64-encoded JSON object containing secret_key, customer_id, and meter_slug. Optionally include provider_key to use your own API key for the request. When using your own API key, you can make requests that use metering only by setting both customer_id and meter_slug to null. Format: 'Bearer BASE64_ENCODED_JSON' ForwardAuthAnthropic: type: apiKey in: header name: x-api-key description: >- You can pass an x-api-key header to authenticate with the forward endpoint for compatibility with anthropic style clients. Requires a base64-encoded JSON object containing secret_key, customer_id, and meter_slug. Optionally include provider_key to use your own API key for the request. When using your own API key, you can make requests that use metering only by setting both customer_id and meter_slug to null. ForwardAuthGoogle: type: apiKey in: header name: x-goog-api-key description: >- You can pass an x-goog-api-key header to authenticate with the forward endpoint for compatibility with Google style clients. Requires a base64-encoded JSON object containing secret_key, customer_id, and meter_slug. Optionally include provider_key to use your own API key for the request. When using your own API key, you can make requests that use metering only by setting both customer_id and meter_slug to null. ForwardAuthGoogleQueryParam: type: apiKey in: query name: key description: >- You can pass a key query parameter to authenticate with the forward endpoint for compatibility with Google style clients. Requires a base64-encoded JSON object containing secret_key, customer_id, and meter_slug. Optionally include provider_key to use your own API key for the request. When using your own API key, you can make requests that use metering only by setting both customer_id and meter_slug to null. ````