> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.coperniq.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.coperniq.io/_mcp/server. # List Catalog Items GET https://api.coperniq.io/v1/catalog-items Lists catalog items (products and services). Reference: https://docs.coperniq.io/api-reference/catalog-items/list-catalog-items ## Authentication - `x-api-key` header (required) — API Key authentication via header ## Response ### 200 List of catalog items - `list of CatalogItem` ## Errors ### 401 Unauthorized Error Authentication failed - `message` (string, optional) - `code` (enum, optional) - Allowed values: `GRAPHQL_ERROR` ### 502 Bad Gateway Error Bad Gateway — downstream GraphQL service returned errors - `message` (string, required) — Summary of the downstream service failure - `code` (enum, required) - Allowed values: `GRAPHQL_ERROR` ## Types ### CatalogItem - `id` (integer, required) — Catalog item identifier - `name` (string, required) — Catalog item name - `catalog` (enum, required, nullable) — High-level trade group for this item. - Allowed values: `ENERGY`, `MECHANICAL`, `ELECTRICAL`, `PLUMBING`, `LOW_VOLTAGE`, `ENVELOPE`, `OTHER` - `type` (enum, required) — Catalog item type - Allowed values: `PRODUCT`, `SERVICE` - `category` (CatalogCategoryCode, required) — Catalog item category code (ProductCategory or ServiceCategory) - `cost` (double, required, nullable) — Catalog item cost - `price` (double, required, nullable) — Catalog item price - `manufacturer` (string, optional, nullable) — Catalog item manufacturer - `sku` (string, optional, nullable) — Catalog item SKU - `code` (string, optional, nullable) — Catalog item code - `description` (string, optional, nullable) — Catalog item description - `image` (CatalogItemImage, optional, nullable) - `isArchived` (boolean, optional, nullable) — Whether the catalog item is archived - `createdById` (integer, optional) — Identifier of the user who created the catalog item - `createdAt` (string, optional, nullable) - `updatedAt` (string, optional, nullable) - `preferredVendorId` (integer, optional, nullable) — ID of the preferred vendor (must be an existing active vendor for this company) - `unit` (CatalogUnit, optional, nullable) — The unit this item is sold/measured in, if any. Set on write via `unitId`. - `measurements` (list of Measurement, optional) — Measurements (and sub-measurements) linked to this item to drive its quantity calculation. A sub-measurement is a linked Measurement with `type SUB_CALCULATION`; at most one may be linked, and it must be the only link when present. - `coverage` (double, optional, nullable) — Measurement units covered per item unit (e.g. a bundle covering ~33.33 SF). Used to size quantity from summed linked measurements; not used when the item is linked to a sub-calculation, which derives quantity from its own formula. - `wasteFactorMode` (enum, optional, nullable) — Waste factor mode applied when computing this item's quantity. Currently only STATIC is supported. Paired with wasteFactorValue — both are set, or neither. - Allowed values: `STATIC` - `wasteFactorValue` (double, optional, nullable) — Waste factor percentage (0-100) applied when computing this item's quantity. Paired with wasteFactorMode. ### CatalogCategoryCode Catalog item category code. Must be: - one of `ProductCategory` when `type` is `PRODUCT`, or - one of `ServiceCategory` when `type` is `SERVICE`. - ProductCategory: enum - Allowed values: `BATTERY_SYSTEM`, `BATTERY_MANAGEMENT_SYSTEM`, `CHARGING_GATEWAY`, `COMBINER_BOX`, `EV_CHARGER`, `LOAD_CENTER`, `MICROINVERTER`, `MOUNTING`, `POWER_OPTIMIZER`, `PRODUCTION_METER`, `PV_INVERTER`, `PV_MODULE`, `RACKING`, `RAPID_SHUTDOWN_DEVICE`, `TRACKER`, `WEATHER_STATION`, `AIR_CONDITIONER`, `AIR_HANDLING_UNIT`, `BOILER`, `CHILLER`, `COOLING_TOWER`, `FAN`, `HEAT_EXCHANGER`, `HEAT_PUMP`, `MAKE_UP_AIR_UNIT`, `PUMP`, `ROOFTOP_UNIT`, `THERMOSTAT`, `VARIABLE_FREQUENCY_DRIVE`, `AUTOMATIC_TRANSFER_SWITCH`, `BREAKER`, `DISCONNECT_SWITCH`, `ELECTRIC_METER`, `GENERATOR`, `LIGHTING_PANEL`, `PANELBOARD`, `SWITCHGEAR`, `TRANSFORMER`, `UNINTERRUPTIBLE_POWER_SUPPLY`, `WIRE`, `BACKFLOW_PREVENTER`, `BOOSTER_PUMP`, `GREASE_INTERCEPTOR`, `STORAGE_TANK`, `SUMP_PUMP`, `VALVE`, `WATER_FILTRATION_SYSTEM`, `WATER_HEATER`, `WATER_SOFTENER`, `ACCESS_CONTROLLER`, `AUTOMATION_CONTROLLER`, `CAMERA`, `CARD_READER`, `DOOR_STRIKE`, `MAGLOCK`, `NETWORK_SWITCH`, `NETWORK_VIDEO_RECORDER`, `SENSOR`, `WIRELESS_ACCESS_POINT`, `ROOF_COVERING`, `ROOF_UNDERLAYMENT`, `ROOF_MEMBRANE`, `ROOF_FLASHING`, `ROOF_VENT`, `WALL_CLADDING`, `WALL_TRIM`, `WEATHER_BARRIER`, `WINDOW`, `EXTERIOR_DOOR`, `SKYLIGHT`, `OPENING_FLASHING`, `GUTTER`, `DOWNSPOUT`, `INSULATION`, `SEALANT`, `SHEATHING`, `OTHER` - ServiceCategory: enum - Allowed values: `ADJUSTMENT`, `BALANCING`, `CALIBRATION`, `CLEANING`, `COMMISSIONING`, `DECOMMISSIONING`, `DIAGNOSTICS`, `ENGINEERING`, `EQUIPMENT_RENTAL`, `INSPECTION`, `INSTALLATION`, `MAINTENANCE`, `MONITORING`, `OPTIMIZATION`, `PERMITTING`, `RELOCATION`, `REMOVAL`, `REPAIR`, `REPLACEMENT`, `RETROFIT`, `SITE_SURVEY`, `TESTING`, `TRAINING`, `OTHER` ### CatalogItemImage - `id` (integer, optional) - `name` (string, optional) - `url` (string, optional) — URL to download the image ### CatalogUnit A unit of measure from the company's unit registry (e.g. Each, Square Feet, Linear Feet). Referenced by catalog items and measurements via `unitId`. - `id` (integer, required) — Catalog unit identifier - `code` (string, required) — Stable short code for the unit (e.g. "SF", "EA") - `label` (string, required) — Human-readable label for the unit (e.g. "Square Feet") - `dimension` (enum, optional, nullable) — The physical dimension this unit measures, if any. Null for packaging-style units (e.g. bundle, roll) that can't be used on a measurement. - Allowed values: `LENGTH`, `AREA`, `COUNT` - `isCustom` (boolean, optional) — Whether this unit was defined by the company, as opposed to one of the seeded defaults. - `isArchived` (boolean, optional) — Whether this unit has been archived. ### Measurement A named measurement or sub-calculation that a catalog item can link to (via `measurementIds`) to drive its quantity. A "sub-measurement" is simply a Measurement with `type: SUB_CALCULATION` — not a separate structure. - `id` (integer, required) — Measurement identifier - `name` (string, required) — Measurement name - `type` (enum, required) — A plain MEASUREMENT is a raw input value; a SUB_CALCULATION ("sub-measurement") derives its value from a formula over other measurements. - Allowed values: `MEASUREMENT`, `SUB_CALCULATION` - `unit` (CatalogUnit, optional, nullable) — The unit this measurement is expressed in, if any. - `minimumValue` (double, optional, nullable) — Minimum allowed value. Only meaningful for type MEASUREMENT. - `formula` (MeasurementFormula, optional) — The formula driving a SUB\_CALCULATION measurement's quantity. Read-only — there is no API to create or edit a measurement's formula; it can only be authored in the app. Shape: `operands` names each referenced measurement (`{name, measurementId}`); `ast` is a binary-operation tree (`ADD`/`SUB`/`MUL`/`DIV`) whose leaves are either `{operandRef}` (referencing an entry in `operands` by name) or `{constant}` (a literal number); `sourceText` is the original formula text as authored. - `isArchived` (boolean, optional) — Whether this measurement has been archived. ### MeasurementFormula The formula driving a SUB\_CALCULATION measurement's quantity. Read-only — there is no API to create or edit a measurement's formula; it can only be authored in the app. Shape: `operands` names each referenced measurement (`{name, measurementId}`); `ast` is a binary-operation tree (`ADD`/`SUB`/`MUL`/`DIV`) whose leaves are either `{operandRef}` (referencing an entry in `operands` by name) or `{constant}` (a literal number); `sourceText` is the original formula text as authored. - `operands` (list of MeasurementFormulaOperandsItems, optional) - `ast` (MeasurementFormulaAst, optional) — Binary-operation AST node or leaf. See the formula description above. - `sourceText` (string, optional) — The formula as originally authored (e.g. "( m1 + m2 ) / 100") ### MeasurementFormulaOperandsItems - `name` (string, optional) - `measurementId` (integer, optional) ### MeasurementFormulaAst Binary-operation AST node or leaf. See the formula description above. ## Examples **Response** ```json [ { "id": 1, "name": "string", "catalog": "ENERGY", "type": "PRODUCT", "category": "BATTERY_SYSTEM", "cost": 1.1, "price": 1.1, "manufacturer": "string", "sku": "string", "code": "string", "description": "string", "image": { "id": 1, "name": "string", "url": "string" }, "isArchived": true, "createdById": 1, "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z", "preferredVendorId": 1, "unit": { "id": 1, "code": "string", "label": "string", "dimension": "LENGTH", "isCustom": true, "isArchived": true }, "measurements": [ { "id": 1, "name": "string", "type": "MEASUREMENT", "unit": { "id": 1, "code": "string", "label": "string", "dimension": "LENGTH", "isCustom": true, "isArchived": true }, "minimumValue": 1.1, "formula": { "operands": [ { "name": "string", "measurementId": 1 } ], "ast": {}, "sourceText": "string" }, "isArchived": true } ], "coverage": 1.1, "wasteFactorMode": "STATIC", "wasteFactorValue": 1.1 } ] ``` **SDK Code** ```python import requests url = "https://api.coperniq.io/v1/catalog-items" headers = {"x-api-key": ""} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.coperniq.io/v1/catalog-items'; const options = {method: 'GET', headers: {'x-api-key': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.coperniq.io/v1/catalog-items" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("x-api-key", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.coperniq.io/v1/catalog-items") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["x-api-key"] = '' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.coperniq.io/v1/catalog-items") .header("x-api-key", "") .asString(); ``` ```php request('GET', 'https://api.coperniq.io/v1/catalog-items', [ 'headers' => [ 'x-api-key' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.coperniq.io/v1/catalog-items"); var request = new RestRequest(Method.GET); request.AddHeader("x-api-key", ""); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["x-api-key": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.coperniq.io/v1/catalog-items")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```