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 exports (load calculation, basis of design, ventilation/hourly-loads CSV) as jobs
• Upload floor-plan PDFs through REST or an SDK, poll their sheet-upload jobs, place pages, and run project-wide auto-takeoff
• 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

The Developer Tab

Everything you need to connect to HVAKR lives on Settings → Developer:

• Docs & SDKs — buttons to the API Docs, the TypeScript SDK, and the Python SDK
• Access Tokens — create and delete the tokens that authenticate API and MCP requests
• MCP Server — the https://mcp.hvakr.com/mcp URL to paste into an AI assistant, with a Copy button
• Webhooks — HTTPS endpoints HVAKR POSTs signed events to (organization admins only; see Webhooks)

API Access

To use the API:

1. Log in to your HVAKR account
2. Go to Settings → Developer
3. Click Create Access Token
4. Enter a name for the token, then click Create Access Token in the dialog
5. Copy and save the token from the Save Your Token dialog — you won’t be able to view it again
6. Use the token in API requests

Tokens never expire — delete a token to revoke it.

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.

Webhooks

Webhooks push events from HVAKR to your own HTTPS endpoint so you don’t have to poll. They belong to your organization, and only organization admins can add, edit, or delete them — other members see Only organization admins can manage webhooks.

Add a Webhook

1. Go to Settings → Developer and scroll to Webhooks
2. Click Add Webhook
3. Enter the URL — it must use https
4. Under Events, check at least one event, then click Add Webhook
5. Copy and save the secret from the Save Your Webhook Secret dialog — you won’t be able to view it again. If you lose it, delete the webhook and create a new one.

Each webhook appears in the table with its URL, Events, and an Active switch. Edit any of the three inline, or select rows to delete them. Inactive webhooks receive nothing.

Events

Event	Fires when	data payload
project.created	a project is created in your organization	{ id, name, organizationId, address?, createdAt? }
opportunity.created	an opportunity is created for your supplier organization	the opportunity record

opportunity.created is only offered to supplier organizations; everyone else sees project.created alone.

Delivery

HVAKR sends one POST per matching webhook with a JSON body:

{
    "event": "project.created",
    "timestamp": "2026-09-10T21:00:00.000Z",
    "data": { "id": "...", "name": "...", "organizationId": "..." }
}

The request carries an X-HVAKR-Event header with the event name and an X-HVAKR-Signature header of the form sha256=<hex> — the HMAC-SHA256 of the raw body, keyed with your webhook secret. Verify the signature before you trust the payload; the TypeScript SDK’s constructWebhookEvent helper does this for you (see Client SDKs).

Delivery is best-effort: HVAKR waits up to 10 seconds for a 2xx response, does not follow redirects, and does not retry a failed delivery.

Usage & Reliability

API access requires a paid plan. 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