AssetGymBuild on the AssetGym API.
Every asset AssetGym resolves is served over a small REST surface: JSON in, JSON out, one bearer key. The spec below is generated from the running service, so it is never out of date.
The API is in beta. Endpoints, request shapes and response payloads may still change while we iterate, and short interruptions are possible, but this page tracks the service, so it always reflects what is deployed. The raw spec is available at /openapi.json.
Asset Data
/api/v1/catalog/assets/{asset_id}/co2/operationGet operational CO2
Operational (use-phase) CO2 figures for the asset: emissions per usage unit and per year, with the fuel/energy consumption figures backing them. Fields are `null` where no data exists. Figures are served from a periodically refreshed snapshot, so recent catalog edits may take up to a day to appear.
Path parameters
| Name | Type | Description |
|---|---|---|
asset_idrequired | integer | Asset id. |
Responses
Id of the asset the figures belong to.
Example: 1234
Operational CO2e emitted per usage unit (see `co2_unit`).
Example: 32.7
Unit of `co2_per_unit`.
Example: "kg/h"
Operational CO2e per year in kilograms, computed from `co2_per_unit` and the typical yearly usage.
Example: 58860
Typical yearly usage assumed for `co2_per_year`.
Example: 1800
Unit of `yearly_usage_amount`.
Example: "h/year"
Fuel or energy carrier of the asset. Multi-fuel assets list every carrier slash-joined (e.g. `petrol/electric`).
Example: "diesel"
Consumption figures backing the CO2 numbers. Empty when not available.
Fuel or energy carrier this consumption entry refers to.
Example: "diesel"
Consumption amount per `consumption_unit`.
Example: 12.4
Unit of the consumption amount.
Example: "l/h"
Provenance of this figure. `asset` is a value recorded for this exact asset and `asset_representative_descendant` comes from a representative descendant asset, while `taxonomy_*` values are calculated from the asset's classification (for example `taxonomy_specification_power_adjusted` is the taxonomy figure scaled to this asset's engine power). New values may be added over time.
Example: "asset"
Example request
curl -X GET 'https://asset-gym.com/api/v1/catalog/assets/<asset_id>/co2/operation' \
-H 'Authorization: Bearer <YOUR_API_KEY>'/api/v1/catalog/assets/{asset_id}/co2/productionGet production CO2
Production (cradle-to-gate) CO2 figures for the asset: embodied material emissions, manufacturing-energy emissions, and their total, in kg CO2e, plus the material composition the material emissions are based on. Material masses are derived from the asset's operating weight; when only shares are known, `mass_kg` is `null`. Fields are `null` where no data exists. Figures are served from a periodically refreshed snapshot, so recent catalog edits may take up to a day to appear.
Path parameters
| Name | Type | Description |
|---|---|---|
asset_idrequired | integer | Asset id. |
Responses
Id of the asset the figures belong to.
Example: 1234
Embodied emissions of the asset's materials, in kg CO2e.
Example: 78100
Manufacturing-energy emissions, in kg CO2e.
Example: 18300
Total production emissions (materials + manufacturing energy), in kg CO2e.
Example: 96400
Material breakdown of the asset, ordered by share, largest first. Empty when not available.
Material name.
Example: "steel"
Mass of this material in the asset, in kilograms. `null` when only the share is known.
Example: 15330
Fraction of the asset's total mass, between 0 and 1.
Example: 0.7
Example request
curl -X GET 'https://asset-gym.com/api/v1/catalog/assets/<asset_id>/co2/production' \
-H 'Authorization: Bearer <YOUR_API_KEY>'/api/v1/catalog/assets/{asset_id}/co2/end-of-lifeGet end-of-life CO2
Coming soonEnd-of-life CO2 figures for the asset: recycling-process emissions, the avoided-burden credit for recovered materials, and the net result, in kg CO2e, plus the material composition the recovery figures are based on. Fields are `null` where no data exists. Note: this is a preview endpoint that currently returns illustrative mock data.
Path parameters
| Name | Type | Description |
|---|---|---|
asset_idrequired | integer | Asset id. |
Responses
Id of the asset the figures belong to.
Example: 1234
Emissions caused by the recycling process itself, in kg CO2e.
Example: 4100
Avoided-burden credit for recovered materials, in kg CO2e. Positive number; subtract it from the emissions.
Example: 12600
`recycling_emissions_kgco2e` minus `recycling_credit_kgco2e`. Negative when recycling is a net benefit.
Example: -8500
Material breakdown of the asset, ordered by share, largest first. Empty when not available.
Material name.
Example: "steel"
Mass of this material in the asset, in kilograms. `null` when only the share is known.
Example: 15330
Fraction of the asset's total mass, between 0 and 1.
Example: 0.7
Example request
curl -X GET 'https://asset-gym.com/api/v1/catalog/assets/<asset_id>/co2/end-of-life' \
-H 'Authorization: Bearer <YOUR_API_KEY>'/api/v1/catalog/assets/{asset_id}/technical-specificationGet the technical specification
The asset's technical specification: operating weight, engine power, fuel type, and further typed spec fields as coverage grows. Fields are `null` where no data exists. Where a representative variant is designated for the asset, figures come from that variant's specification. Served directly from the catalog, so recent edits appear immediately.
Path parameters
| Name | Type | Description |
|---|---|---|
asset_idrequired | integer | Asset id. |
Responses
Id of the asset the specification belongs to.
Example: 1234
Operating weight in kilograms.
Example: 21900
Rated engine power in kilowatts.
Example: 122
Fuel or energy carrier of the asset. Multi-fuel assets list every carrier slash-joined (e.g. `petrol/electric`).
Example: "diesel"
Example request
curl -X GET 'https://asset-gym.com/api/v1/catalog/assets/<asset_id>/technical-specification' \
-H 'Authorization: Bearer <YOUR_API_KEY>'/api/v1/catalog/assets/{asset_id}/technical-specification-attributesList technical specification attributes
Every technical specification attribute extracted for the asset from manufacturer documentation: attributes shared across the asset's taxonomy and asset-specific ones alike. Values are normalized: each `key` is canonical with one fixed unit, so the same key is directly comparable across assets. To learn which keys are common for a taxonomy (e.g. to pick comparison columns), call `GET /catalog/taxonomies/{taxonomy_id}/technical-specification-attributes` and join on `key`. The key set is data, not schema: keys are added, merged, and retired as document coverage grows; ordering is stable per asset but unspecified, so join on `key`, not position.
Path parameters
| Name | Type | Description |
|---|---|---|
asset_idrequired | integer | Asset id. |
Query parameters
| Name | Type | Description |
|---|---|---|
offset | integer | Number of items to skip. Defaults to 0. |
limit | integer | Number of items per page. Defaults to 50, capped at 100. |
include_total | string | Opt-in to a `total` field in the response. Defaults to `false`. Case-insensitive. |
Responses
Page of the asset's technical specification attributes.
Canonical attribute key, stable across assets and shared with the taxonomy vocabulary: join asset values to taxonomy definitions on this field. For numeric attributes the normalized unit is part of the key (e.g. `dig_depth_mm`). The key set is data, not schema: keys may be added, merged, or retired as document coverage grows.
Example: "dig_depth_mm"
Canonical human-readable label of the attribute, identical for every asset.
Example: "Maximum digging depth"
Normalized value: a number for numeric attributes (in the attribute's canonical unit) or a string for textual ones, matching the `data_type` the taxonomy vocabulary declares for this `key`.
Example: 6720
Unit of the normalized value. `null` for unitless (e.g. textual) attributes. Fixed per `key`: every asset reports this attribute in the same unit.
Example: "mm"
Total count before paging. Only present when `include_total=true` was passed.
Example: 12
Example request
curl -X GET 'https://asset-gym.com/api/v1/catalog/assets/<asset_id>/technical-specification-attributes?offset=<offset>&limit=<limit>&include_total=<include_total>' \
-H 'Authorization: Bearer <YOUR_API_KEY>'/api/v1/catalog/taxonomies/{taxonomy_id}/technical-specification-attributesList taxonomy technical specification attributes
The technical-specification vocabulary of a taxonomy: every attribute key that appears on assets under this node, with its canonical label, value type, unit, and `coverage`. Coverage is how common the attribute is among the node's documented assets (those with processed manufacturer documentation). Use it to discover which attributes are common (and therefore comparable) across a taxonomy before fetching per-asset values from `GET /catalog/assets/{asset_id}/technical-specification-attributes`; the two join on `key`. Entries are ordered by descending `coverage`. Coverage is computed on read from the current catalog, so recent changes appear immediately.
Path parameters
| Name | Type | Description |
|---|---|---|
taxonomy_idrequired | integer | Taxonomy id. |
Query parameters
| Name | Type | Description |
|---|---|---|
offset | integer | Number of items to skip. Defaults to 0. |
limit | integer | Number of items per page. Defaults to 50, capped at 100. |
include_total | string | Opt-in to a `total` field in the response. Defaults to `false`. Case-insensitive. |
Responses
Page of the taxonomy's attribute vocabulary, ordered by descending `coverage`.
Canonical attribute key, stable across assets and shared with the taxonomy vocabulary: join asset values to taxonomy definitions on this field. For numeric attributes the normalized unit is part of the key (e.g. `dig_depth_mm`). The key set is data, not schema: keys may be added, merged, or retired as document coverage grows.
Example: "dig_depth_mm"
Canonical human-readable label of the attribute, identical for every asset.
Example: "Maximum digging depth"
Type of the `value` asset entries carry for this key. New types may be added over time.
Enum: "number" · "string"
Example: "number"
Unit of the normalized value. `null` for unitless (e.g. textual) attributes. Fixed per `key`: every asset reports this attribute in the same unit.
Example: "mm"
How common this attribute is in the taxonomy's documentation: the fraction of documented assets under this node (those with processed manufacturer documentation) that have a value for it, between 0 and 1. Use it to pick comparison columns (e.g. keep keys with coverage >= 0.8). Note that an asset without processed documentation returns no value even for high-coverage keys.
Example: 0.91
Total count before paging. Only present when `include_total=true` was passed.
Example: 8
Example request
curl -X GET 'https://asset-gym.com/api/v1/catalog/taxonomies/<taxonomy_id>/technical-specification-attributes?offset=<offset>&limit=<limit>&include_total=<include_total>' \
-H 'Authorization: Bearer <YOUR_API_KEY>'/api/v1/catalog/assets/{asset_id}/geo-contentGet GEO content
Coming soonEditorial content about the asset written for generative-engine and search visibility: a summary, a long-form description, highlights, and typical applications. All fields are typed; text is plain text. Note: this is a preview endpoint that currently returns illustrative mock data.
Path parameters
| Name | Type | Description |
|---|---|---|
asset_idrequired | integer | Asset id. |
Responses
Id of the asset the content belongs to.
Example: 1234
One-sentence plain-text summary of the asset.
Example: "The Caterpillar 320 GC is a 21.9-tonne crawler excavator built for lower-cost-per-hour production work."
Long-form plain-text description of the asset. Paragraphs separated by blank lines.
Example: "The Caterpillar 320 GC pairs a 122 kW engine with a reduced-power hydraulic system…"
Short bullet-style facts about the asset. Empty when not available.
Typical applications and industries the asset is used in. Empty when not available.
Example request
curl -X GET 'https://asset-gym.com/api/v1/catalog/assets/<asset_id>/geo-content' \
-H 'Authorization: Bearer <YOUR_API_KEY>'AssetVault
/api/v1/vault-filesList asset vault files
Returns up to 50 asset vault files belonging to the authenticated user.
Responses
Short UUID of the file
Example: "mMxzWbBDSfiEP6MBcfNUgP"
Original file name
Example: "report.pdf"
MIME type
Example: "application/pdf"
File size in bytes
Example: 102400
ISO 8601 timestamp of last download
Example: "2026-04-20T10:30:00.000Z"
ISO 8601 creation timestamp
Example: "2026-04-15T08:00:00.000Z"
Short-lived presigned URL to download the file. Valid until `download_url_expires_at`.
Example: "https://s3.eu-west-1.amazonaws.com/bucket/asset-vault/user-123/file-456/upload.pdf?X-Amz-Signature=..."
ISO 8601 UTC timestamp when `download_url` stops working.
Example: "2026-04-29T13:30:00.000Z"
Example request
curl -X GET 'https://asset-gym.com/api/v1/vault-files' \
-H 'Authorization: Bearer <YOUR_API_KEY>'Catalog
/api/v1/catalog/suggestSuggest catalog entries
Ranked autocomplete over the catalog (assets + taxonomies). Scope the results with `parent_id` (asset subtree), `taxonomy_id` (classification subtree), and `direct_only` (first level of the scope only; see each parameter for how they combine). Unlike the browse endpoints, scope ids are not existence-checked: an unknown id yields an empty result rather than a 404, keeping autocomplete responsive.
Request body
Free-text term that is being searched.
Example: "komatsu pc210"
Restrict results to a single domain. Omit to return both.
Enum: "taxonomy" · "asset"
Example: "asset"
Scope to the subtree below this asset. By default every descendant is searched; set `direct_only=true` to search only the direct children. Cannot be combined with `entity_type="taxonomy"` (taxonomy rows are not part of the assets tree).
Example: 1234
Classification scope. Asset and manufacturer rows match when anything in their subtree is classified at or under this taxonomy. Taxonomy rows match when they are this taxonomy or one of its descendants; or, with `direct_only=true` (and no `parent_id`), exactly its direct child taxonomies.
Example: 56
Search only the first level of the scope. With `parent_id`: the direct children of that asset. With `taxonomy_id` (and no `parent_id`): its direct child taxonomies, plus manufacturers whose subtree intersects the taxonomy. With no scope: tree roots only (industries and manufacturers). Defaults to `false` (full depth).
Example: false
Responses
Ranked list of suggestions. Capped to at most 5 entries.
Id of the underlying entity. When `entity_type` = 'asset' this is the `asset_id`; when 'taxonomy' it is the `taxonomy_id`.
Example: 1234
`taxonomy` matches any taxonomy level; `asset` matches manufacturers and individual assets.
Enum: "taxonomy" · "asset"
Example: "asset"
Friendly display string for the row. For asset (leaf) rows this is the full concatenated chain (e.g. `"Caterpillar 320 GC"`); for taxonomy and manufacturer rows it is the bare entity name (e.g. `"Excavators"`, `"Caterpillar"`).
Example: "Caterpillar 320 GC"
Chain through the assets tree ordered from the root down to the row itself: manufacturer first, the row last (e.g. `["Komatsu", "PC", "210-7"]`). Always `[]` for taxonomy rows (their chain is in `taxonomy_chain`).
Id of the node (asset_id or taxonomy_id).
Example: 100
Name of the chain node.
Example: "Caterpillar"
Chain through the taxonomy tree ordered from the root down: broadest category first, leaf last. For taxonomy rows this is the row's own chain (ending in the row itself); for asset rows it is the classification chain, populated only when the asset carries its own taxonomy.
Id of the node (asset_id or taxonomy_id).
Example: 100
Name of the chain node.
Example: "Caterpillar"
Example request
curl -X POST 'https://asset-gym.com/api/v1/catalog/suggest' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
"query": "komatsu pc210",
"entity_type": "asset",
"parent_id": 1234
}'/api/v1/catalog/taxonomiesList taxonomies
Paginated taxonomy list. If no `parent_id` is provided, returns root taxonomies. Pass `parent_id` to fetch direct children of a node.
Query parameters
| Name | Type | Description |
|---|---|---|
offset | integer | Number of items to skip. Defaults to 0. |
limit | integer | Number of items per page. Defaults to 50, capped at 100. |
include_total | string | Opt-in to a `total` field in the response. Defaults to `false`. Case-insensitive. |
parent_id | integer | List direct children of this taxonomy. |
Responses
Page of taxonomy nodes.
Id of the taxonomy node.
Example: 12
Name of the taxonomy.
Example: "Excavators"
Direct parent id, or `null` for a root taxonomy.
Example: 3
Total count after filters, before paging. Only present when `include_total=true` was passed.
Example: 14
Example request
curl -X GET 'https://asset-gym.com/api/v1/catalog/taxonomies?offset=<offset>&limit=<limit>&include_total=<include_total>&parent_id=<parent_id>' \
-H 'Authorization: Bearer <YOUR_API_KEY>'/api/v1/catalog/taxonomies/{taxonomy_id}Get a taxonomy
Fetch a single taxonomy node by id.
Path parameters
| Name | Type | Description |
|---|---|---|
taxonomy_idrequired | integer | Taxonomy id. |
Responses
Id of the taxonomy node.
Example: 12
Name of the taxonomy.
Example: "Excavators"
Direct parent id, or `null` for a root taxonomy.
Example: 3
Example request
curl -X GET 'https://asset-gym.com/api/v1/catalog/taxonomies/<taxonomy_id>' \
-H 'Authorization: Bearer <YOUR_API_KEY>'/api/v1/catalog/assetsList assets
Paginated asset list ordered by name. With no filters, returns top-level assets (manufacturers). `parent_id` and `taxonomy_id` each narrow the results (see each parameter); combining them returns the direct children of `parent_id` that also match the taxonomy filter.
Query parameters
| Name | Type | Description |
|---|---|---|
offset | integer | Number of items to skip. Defaults to 0. |
limit | integer | Number of items per page. Defaults to 50, capped at 100. |
include_total | string | Opt-in to a `total` field in the response. Defaults to `false`. Case-insensitive. |
parent_id | integer | List direct children of this asset. |
taxonomy_id | integer | Include assets whose subtree contains anything classified under this taxonomy or its descendants. |
Responses
Page of asset nodes.
Id of the asset node.
Example: 1234
Name of the asset.
Example: "210-7"
Name prefixed with all ancestor names, space-separated (e.g. `Komatsu PC 210-7`).
Example: "Komatsu PC 210-7"
Direct parent asset id, or `null` for a manufacturer.
Example: 100
Total count after filters, before paging. Only present when `include_total=true` was passed.
Example: 42
Example request
curl -X GET 'https://asset-gym.com/api/v1/catalog/assets?offset=<offset>&limit=<limit>&include_total=<include_total>&parent_id=<parent_id>&taxonomy_id=<taxonomy_id>' \
-H 'Authorization: Bearer <YOUR_API_KEY>'/api/v1/catalog/assets/{asset_id}Get an asset
Fetch a single asset node by id.
Path parameters
| Name | Type | Description |
|---|---|---|
asset_idrequired | integer | Asset id. |
Responses
Id of the asset node.
Example: 1234
Name of the asset.
Example: "210-7"
Name prefixed with all ancestor names, space-separated (e.g. `Komatsu PC 210-7`).
Example: "Komatsu PC 210-7"
Direct parent asset id, or `null` for a manufacturer.
Example: 100
Example request
curl -X GET 'https://asset-gym.com/api/v1/catalog/assets/<asset_id>' \
-H 'Authorization: Bearer <YOUR_API_KEY>'Identification
/api/v1/catalog/identifyIdentify an asset
Coming soonIdentify a catalog asset from any combination of evidence: a free-text `description` (dealer feeds, spreadsheets, invoices), a `serial_number` as stamped on the identification plate, and/or a `photo` showing the serial. Send text-only evidence as `application/json`; include a photo by sending `multipart/form-data` with the image in the `photo` field and the other inputs as text form fields. At least one input is required. The response is one fused, ranked match list: matches supported by several inputs rank first, and deterministic serial decodes rank above probabilistic description matches. When a serial was available (the `serial_number` field, or one read off the photo), `serial_decode` reports how it was decoded, in the same shape as `POST /catalog/serial-numbers/decode`: the status says how far the serial could be trusted, and the serial-based matches derive from it. When a photo was sent, `photo` echoes what was read off it: the normalized serial, its read confidence, and every recognized text region with a normalized bounding rectangle for drawing overlays. A photo with no readable serial is not an error: `photo.serial_number` is `null` and any other provided inputs still match. Pass `manufacturer_id` as a hint when the same serial format is used by several manufacturers; an id that is not a manufacturer is reported in `serial_decode` as an `error`, and the other inputs still match. Each provided input is billed additively at its own credit weight. Note: this is a preview endpoint that currently returns illustrative mock data; upload a zero-byte file to preview the unreadable-photo shape.
Request body
Free-text description of the asset as it appears in your source system: dealer feeds, spreadsheets, invoices. Abbreviations, mixed languages, and noise are expected.
Example: "komatsu pc210lc-8 escavatore cingolato 2021 usato"
Serial number as stamped on the asset's identification plate, 1–64 characters. Sent to the decoder unchanged: keep the stamped case and dashes (they are part of some formats), but strip label prefixes such as `SERIAL NO`.
Example: "KMTPC180JMKK00001"
Optional asset id of a manufacturer (a root node of the assets tree) to decode the serial against. A hint, not evidence: it narrows serial decoding and it is not billed. A manufacturer prefix in the serial itself overrides it. An id that is not a manufacturer is reported as a `manufacturer_not_found` error in `serial_decode`, not as a request failure.
Example: 1777
Responses
Potential matches across all provided inputs, ranked best first: matches supported by more inputs rank above single-input matches, and deterministic serial decodes rank above probabilistic description matches. Empty when nothing matched. Each match identifies the asset axis, the taxonomy axis, or both. Capped to at most 5 entries.
Id of the identified node in the assets tree, or `null` when the evidence did not resolve to anything on the asset axis. Can be any level of the tree: a manufacturer when only the maker was recognized, or a model when the match is precise. At least one of `asset_id` and `taxonomy_id` is set.
Example: 36988
Id of the identified taxonomy node, or `null` when the kind of machine could not be determined. At least one of `asset_id` and `taxonomy_id` is set.
Example: 1063
Friendly display string for the asset axis: the full concatenated asset chain (e.g. `"Komatsu PC 210LC-8"`, or just `"Komatsu"` for a manufacturer-level match). `null` when `asset_id` is `null`.
Example: "Komatsu PC 210LC-8"
Friendly display string for the taxonomy axis: the bare taxonomy name (e.g. `"Crawler Excavator"`). `null` when `taxonomy_id` is `null`.
Example: "76-130 KW"
Chain through the assets tree ordered from the root down: the manufacturer first, the identified node last. `[]` when `asset_id` is `null`.
Id of the node (asset_id or taxonomy_id).
Example: 100
Name of the chain node.
Example: "Caterpillar"
Chain through the taxonomy tree ordered from the root down: the broadest category first, the identified taxonomy last. `[]` when `taxonomy_id` is `null`.
Id of the node (asset_id or taxonomy_id).
Example: 100
Name of the chain node.
Example: "Caterpillar"
How the serial was decoded, in the same shape as `POST /catalog/serial-numbers/decode`. Present exactly when a serial was available: the `serial_number` field when sent, otherwise the serial read off the photo; its own `serial_number` says which. Absent when neither input carried a serial. The serial-based entries in `data` derive from it: a `decoded` result gives its asset, a manufacturer-level result (`model_not_in_catalog`, `unknown_model`, `checksum_failed`, `unrecognized_format`) gives the manufacturer, an `ambiguous_model` result gives its candidates (or what they share when the catalogue has none of them), and `ambiguous_manufacturer`, `no_match`, `unsupported_manufacturer` and `error` give nothing. A tie's readings are in its `alternatives`; send `manufacturer_id` to resolve it.
What was read off the uploaded photo. Present exactly when the request carried a `photo`; absent for JSON requests.
The serial number as read off the photo, normalized (uppercase, no spaces), or `null` when the photo contains no readable serial. Show it to the end user for confirmation; if the read is slightly wrong, correct it and re-identify with the `serial_number` field. When `null` and no other input was provided, `data` is empty; there is no error status for an unreadable serial.
Example: "KMTPC180JMKK00001"
Confidence of the photo read between 0 and 1, or `null` when no serial was read. It scores the reading of the characters, not the matches: decoding the read serial into assets is deterministic and unscored. Low values mean the serial may have been misread; confirm `serial_number` with the end user before trusting the matches.
Example: 0.97
Width in pixels of the photo as processed, after EXIF orientation was applied (the orientation a browser displays by default). Annotation coordinates are fractions of this frame; compare against your rendered image to detect an orientation mismatch.
Example: 3024
Height in pixels of the photo as processed, after EXIF orientation was applied.
Example: 4032
Every text region recognized in the photo, in reading order (top to bottom), with normalized bounding rectangles for drawing an overlay on the uploaded image: multiply `x`/`width` by the rendered width and `y`/`height` by the rendered height. Coordinates are relative to the EXIF-oriented image (origin top-left). Regions with `is_serial_number: true` are the ones the serial was read from.
Recognized text verbatim as it appears in the photo, including spacing and label prefixes as printed. For serial regions this may differ from `photo.serial_number`, which is normalized for matching.
Example: "KMTPC180JM KK00001"
`true` when this region is (part of) the serial number that was read. A serial stamped across several lines yields several regions with this flag; concatenated in array order they form the read that `photo.serial_number` was normalized from.
Example: true
Recognition confidence for this region's text, between 0 and 1.
Example: 0.97
Left edge of the bounding rectangle as a fraction of image width (0 = left edge, 1 = right edge).
Example: 0.38
Top edge of the bounding rectangle as a fraction of image height (0 = top edge, 1 = bottom edge).
Example: 0.535
Width of the bounding rectangle as a fraction of image width.
Example: 0.35
Height of the bounding rectangle as a fraction of image height.
Example: 0.032
Example request
curl -X POST 'https://asset-gym.com/api/v1/catalog/identify' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
"description": "komatsu pc210lc-8 escavatore cingolato 2021 usato"
}'/api/v1/catalog/serial-numbers/decodeDecode serial numbers
Decode up to 10 serial numbers in one call and match each to the AssetBase catalogue. Decoding is deterministic: the same serial always resolves the same way, and there is no confidence score. Instead, every result carries a `status` saying how far the serial could be trusted: `decoded` (one asset), `model_not_in_catalog` (a model the catalogue lacks; the manufacturer is certain), `ambiguous_model` (one manufacturer, several candidate models), `unknown_model` (manufacturer and year; the model code is not in the rules), `checksum_failed` (manufacturer only; distrust the serial), `unrecognized_format` (manufacturer only, from the prefix), `ambiguous_manufacturer` (several manufacturers' formats fit), `no_match` (nothing identified), `unsupported_manufacturer` (the `manufacturer_id` sent has no formats), or `error` (a fault on that item). Results come back in request order, one per serial, each echoing its `serial_number`. A fault on one item never fails the request: it is reported as that item's `error` and the other items decode normally. Send `manufacturer_id` as a hint when the same format is used by several manufacturers; a manufacturer prefix in the serial overrides it. Serials are decoded exactly as sent (case-sensitive). Each serial is billed at its own credit weight, whatever its outcome.
Request body
Serials to decode, 1–10 per call. Each item is decoded and billed on its own.
Serial number as stamped on the asset's identification plate, 1–64 characters. Sent to the decoder unchanged: keep the stamped case and dashes (they are part of some formats), but strip label prefixes such as `SERIAL NO`.
Example: "KMTPC180JMKK00001"
Optional asset id of a manufacturer (a root node of the assets tree) to decode against. A hint, not evidence: it restricts decoding to that manufacturer's formats and is not billed. A manufacturer prefix in the serial itself (a WMI) overrides it. An id that is not a manufacturer yields a `manufacturer_not_found` error for that item only.
Example: 1777
Responses
One result per requested serial, in request order, each echoing its `serial_number`. Branch on `status`; the other fields depend on it.
The serial this result is for, exactly as sent.
Example: "KMTPC180JMKK00001"
The serial names exactly one asset the catalogue has.
Enum: "decoded"
Example: "decoded"
The year encoded in the serial (the decoder does not say whether it is a model year or a build year), or `null` when the serial encodes none or its year code is unknown.
Example: 2021
The identified asset.
Id of the node in the assets tree. Any level: a manufacturer when only the maker is known, a family node for a shared ancestor, a model for a precise decode. The stable handle to store and compare.
Example: 36988
Friendly display string: the full concatenated asset chain (e.g. `"Komatsu PC 210LC-8"`, or just `"Komatsu"` for a manufacturer).
Example: "Komatsu PC 210LC-8"
Chain through the assets tree ordered from the root down: the manufacturer first, this asset last.
Id of the node (asset_id or taxonomy_id).
Example: 100
Name of the chain node.
Example: "Caterpillar"
Id of the asset's own taxonomy node, or `null` when it carries none (manufacturers never do; a few models don't). Not inherited from parents.
Example: 1063
Friendly display string of the taxonomy node. `null` when `taxonomy_id` is `null`.
Example: "76-130 KW"
Chain through the taxonomy tree ordered from the root down: the broadest category first, the asset's taxonomy last. `[]` when `taxonomy_id` is `null`.
Id of the node (asset_id or taxonomy_id).
Example: 100
Name of the chain node.
Example: "Caterpillar"
The serial this result is for, exactly as sent.
Example: "KMTPC180JMKK00001"
The serial names a model the catalogue does not have yet. The manufacturer is certain; use it, and read the model from `decoded_name_path`.
Enum: "model_not_in_catalog"
Example: "model_not_in_catalog"
The year encoded in the serial (the decoder does not say whether it is a model year or a build year), or `null` when the serial encodes none or its year code is unknown.
Example: 2021
The decoder's own name path for what the serial names, manufacturer first. Fixed when the decoding rules were written, so it is a label, not a catalogue name.
Example: ["Case IH","Luxxum 100"]
The serial this result is for, exactly as sent.
Example: "KMTPC180JMKK00001"
The serial names one manufacturer and one of several models (a type code shared across models).
Enum: "ambiguous_model"
Example: "ambiguous_model"
The year encoded in the serial (the decoder does not say whether it is a model year or a build year), or `null` when the serial encodes none or its year code is unknown.
Example: 2021
The assets the serial may name, each a descendant of `common_ancestor`. Narrow them with other evidence. Can be shorter than the decoder's own list when the catalogue lacks some of the models, even empty.
Id of the node in the assets tree. Any level: a manufacturer when only the maker is known, a family node for a shared ancestor, a model for a precise decode. The stable handle to store and compare.
Example: 36988
Friendly display string: the full concatenated asset chain (e.g. `"Komatsu PC 210LC-8"`, or just `"Komatsu"` for a manufacturer).
Example: "Komatsu PC 210LC-8"
Chain through the assets tree ordered from the root down: the manufacturer first, this asset last.
Id of the node (asset_id or taxonomy_id).
Example: 100
Name of the chain node.
Example: "Caterpillar"
Id of the asset's own taxonomy node, or `null` when it carries none (manufacturers never do; a few models don't). Not inherited from parents.
Example: 1063
Friendly display string of the taxonomy node. `null` when `taxonomy_id` is `null`.
Example: "76-130 KW"
Chain through the taxonomy tree ordered from the root down: the broadest category first, the asset's taxonomy last. `[]` when `taxonomy_id` is `null`.
Id of the node (asset_id or taxonomy_id).
Example: 100
Name of the chain node.
Example: "Caterpillar"
The serial this result is for, exactly as sent.
Example: "KMTPC180JMKK00001"
The format matched and every position was read, but the model code is not in the decoder's rules. The manufacturer and the year are certain; the serial is fine and the rules are incomplete.
Enum: "unknown_model"
Example: "unknown_model"
The year encoded in the serial (the decoder does not say whether it is a model year or a build year), or `null` when the serial encodes none or its year code is unknown.
Example: 2021
The serial this result is for, exactly as sent.
Example: "KMTPC180JMKK00001"
The format matched, but the serial fails its own check character, so it is corrupt or misread and nothing it encodes counts as evidence. Only the manufacturer the format proves is reported; distrust the serial.
Enum: "checksum_failed"
Example: "checksum_failed"
The serial this result is for, exactly as sent.
Example: "KMTPC180JMKK00001"
The serial opens on a prefix that proves the manufacturer (a WMI, a factory prefix), but none of that manufacturer's formats accepts it. Nothing past the prefix was read; the serial may be corrupt or its format not covered yet.
Enum: "unrecognized_format"
Example: "unrecognized_format"
The serial this result is for, exactly as sent.
Example: "KMTPC180JMKK00001"
Several manufacturers' formats accept the serial equally well. The tie itself attributes nothing; each alternative is a complete decode under its own manufacturer. Send `manufacturer_id` to break the tie.
Enum: "ambiguous_manufacturer"
Example: "ambiguous_manufacturer"
One complete decode per manufacturer whose format matched.
The serial names exactly one asset the catalogue has.
Enum: "decoded"
Example: "decoded"
The year encoded in the serial (the decoder does not say whether it is a model year or a build year), or `null` when the serial encodes none or its year code is unknown.
Example: 2021
The identified asset.
Id of the node in the assets tree. Any level: a manufacturer when only the maker is known, a family node for a shared ancestor, a model for a precise decode. The stable handle to store and compare.
Example: 36988
Friendly display string: the full concatenated asset chain (e.g. `"Komatsu PC 210LC-8"`, or just `"Komatsu"` for a manufacturer).
Example: "Komatsu PC 210LC-8"
Chain through the assets tree ordered from the root down: the manufacturer first, this asset last.
Id of the node (asset_id or taxonomy_id).
Example: 100
Name of the chain node.
Example: "Caterpillar"
Id of the asset's own taxonomy node, or `null` when it carries none (manufacturers never do; a few models don't). Not inherited from parents.
Example: 1063
Friendly display string of the taxonomy node. `null` when `taxonomy_id` is `null`.
Example: "76-130 KW"
Chain through the taxonomy tree ordered from the root down: the broadest category first, the asset's taxonomy last. `[]` when `taxonomy_id` is `null`.
Id of the node (asset_id or taxonomy_id).
Example: 100
Name of the chain node.
Example: "Caterpillar"
The serial names a model the catalogue does not have yet. The manufacturer is certain; use it, and read the model from `decoded_name_path`.
Enum: "model_not_in_catalog"
Example: "model_not_in_catalog"
The year encoded in the serial (the decoder does not say whether it is a model year or a build year), or `null` when the serial encodes none or its year code is unknown.
Example: 2021
The decoder's own name path for what the serial names, manufacturer first. Fixed when the decoding rules were written, so it is a label, not a catalogue name.
Example: ["Case IH","Luxxum 100"]
The serial names one manufacturer and one of several models (a type code shared across models).
Enum: "ambiguous_model"
Example: "ambiguous_model"
The year encoded in the serial (the decoder does not say whether it is a model year or a build year), or `null` when the serial encodes none or its year code is unknown.
Example: 2021
The assets the serial may name, each a descendant of `common_ancestor`. Narrow them with other evidence. Can be shorter than the decoder's own list when the catalogue lacks some of the models, even empty.
Id of the node in the assets tree. Any level: a manufacturer when only the maker is known, a family node for a shared ancestor, a model for a precise decode. The stable handle to store and compare.
Example: 36988
Friendly display string: the full concatenated asset chain (e.g. `"Komatsu PC 210LC-8"`, or just `"Komatsu"` for a manufacturer).
Example: "Komatsu PC 210LC-8"
Chain through the assets tree ordered from the root down: the manufacturer first, this asset last.
Id of the node (asset_id or taxonomy_id).
Example: 100
Name of the chain node.
Example: "Caterpillar"
Id of the asset's own taxonomy node, or `null` when it carries none (manufacturers never do; a few models don't). Not inherited from parents.
Example: 1063
Friendly display string of the taxonomy node. `null` when `taxonomy_id` is `null`.
Example: "76-130 KW"
Chain through the taxonomy tree ordered from the root down: the broadest category first, the asset's taxonomy last. `[]` when `taxonomy_id` is `null`.
Id of the node (asset_id or taxonomy_id).
Example: 100
Name of the chain node.
Example: "Caterpillar"
The serial this result is for, exactly as sent.
Example: "KMTPC180JMKK00001"
No format identified the serial, so nothing about it is known. Suspect the serial: check the case (decoding is case-sensitive), dashes and label prefixes.
Enum: "no_match"
Example: "no_match"
The serial this result is for, exactly as sent.
Example: "KMTPC180JMKK00001"
The `manufacturer_id` sent names a manufacturer the decoder has no formats for, so the serial was never decoded and may be perfectly valid. Unlike `no_match`, no rules were tried.
Enum: "unsupported_manufacturer"
Example: "unsupported_manufacturer"
The serial this result is for, exactly as sent.
Example: "KMTPC180JMKK00001"
This item was not decoded, because of its own input or a catalogue gap. The other items in the request are unaffected.
Enum: "error"
Example: "error"
Why this item has no decode result.
`manufacturer_not_found`: the `manufacturer_id` sent is not an asset, or not a manufacturer (a root of the assets tree). `manufacturer_not_in_catalog`: the serial was recognized, but it belongs to a manufacturer the catalogue does not have yet.
Enum: "manufacturer_not_found" · "manufacturer_not_in_catalog"
Example: "manufacturer_not_found"
Human-readable explanation, safe to show to end users.
Example: "No manufacturer with id 36988."
Example request
curl -X POST 'https://asset-gym.com/api/v1/catalog/serial-numbers/decode' \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
"serial_numbers": [
{
"serial_number": "KMTPC180JMKK00001"
},
{
"serial_number": "158300001",
"manufacturer_id": 1777
}
]
}'