Bluon API Documentation

This documentation covers the primary use cases for the Bluon API v1.1, focusing on model search, model details retrieval, parts listing (BOM), replacement parts lookup, nameplate reading, and HVAC tools.

API Details

Base URL (UAT): https://test.hub.bluontoolbox.com/uat

Authentication: Bearer Token (required for all endpoints)

Version: v1.1

Core Endpoints

The following are the most important endpoints for common use cases. Additional endpoints are available for niche requirements but are rarely used in practice. For a complete index of all available endpoints, refer to our Swagger documentation.

Model Search

Search equipment by model number

Model Details

Get comprehensive model information

Parts List (BOM)

Get list of original parts

Replacement Parts

List compatible replacements

Parts Search

Universal parts search functionality

Manuals

Get all manuals for a model

Distributor Inventory

Check distributor stock

Nameplate Reader

Extract data from nameplate images

Age & Warranty

Determine equipment age and warranty status

HVAC Tools

Field diagnostic and calculation tools

Authentication

Bluon will provide you with access tokens (UAT and Production) and your partner_slug.

Base URL Path

{{url}}/{{environment}}/gateway/{{partner}}/...

Example

https://test.hub.bluontoolbox.com/uat/gateway/your_partner_slug/...

Headers

In calls to the endpoints, different headers must be added. Some are optional, while others are required for proper functionality.

Required Headers

The token generated during authentication must be included in all subsequent requests involving private endpoint routes.

{
  "headers": {
    "Authorization": "Bearer eyJ0eXAiOi1QiLCJh...DVnDGd6J_ig"
  }
}

Optional Headers

Additional information about the company and the user can be optionally provided and will be used for classifying the usage of the services.

{
  "headers": {
    "x-api-company-id": "66542211154",
    "x-api-user-id": "5444554",
    "x-api-company-email": "example@example.com",
    "x-api-company-name": "Example Company",
    "x-api-company-zip-code": "90210",
    "x-api-phone": "15633211145"
  }
}

x-api-company-id

Unique identifier for the company making the request

x-api-user-id

Unique identifier for the user initiating the action

x-api-company-email

Primary email address associated with the company

x-api-company-name

Legal or commercial name of the company

x-api-company-zip-code

ZIP code corresponding to the company's location

x-api-phone

Company's contact phone number (international format recommended)

Error Handling

The API returns standard HTTP status codes.

200Success

400Bad Request - Invalid input data

401Unauthorized - Invalid or missing token

404Not Found - Resource doesn't exist

Swagger

Check out our Swagger for all API endpoints with interactive request/response examples, detailed parameter information, and live testing capabilities!

Open Swagger →