API Overview

HVAKR provides API access for integrating with other tools and automating workflows.

API Capabilities

What You Can Do

The HVAKR API allows you to:

• Create, read, update, and delete projects (and their spaces, zones, systems, and types)
• Run the calculator: loads, register schedules, the dryside duct graph, ventilation (ASHRAE 62.1), equipment, checksums, and airflows
• Generate reports (load calculation, basis of design, ventilation/hourly-loads CSV) as jobs
• Automate design steps: auto-group spaces/zones, run project checks, and auto-takeoff
• Browse the product catalog (your organization’s products plus public ones)
• Paginate large project lists and retry writes safely with idempotency keys

Use Cases

Common integrations:

• Import building data from BIM tools
• Export results to spreadsheets
• Integrate with project management
• Automate batch processing

Getting Started

API Access

To use the API:

1. Log in to your HVAKR account
2. Go to Settings → Developer
3. Click Create Access Token
4. Copy and save the token — you won’t be able to view it again
5. Use the token in API requests

API Documentation

Full API reference available at:

• https://api.hvakr.com/v0/docs/ — interactive Swagger UI
• https://api.hvakr.com/v0/docs/openapi.json — raw OpenAPI 3 document
• https://api.hvakr.com/llms.txt — compact endpoint inventory for AI agents

Authentication

Access Tokens

API requests use token authentication:

Authorization: Bearer YOUR_TOKEN

Token Security

Keep tokens secure:

• Don’t share tokens
• Rotate tokens periodically
• Use environment variables

Client SDKs

We provide official client libraries to make integration easier.

Learn more about Client SDKs

TypeScript/JavaScript

npm install @hvakr/client

Python

pip install hvakr

MCP Server

Connect Claude, Notion, and other AI assistants to your HVAKR projects through our MCP Server. The assistant signs in with a HVAKR access token and can list projects, read project data, run calculations, and create, update, or delete projects on your behalf.

Usage & Reliability

API access requires a paid plan — Pay-Per-Project does not include it (403). Requests are rate limited per token by plan (Enterprise 1200/min, all other paid plans 120/min) — responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset, and a 429 includes Retry-After. Call GET /v0/me to see your plan and limit. Build clients defensively:

• Retry transient 5xx and 429 responses with exponential backoff (honoring Retry-After)
• Send an Idempotency-Key header on POSTs so a retried write can’t run twice
• Correlate issues with the X-Request-Id response header (also echoed as requestId in error bodies)
• Cache results locally and only fetch what you need — prefer expand=false or a specific subcollection list
• Contact support@hvakr.com about high-volume or batch workloads

Best Practices

Error Handling

Every error returns a standard envelope:

{
    "error": { "code": "not_found", "message": "Project not found" },
    "requestId": "..."
}

error.code is a stable value (invalid_request, validation_failed, unauthenticated, permission_denied, not_found, method_not_allowed, conflict, rate_limited, internal). For validation_failed, error.details holds the validation issues. Branch on error.code rather than the message text.

Efficiency

Optimize API usage:

• Batch requests when possible
• Cache results locally
• Only fetch what you need

Support

Getting Help

For API support:

• Check the API documentation
• Review error messages
• Contact support@hvakr.com