API Overview & Authentication

Getting started with the ExCoil REST API: authentication, rate limits, error handling, and base URL configuration.

1. Base URL

All API endpoints are served under:

https://excoil.net/api/v1/

All requests and responses use JSON format. Set the Content-Type header to application/json for POST requests.

2. Authentication

Authenticate using a Bearer token in the Authorization header:

Authorization: Bearer exk_your_api_key_here

API keys are generated from the API Keys page in your dashboard. See the API Key Management guide for details.

3. Available Endpoints

Method	Endpoint	Description
GET	/health	API health check
GET	/refrigerants	List available refrigerants
POST	/calculate/chilled-water	Chilled water coil calculation
POST	/calculate/hot-water	Hot water coil calculation
POST	/calculate/steam-coil	Steam coil calculation
POST	/calculate/dry-cooler	Dry cooler calculation
POST	/calculate/dx-evaporator	DX evaporator calculation
POST	/calculate/dx-evaporator/balanced	DX evaporator with energy balance
POST	/calculate/dx-condenser	DX condenser calculation
POST	/calculate/dx-condenser/balanced	DX condenser with energy balance

4. Response Format

Successful responses return:

{ "success": true, "data": { ... } }

Error responses return:

{ "error": "error_code", "message": "Human-readable description" }

5. HTTP Status Codes

Code	Meaning	When
200	OK	Successful calculation
400	Bad Request	Invalid input parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Key lacks required permission
422	Unprocessable	Calculation error (e.g., solver did not converge)
429	Too Many Requests	Rate limit exceeded

6. Quick Start

Example using curl:

curl -X POST https://excoil.net/api/v1/calculate/chilled-water \ -H "Authorization: Bearer exk_your_key" \ -H "Content-Type: application/json" \ -d '{ "air": { "T_db": 35, "T_wb": 24 }, ... }'

See the Calculator Endpoints guide for complete request/response examples for each calculator type.