API

The same calculations, from your own program.

Everything the panel does goes through this API: projects, items, revisions, comparisons and — the part that matters — the selection itself. You send duty and geometry, you get pressure drop, attenuation and noise, computed by the same code and the same version that produced the report your client is holding.

Keys are part of the Enterprise plan. There are two ways into this API and only one of them is sold: the panel talks to it with your session cookie on every plan — that is simply how our own site connects to us. A key is different: through it your program reaches the calculation itself, and that is what Enterprise pays for. The plan is checked both when a key is issued and on every request it makes. This page stays public on purpose — you should know what you are buying before you pay for it.

Authentication

Two ways in, and they exist side by side.

Who	How	Notes
Your program	`Authorization: Bearer cap_<prefix>_<secret>`	Keys are shown once, at creation. We store only a hash — a lost key is revoked, not recovered.
The panel	Session cookie, `httpOnly`, `SameSite=Lax`	Browser only. Writes from another origin are refused.

Every request is answered as { "data": … } or { "error": { "code", "message" } }. Nothing else. Lists add meta with total, limit and offset.

Everything in SI

The API speaks SI and nothing else: m, m³/s, Pa, W, kg, kg/m³, m/s, °C. Millimetres, CFM and inches belong to the screen, not to the wire — the panel converts them for the person looking, and what travels and what is stored stays in base units.

This is why an item computed in Chicago and opened in Kraków shows the same number, and why a result from last year can still be compared with one from today. GET /v1/units returns the whole dictionary: families, their SI base and every unit with its factor.

One account, one filter

A key belongs to a company account, and every row it can reach carries that account. Asking for someone else's project answers exactly like asking for one that does not exist — 404 — so response codes cannot be used to find out what your competitor has.

Resources

Generated from the API itself, so it cannot drift from what the server really does.

`/v1/account`

Dane firmy, logo do raportów i jednostki, w których konto pracuje.

Route	What it does	Who may call it
`GET /v1/account`	read one	signed in
`PATCH /v1/account`	change	signed in, role owner or higher
`GET/POST/DELETE /v1/account/logo`	logo	signed in
`GET/PUT /v1/account/units`	units	signed in
`POST /v1/account/vat`	vat	signed in, role owner or higher

`/v1/api-keys`

Klucze API: wydanie, warunki, unieważnienie.

Route	What it does	Who may call it
`GET /v1/api-keys`	list	signed in, role owner or higher
`GET /v1/api-keys/{id}`	read one	signed in, role owner or higher
`POST /v1/api-keys`	create	signed in, role owner or higher
`PATCH /v1/api-keys/{id}`	change	signed in, role owner or higher
`DELETE /v1/api-keys/{id}`	delete	signed in, role owner or higher
`GET /v1/api-keys/usage`	usage	signed in, role owner or higher

`/v1/auth`

Zakładanie konta, logowanie, wylogowanie, kim jestem.

Route	What it does	Who may call it
`POST /v1/auth/signup`	signup	anyone
`POST /v1/auth/login`	login	anyone
`POST /v1/auth/logout`	logout	anyone
`GET /v1/auth/me`	me	signed in
`POST /v1/auth/password`	password	signed in
`PATCH /v1/auth/profile`	profile	signed in
`GET/POST/DELETE /v1/auth/avatar`	avatar	signed in
`POST /v1/auth/email`	email	anyone
`POST /v1/auth/forgot`	forgot	anyone
`POST /v1/auth/reset`	reset	anyone
`GET/DELETE /v1/auth/sessions`	sessions	signed in

`/v1/billing`

Dane do faktury, płatność, faktury z numerem KSeF.

Route	What it does	Who may call it
`GET /v1/billing`	read one	signed in, role owner or higher
`PATCH /v1/billing`	change	signed in, role owner or higher
`POST /v1/billing/checkout`	checkout	signed in, role owner or higher
`POST /v1/billing/portal`	portal	signed in, role owner or higher
`GET /v1/billing/invoices`	invoices	signed in, role owner or higher
`POST /v1/billing/vat`	vat	signed in, role owner or higher

`/v1/brands`

Marki konta: logo i stopka, którymi podpisuje się dokument.

Route	What it does	Who may call it
`GET /v1/brands`	list	signed in
`GET /v1/brands/{id}`	read one	signed in
`POST /v1/brands`	create	signed in, role owner or higher
`PATCH /v1/brands/{id}`	change	signed in, role owner or higher
`DELETE /v1/brands/{id}`	delete	signed in, role owner or higher
`GET/POST/DELETE /v1/brands/{id}/logo`	logo	signed in

`/v1/calc`

Rachunek po stronie serwera: dobór z wymiarów i dobór z wymagań.

Route	What it does	Who may call it
`POST /v1/calc/{id}/optimize`	optimize	signed in

`/v1/comparisons`

Zestawienia pozycji: wejścia i wyniki obok siebie.

Route	What it does	Who may call it
`GET /v1/comparisons`	list	signed in
`GET /v1/comparisons/{id}`	read one	signed in
`POST /v1/comparisons`	create	signed in, role editor or higher
`PATCH /v1/comparisons/{id}`	change	signed in, role editor or higher
`DELETE /v1/comparisons/{id}`	delete	signed in, role editor or higher
`PUT /v1/comparisons/{id}/items`	items	signed in, role editor or higher

`/v1/hooks`

Sygnały od operatora płatności.

Route	What it does	Who may call it
`POST /v1/hooks/stripe`	stripe	anyone

`/v1/items`

Pozycje projektu: wejścia, wynik i historia wersji.

Route	What it does	Who may call it
`GET /v1/items`	list	signed in
`GET /v1/items/{id}`	read one	signed in
`POST /v1/items`	create	signed in, role editor or higher
`PATCH /v1/items/{id}`	change	signed in, role editor or higher
`DELETE /v1/items/{id}`	delete	signed in, role editor or higher
`GET /v1/items/{id}/revisions`	revisions	signed in
`POST /v1/items/{id}/restore`	restore	signed in, role editor or higher

`/v1/languages`

Języki: panel, raporty, format liczb i teksty raportu.

Route	What it does	Who may call it
`GET /v1/languages`	list	anyone
`GET /v1/languages/texts`	texts	anyone

`/v1/plans`

Plany: model rozliczenia, ceny i limity.

Route	What it does	Who may call it
`GET /v1/plans`	list	anyone

`/v1/products`

Własny katalog konta: serie wyrobów i ich warianty, zakładane z zapisanych doborów.

Route	What it does	Who may call it
`GET /v1/products`	list	signed in
`GET /v1/products/{id}`	read one	signed in
`POST /v1/products`	create	signed in, role editor or higher
`PATCH /v1/products/{id}`	change	signed in, role editor or higher
`DELETE /v1/products/{id}`	delete	signed in, role owner or higher
`GET/DELETE /v1/products/assets`	assets	signed in
`POST/PATCH/PUT/DELETE /v1/products/{id}/variants`	variants	signed in, role editor or higher
`POST /v1/products/{id}/publish`	publish	signed in, role owner or higher
`POST /v1/products/{id}/withdraw`	withdraw	signed in, role owner or higher
`POST /v1/products/{id}/picture`	picture	signed in, role editor or higher

`/v1/projects`

Projekty: teczki z pozycjami liczonymi narzędziami Pro.

Route	What it does	Who may call it
`GET /v1/projects`	list	signed in
`GET /v1/projects/{id}`	read one	signed in
`POST /v1/projects`	create	signed in, role editor or higher
`PATCH /v1/projects/{id}`	change	signed in, role editor or higher
`DELETE /v1/projects/{id}`	delete	signed in, role editor or higher
`POST /v1/projects/{id}/restore`	restore	signed in, role editor or higher
`DELETE /v1/projects/{id}/purge`	purge	signed in, role owner or higher
`POST /v1/projects/{id}/duplicate`	duplicate	signed in, role editor or higher

`/v1/spectra`

Zapisane widma oktawowe: szablony konta do wstawiania w pozycje.

Route	What it does	Who may call it
`GET /v1/spectra`	list	signed in
`GET /v1/spectra/{id}`	read one	signed in
`POST /v1/spectra`	create	signed in, role editor or higher
`PATCH /v1/spectra/{id}`	change	signed in, role editor or higher
`DELETE /v1/spectra/{id}`	delete	signed in, role editor or higher

`/v1/tools`

Narzędzia dostępne w Pro, z wersją rachunku i wymaganym planem.

Route	What it does	Who may call it
`GET /v1/tools`	list	anyone
`GET /v1/tools/{id}`	read one	anyone

`/v1/units`

Rodziny wielkości, jednostki i przeliczniki do jednostek bazowych.

Route	What it does	Who may call it
`GET /v1/units`	list	anyone

`/v1/users`

Użytkownicy konta: role, zaproszenia, własne jednostki.

Route	What it does	Who may call it
`GET /v1/users`	list	signed in
`GET /v1/users/{id}`	read one	signed in
`POST /v1/users`	create	signed in, role owner or higher
`PATCH /v1/users/{id}`	change	signed in, role editor or higher
`DELETE /v1/users/{id}`	delete	signed in, role owner or higher
`POST /v1/users/{id}/invite`	invite	signed in, role owner or higher

Errors

The code is for your program, the message is for the person reading the log.

HTTP	Code	What it means
400	`BAD_JSON`, `BAD_SIGNATURE`	The request body or signature could not be read.
401	`NOT_LOGGED`, `BAD_LOGIN`	No valid session or key.
402	`PLAN_LIMIT`	Not a missing right — a missing plan. The body says which limit and how far you are.
403	`NO_RIGHT`, `ACCOUNT_BLOCKED`, `BAD_ORIGIN`	The caller exists but may not do this.
404	`NOT_FOUND`, `NO_RESOURCE`	Also answers for rows belonging to another account.
405	`BAD_METHOD`	Right address, wrong verb.
409	`EMAIL_TAKEN`, `LAST_OWNER`	The state of the account forbids it.
422	`FIELD_REQUIRED`, `FIELD_BAD`	The body names the field and the reason.
429	`TOO_MANY`	Too many attempts from one address.
502/503	`PAYMENT_FAILED`, `BILLING_OFF`	A service we depend on refused or is not configured.

Versions

The address carries the version: /v1/…. Within a version we add fields and resources, and we do not remove or rename them. A result always travels with the core_version that produced it, so an item computed last year can be told apart from the same item computed today.

Want the keys? API access comes with Enterprise — write to pro@cloudair.tech and we will set it up, together with the contract and the onboarding.