CloudAir Selection API

Getting started

1. Get a key from the company whose catalogue you integrate. Keys are issued in their CloudAir administration — with an end date and a scope: the categories, series and products you may read.
2. Send it in the X-Api-Key header with every request.
3. Start with GET /v1 — it tells you whose catalogue the key opens, until when, and what part of it you see.

curl -H "X-Api-Key: YOUR_API_KEY" https://selection-api.cloudair.tech/v1

Authentication

Every request carries the key in one header:

X-Api-Key: ca_api_3f9a…c21d

• Two kinds of keys. A server key is a secret, called from your backend (Node, PHP, Python, C#…) and refused from web pages. A browser key lists the websites it works on and is called by JavaScript in those pages — see Calling from a browser. One key is one kind; for both, ask for two keys.
• Shown once. The catalogue owner sees the key only when issuing it. A lost key is replaced with a new one; the old one stops working at once.
• Validity. Every key has an end date. Extending it keeps the same key.
• Addresses. A key may be limited to your server's IP addresses, and single addresses may be blocked. Such a key answers IP_NOT_ALLOWED in the Try it panels here, because they call from our server.
• Daily limit. A key may have a daily number of calls; it resets at midnight.

Calling from a browser

A browser key lets JavaScript in a web page ask the API directly — a product finder on a distributor's site, a configurator page. The catalogue owner lists the websites it works on, e.g. www.example.com or *.example.com (the domain and all its subdomains).

const res = await fetch("https://selection-api.cloudair.tech/v1/series?lang=en", {
    headers: { "X-Api-Key": "ca_api_…" }   // a browser key — it is visible in the page, by design
});
const body = await res.json();
if (!res.ok) console.warn(body.error.code, body.error.message);

• The browser sends the page's Origin by itself; the API answers only listed websites and lets only them read the response (CORS).
• A browser key does not work from a server (WEBSITE_REQUIRED) and a server key does not work from a page (BROWSER_NOT_ALLOWED).
• Anyone can read a key in a web page. What protects it is the website list together with a low daily limit and a narrow scope — the same model as map keys on millions of sites.
• The Try it panels here call from our server, so a browser key answers WEBSITE_REQUIRED in them. Try it in your page instead.

Responses and errors

Every answer is JSON in UTF-8 with a real HTTP status. Success has data and usually meta:

{
  "data": [ … ],
  "meta": { "count": 20, "limit": 20, "offset": 0, "language": "en" }
}

Addresses are absolute. Every image and file — image, image_url, images[].url, files[].url — is a full https:// link you can download or show as it is.

A refusal has a stable code for your program and a message for people; some add fields:

{
  "error": { "code": "KEY_EXPIRED", "message": "This key expired on 2027-10-24.", "fields": { "valid_to": "2027-10-24" } }
}

Language

Names and descriptions come in the language you ask for with ?lang= — en, pl, de, fr and the other catalogue languages. Where a text is missing in that language you get the English one, never an empty field by accident.

• Without ?lang= answers are in English — or in the first language of a key limited to other languages.
• A key limited to some languages answers LANGUAGE_NOT_INCLUDED for the rest, so a missing translation never looks like a missing text.
• meta.language says which language you got. Language codes are the CloudAir ones: cz, dk, ua, gr, jp, cn, zn.
• The language picker at the top applies to every Try it panel on this page.

Paging

Lists take limit (1–1000, default 100) and offset. Ask for the next page while meta.count equals limit. For everything at once there is Whole catalogue.

What a key sees

The catalogue owner decides what each key may read: the whole catalogue, or chosen categories, series and single products, up to an access level and in chosen languages. Chosen categories narrow the series; chosen series and single products add up.

Anything outside the scope simply does not exist for the key — it answers 404, not 403. Prices and internal notes are never part of the API.

Dictionaries

Series and products carry keys, not texts. Two dictionaries turn them into something a person can read — fetch them once, in the language you show, and keep them:

"variables": { "powerRated": "90", "voltageRated": "230" }   →   /v1/variables
"tags": [ "Centrifugal", "Phase-1" ]                         →   /v1/tags

• The whole dictionary as a filterable table: Variables.
• Variables — powerRated is “Rated power”, symbol P, unit W, rounded to the given step. Values come as the catalogue stores them, sometimes as text: read them as numbers.
• Tags — Phase-1 is “Single-phase” in group “power supply”. Groups are what you build filters from; filter lists with ?tag=.
• Both take ?used=1 to return only what appears in the part of the catalogue your key sees.
• Filter on any variable in Products: ?v.phase=1, ?v.motorSupplyType=EC,DEC, ?min.powerRated=500&max.powerRated=2000. Keys are the ones from Variables; text compares without case, numbers as numbers.