Belova Platform API

Introduction

Welcome to the Belova Platform API documentation. This API allows developers to programmatically interact with the Belova system, enabling seamless integration with your existing tools and workflows.

You can use the API to access and manage data related to inventory, pricing, auctions, and customer relationships.

Current API Version: v1

Base URL: https://api.belovatech.com/v1

Protocol: HTTPS

Authentication

All API requests must be authenticated using an API Key.

Obtaining an API Key

API Keys can be generated and managed within your Belova Client Hub account under the 'API' section.

Authenticating Requests

Include your API key in the header of all requests:

Authorization: Bearer YOUR_API_KEY_HERE

Example Request Header

GET /vehicles HTTP/1.1
Host: api.belovatech.com
Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc

Errors

The Belova API uses standard HTTP status codes to indicate the success or failure of a request.

Error responses will include a JSON object with details:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid API Key provided.",
    "param": "authorization"
  }
}

Rate Limits

To ensure fair usage and stability, the API enforces rate limits.

• Default Limit: 1000 requests per hour per API key.
• Limit Header: The X-RateLimit-Limit header indicates the total number of requests allowed per hour.
• Remaining Header: The X-RateLimit-Remaining header shows the number of requests remaining in the current window.
• Reset Header: The X-RateLimit-Reset header indicates the time at which the current rate limit window resets (Unix timestamp).

If you exceed the rate limit, you will receive a 429 Too Many Requests error response. Please wait until the reset time before making further requests.

Endpoints

Detailed documentation for each API endpoint.

curl https://api.belovatech.com/v1/vehicles?limit=5&status=available \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"

{
  "vehicles": [
    {
      "id": "veh_1J9FZ2H3K4L5M6N7O8P9",
      "vin": "1HGCM826XA00123456",
      "make": "Honda",
      "model": "Accord",
      "year": 2023,
      "mileage": 15000,
      "color": "White",
      "status": "available",
      "acquisition_date": "2024-01-15",
      "predicted_turn_days": 45,
      "current_market_value": 24500.00,
      "location": "Warehouse A"
    },
    // ... more vehicles
  ],
  "total_count": 125,
  "has_more": true
}

curl https://api.belovatech.com/v1/pricing/recommend \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"vehicle_id": "veh_1J9FZ2H3K4L5M6N7O8P9"}'

{
  "vehicle_id": "veh_1J9FZ2H3K4L5M6N7O8P9",
  "recommended_price": 25200.00,
  "market_comparison": {
    "average_competitor_price": 24850.00,
    "percentile_25": 23500.00,
    "percentile_75": 26200.00
  },
  "confidence_score": 0.92, // 92% confidence in the recommendation
  "last_updated": "2025-07-31T10:30:00Z"
}

Client Libraries

We provide official libraries for popular programming languages to simplify API integration:

• Python: pip install belova-python | GitHub | Docs
• JavaScript (Node.js): npm install @belova/node | GitHub | Docs
• Java: Maven Central | GitHub | Docs
• .NET (C#): NuGet | GitHub | Docs

These libraries handle authentication, request signing, and response parsing for you.

Changelog

Keep track of changes and updates to the API.

• 2025-07-15: Added `/auctions/bid` endpoint. Improved error handling for `/vehicles` endpoint.
• 2025-05-20: Introduced API versioning. Base URL changed to `https://api.belovatech.com/v1`. Added `/crm/leads/search` endpoint.
• 2025-03-10: Initial release of v1 API with core Inventory, Pricing, and basic CRM endpoints.