Skip to content
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
GET
/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
asset_idintegerrequired
Id of the asset the figures belong to.
Example: 1234
co2_per_unitnumberrequirednullable
Operational CO2e emitted per usage unit (see `co2_unit`).
Example: 32.7
co2_unitstringrequirednullable
Unit of `co2_per_unit`.
Example: "kg/h"
co2_per_yearnumberrequirednullable
Operational CO2e per year in kilograms, computed from `co2_per_unit` and the typical yearly usage.
Example: 58860
yearly_usage_amountnumberrequirednullable
Typical yearly usage assumed for `co2_per_year`.
Example: 1800
yearly_usage_unitstringrequirednullable
Unit of `yearly_usage_amount`.
Example: "h/year"
fuel_typestringrequirednullable
Fuel or energy carrier of the asset. Multi-fuel assets list every carrier slash-joined (e.g. `petrol/electric`).
Example: "diesel"
fuel_consumptionsarrayrequired
Consumption figures backing the CO2 numbers. Empty when not available.
array of:
fuel_typestringrequired
Fuel or energy carrier this consumption entry refers to.
Example: "diesel"
consumptionnumberrequired
Consumption amount per `consumption_unit`.
Example: 12.4
consumption_unitstringrequired
Unit of the consumption amount.
Example: "l/h"
sourcestringrequired
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>'GET
/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
asset_idintegerrequired
Id of the asset the figures belong to.
Example: 1234
material_kgco2enumberrequirednullable
Embodied emissions of the asset's materials, in kg CO2e.
Example: 78100
energy_kgco2enumberrequirednullable
Manufacturing-energy emissions, in kg CO2e.
Example: 18300
total_kgco2enumberrequirednullable
Total production emissions (materials + manufacturing energy), in kg CO2e.
Example: 96400
material_compositionarrayrequired
Material breakdown of the asset, ordered by share, largest first. Empty when not available.
array of:
materialstringrequired
Material name.
Example: "steel"
mass_kgnumberrequirednullable
Mass of this material in the asset, in kilograms. `null` when only the share is known.
Example: 15330
sharenumberrequired
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>'GET
/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
asset_idintegerrequired
Id of the asset the figures belong to.
Example: 1234
recycling_emissions_kgco2enumberrequirednullable
Emissions caused by the recycling process itself, in kg CO2e.
Example: 4100
recycling_credit_kgco2enumberrequirednullable
Avoided-burden credit for recovered materials, in kg CO2e. Positive number; subtract it from the emissions.
Example: 12600
net_kgco2enumberrequirednullable
`recycling_emissions_kgco2e` minus `recycling_credit_kgco2e`. Negative when recycling is a net benefit.
Example: -8500
material_compositionarrayrequired
Material breakdown of the asset, ordered by share, largest first. Empty when not available.
array of:
materialstringrequired
Material name.
Example: "steel"
mass_kgnumberrequirednullable
Mass of this material in the asset, in kilograms. `null` when only the share is known.
Example: 15330
sharenumberrequired
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>'GET
/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
asset_idintegerrequired
Id of the asset the specification belongs to.
Example: 1234
weight_kgnumberrequirednullable
Operating weight in kilograms.
Example: 21900
engine_power_kwnumberrequirednullable
Rated engine power in kilowatts.
Example: 122
fuel_typestringrequirednullable
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>'GET
/api/v1/catalog/assets/{asset_id}/technical-specification-attributesList technical specification attributes
Coming soonEvery 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. Note: this is a preview endpoint that currently returns illustrative mock data.
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
dataarrayrequired
Page of the asset's technical specification attributes.
array of:
keystringrequired
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"
labelstringrequired
Canonical human-readable label of the attribute, identical for every asset.
Example: "Maximum digging depth"
valueanyOfrequired
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
unitstringrequirednullable
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"
totalinteger
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>'GET
/api/v1/catalog/taxonomies/{taxonomy_id}/technical-specification-attributesList taxonomy technical specification attributes
Coming soonThe 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 from a periodically refreshed snapshot, so recent catalog changes may take up to a day to appear. Note: this is a preview endpoint that currently returns illustrative mock data.
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
dataarrayrequired
Page of the taxonomy's attribute vocabulary, ordered by descending `coverage`.
array of:
keystringrequired
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"
labelstringrequired
Canonical human-readable label of the attribute, identical for every asset.
Example: "Maximum digging depth"
data_typestringrequired
Type of the `value` asset entries carry for this key. New types may be added over time.
Enum: "number" · "string"
Example: "number"
unitstringrequirednullable
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"
coveragenumberrequired
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
totalinteger
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>'GET
/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
asset_idintegerrequired
Id of the asset the content belongs to.
Example: 1234
summarystringrequirednullable
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."
descriptionstringrequirednullable
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…"
highlightsarrayrequired
Short bullet-style facts about the asset. Empty when not available.
array of:
string
applicationsarrayrequired
Typical applications and industries the asset is used in. Empty when not available.
array of:
string
Example request
curl -X GET 'https://asset-gym.com/api/v1/catalog/assets/<asset_id>/geo-content' \
-H 'Authorization: Bearer <YOUR_API_KEY>'AssetVault
GET
/api/v1/vault-filesList asset vault files
Returns up to 50 asset vault files belonging to the authenticated user.
Responses
dataarrayrequired
array of:
idstringrequired
Short UUID of the file
Example: "mMxzWbBDSfiEP6MBcfNUgP"
namestringrequired
Original file name
Example: "report.pdf"
mime_typestringrequired
MIME type
Example: "application/pdf"
size_bytesintegerrequired
File size in bytes
Example: 102400
last_downloaded_atstringrequirednullable
ISO 8601 timestamp of last download
Example: "2026-04-20T10:30:00.000Z"
created_atstringrequired
ISO 8601 creation timestamp
Example: "2026-04-15T08:00:00.000Z"
download_urlurirequired
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=..."
download_url_expires_atstringrequired
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
POST
/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
querystringrequired
Free-text term that is being searched.
Example: "komatsu pc210"
entity_typestring
Restrict results to a single domain. Omit to return both.
Enum: "taxonomy" · "asset"
Example: "asset"
parent_idinteger
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
taxonomy_idinteger
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
direct_onlyboolean
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
dataarrayrequired
Ranked list of suggestions. Capped to at most 5 entries.
array of:
idintegerrequired
Id of the underlying entity. When `entity_type` = 'asset' this is the `asset_id`; when 'taxonomy' it is the `taxonomy_id`.
Example: 1234
entity_typestringrequired
`taxonomy` matches any taxonomy level; `asset` matches manufacturers and individual assets.
Enum: "taxonomy" · "asset"
Example: "asset"
display_namestringrequired
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"
asset_chainarrayrequired
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`).
array of:
idintegerrequired
Id of the node (asset_id or taxonomy_id).
Example: 100
namestringrequired
Name of the chain node.
Example: "Caterpillar"
taxonomy_chainarrayrequired
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.
array of:
idintegerrequired
Id of the node (asset_id or taxonomy_id).
Example: 100
namestringrequired
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
}'GET
/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
dataarrayrequired
Page of taxonomy nodes.
array of:
idintegerrequired
Id of the taxonomy node.
Example: 12
namestringrequired
Name of the taxonomy.
Example: "Excavators"
parent_idintegerrequirednullable
Direct parent id, or `null` for a root taxonomy.
Example: 3
totalinteger
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>'GET
/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
idintegerrequired
Id of the taxonomy node.
Example: 12
namestringrequired
Name of the taxonomy.
Example: "Excavators"
parent_idintegerrequirednullable
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>'GET
/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
dataarrayrequired
Page of asset nodes.
array of:
idintegerrequired
Id of the asset node.
Example: 1234
namestringrequired
Name of the asset.
Example: "210-7"
qualified_namestringrequired
Name prefixed with all ancestor names, space-separated (e.g. `Komatsu PC 210-7`).
Example: "Komatsu PC 210-7"
parent_idintegerrequirednullable
Direct parent asset id, or `null` for a manufacturer.
Example: 100
totalinteger
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>'GET
/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
idintegerrequired
Id of the asset node.
Example: 1234
namestringrequired
Name of the asset.
Example: "210-7"
qualified_namestringrequired
Name prefixed with all ancestor names, space-separated (e.g. `Komatsu PC 210-7`).
Example: "Komatsu PC 210-7"
parent_idintegerrequirednullable
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
POST
/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: every match declares which inputs support it (`basis`), matches supported by several inputs rank first, deterministic serial decodes carry an `explanation` with character-level `explanation_segments`, and probabilistic description matches carry a `confidence`. When a photo was sent, `photo` in the response 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` to constrain serial decoding when the same pattern is used by several manufacturers. 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
descriptionstring
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: "cat 320gc escavatore cingolato 2019 usato"
serial_numberstring
Serial number as stamped on the asset's identification plate.
Example: "CAT0320GC-A9K02154"
manufacturer_idinteger
Optional asset id of a manufacturer (a root node of the assets tree) to constrain serial decoding. A scope, not evidence: it narrows the search, it is not billed, and it never appears in `basis`. Unknown ids return `404 not_found`.
Example: 100
Responses
dataarrayrequired
Potential matches across all provided inputs, ranked best first: matches supported by more inputs rank above single-input matches, deterministic serial decodes rank above probabilistic ones, and probabilistic matches are ordered by `confidence`. Empty when nothing matched. Each match identifies the asset axis, the taxonomy axis, or both. Capped to at most 5 entries.
array of:
asset_idintegerrequirednullable
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: 1234
taxonomy_idintegerrequirednullable
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: 56
asset_display_namestringrequirednullable
Friendly display string for the asset axis: the full concatenated asset chain (e.g. `"Caterpillar 320 GC"`, or just `"Caterpillar"` for a manufacturer-level match). `null` when `asset_id` is `null`.
Example: "Caterpillar 320 GC"
taxonomy_display_namestringrequirednullable
Friendly display string for the taxonomy axis: the bare taxonomy name (e.g. `"Crawler excavator"`). `null` when `taxonomy_id` is `null`.
Example: "Crawler excavator"
basisarrayrequired
The request inputs that support this match, in the order `description`, `serial_number`, `photo`. A match supported by several inputs at once ranks above single-input matches.
Example: ["serial_number"]
array of:
stringA request input that contributed to a match. `serial_number` refers to the serial sent as a field; `photo` to the serial (and text) read off the uploaded photo.
confidencenumberrequirednullable
Match confidence between 0 and 1 for probabilistic evidence (a description). `null` when the match rests purely on deterministic serial decoding; those matches carry an `explanation` instead and rank first. Thresholds are up to the client; values above 0.9 are usually safe to auto-accept.
Example: 0.93
explanationstringrequirednullable
Prepared English explanation of how the serial number was decoded into this match, assembled from `explanation_segments`; safe to show to end users. `null` when no serial contributed to the match.
Example: "Characters 1–3 “CAT” identify Caterpillar. Characters 4–9 “0320GC” identify the 320 GC model line. Character 11 “A” encodes the 2019 model year."
explanation_segmentsarrayrequired
Programmatic serial-decoding derivation, ordered by `position_start`. Each segment states which characters were read and what they resolved to. Deterministic: the same serial always yields the same segments. Positions are 1-indexed into the serial number: the `serial_number` request field, or `photo.serial_number` when the serial was read off a photo. `[]` when no serial contributed to the match.
array of:
kindstringrequired
What a decoded serial segment encodes. `manufacturer`: the maker; `model`: the model or model line; `model_year`: the production year code; `plant`: the factory of origin; `sequence`: the per-unit production sequence (identifies the individual machine, not decoded further).
Enum: "manufacturer" · "model" · "model_year" · "plant" · "sequence"
Example: "manufacturer"
charactersstringrequired
The exact characters of the serial number this segment covers.
Example: "CAT"
position_startintegerrequired
1-indexed position of the segment's first character within the serial number.
Example: 1
position_endintegerrequired
1-indexed position of the segment's last character (inclusive).
Example: 3
resolved_valuestringrequired
What the segment resolves to, human-readable: a manufacturer name for `manufacturer`, a model line for `model`, a year for `model_year`. For `sequence` segments this is the sequence itself.
Example: "Caterpillar"
asset_chainarrayrequired
Chain through the assets tree ordered from the root down: the manufacturer first, the identified node last. `[]` when `asset_id` is `null`.
array of:
idintegerrequired
Id of the node (asset_id or taxonomy_id).
Example: 100
namestringrequired
Name of the chain node.
Example: "Caterpillar"
taxonomy_chainarrayrequired
Chain through the taxonomy tree ordered from the root down: the broadest category first, the identified taxonomy last. `[]` when `taxonomy_id` is `null`.
array of:
idintegerrequired
Id of the node (asset_id or taxonomy_id).
Example: 100
namestringrequired
Name of the chain node.
Example: "Caterpillar"
photoobject
What was read off the uploaded photo. Present exactly when the request carried a `photo`; absent for JSON requests.
serial_numberstringrequirednullable
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: "CAT0320GC-A9K02154"
serial_number_confidencenumberrequirednullable
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
image_widthintegerrequired
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
image_heightintegerrequired
Height in pixels of the photo as processed, after EXIF orientation was applied.
Example: 4032
text_annotationsarrayrequired
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.
array of:
textstringrequired
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: "CAT 0320GC-A 9K02154"
is_serial_numberbooleanrequired
`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
confidencenumberrequired
Recognition confidence for this region's text, between 0 and 1.
Example: 0.97
xnumberrequired
Left edge of the bounding rectangle as a fraction of image width (0 = left edge, 1 = right edge).
Example: 0.38
ynumberrequired
Top edge of the bounding rectangle as a fraction of image height (0 = top edge, 1 = bottom edge).
Example: 0.535
widthnumberrequired
Width of the bounding rectangle as a fraction of image width.
Example: 0.35
heightnumberrequired
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": "cat 320gc escavatore cingolato 2019 usato"
}'