Skip to main content

​
Development Guide

This guide covers best practices and important considerations when developing with the Vaani Backend API.

​
Authentication

All API requests require authentication via the X-API-Key header. Include this header in every request: 
const headers = {
  'X-API-Key': 'your-api-key-here',
  'Content-Type': 'application/json'
};
Never expose your API key in client-side code, version control, or public repositories. Use environment variables or secure secret management systems.

​
Base URL

The base URL for all API requests is: 
https://api.vaaniresearch.com

​
Error Handling

The API uses standard HTTP status codes:
  • 200 - Success
  • 422 - Validation Error (request format issues)
When a validation error occurs, the response will include details about what went wrong:
{
  "detail": [
    {
      "loc": ["body", "contact_number"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

​
Request Format

All request bodies should be sent as JSON with the Content-Type: application/json header: 
const response = await fetch('https://api.vaaniresearch.com/api/trigger-call/', {
  method: 'POST',
  headers: {
    'X-API-Key': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agent_name: 'sales-agent',
    contact_number: '+919876543210',
    name: 'John Doe'
  })
});

​
Response Format

All successful responses return JSON data. The structure varies by endpoint - refer to the API Reference for specific response schemas.

​
Rate Limits

Please refer to your API key documentation for specific rate limit information. Implement appropriate retry logic and exponential backoff for handling rate limit errors.

​
Best Practices

Store your API key in environment variables:
# .env file
VANI_API_KEY=your-api-key-here

// JavaScript
const apiKey = process.env.VANI_API_KEY;

# Python
import os
api_key = os.getenv('VANI_API_KEY')
Always implement proper error handling:
try {
  const response = await fetch(url, options);
  if (!response.ok) {
    const error = await response.json();
    console.error('API Error:', error);
    // Handle error appropriately
  }
  const data = await response.json();
  return data;
} catch (error) {
  console.error('Network Error:', error);
  // Handle network error
}

​
Testing

Use the API reference documentation to test endpoints. All endpoints include example requests that you can use with tools like:
  • cURL
  • Postman
  • HTTPie
  • Your programming language’s HTTP client