Contract
- shape
- entity
- authority
- read
- evidence
- none
- subscription
- false
- permission
- any one of: org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
- idempotency
- safe
- emits
- none
- MCP tool
- summarize_catalog
- REST
- POST https://api.containertradehq.com/v1/cap/summarize_catalog
Idempotency: a read: calling again changes nothing
Inputs
| name | type | required | validation |
|---|---|---|---|
| org_id | org_id | required | tradehq-org-id; 1 to 20 characters The org whose catalog it is. |
| filters | filters | optional | Lines matching every term given. |
| split_by | catalog_split_by | optional | 0 to 8 items; unique The attributes the groups split by, nested in this order (the order they were switched on): any of color, forklift_pockets, lockbox, vents, handles, depot, source and damage, each once. None when left out. |
Response
total· integer · The lines matching the filters.total_count· integer · Their units, summed.available_count· integer · Their units available to sell, summed.reserved_count· integer · Their units reserved, summed.secured_count· integer · Their units secured, summed.pending_count· integer · Their units pending, summed.available_secured_count· integer · Their units available and secured, summed.available_pending_count· integer · Their units available and pending, summed.split_by· string[] · The attributes the groups split by, in the order they nest: the split_by given, or none.groups· object[] · Every line the filters select, grouped by market, size, type and condition, ordered by those four (nulls last). Each group: id, market, size, type, condition, lines, catalog_ids (distinct, sorted), the seven counts summed under their list names (landed is available_secured_count, incoming available_pending_count), values (for every attribute not in split_by, its values with lines and available_count each, most available first; a depot's carries its name) and splits (the first split_by attribute's values, ordered by value, false before true, nulls last; each split: id, attribute, value, name, the same counts, values and its own splits by the next attribute, empty on the last). Every group and split carries photo: one real yard photo of a unit on its lines ({photo_id, container, taken_at}; a sound unit before a damaged one, then the newest, never one an org admin hid), or null when none of its units has one.prices· value · One entry per group and split, by its id: wholesale (suggested_price) and retail (retail_price), each min, max and avg (the unweighted mean over the lines that carry that price, rounded half away from zero) as 4-place decimal strings, and the lines priced. A price no line carries is null; the from price is min.
Full JSON Schema
{
"type": "object",
"properties": {
"total": {
"type": "integer",
"minimum": 0,
"description": "The lines matching the filters.",
"x-data-class": "operational"
},
"total_count": {
"type": "integer",
"minimum": 0,
"description": "Their units, summed.",
"x-data-class": "operational"
},
"available_count": {
"type": "integer",
"minimum": 0,
"description": "Their units available to sell, summed.",
"x-data-class": "operational"
},
"reserved_count": {
"type": "integer",
"minimum": 0,
"description": "Their units reserved, summed.",
"x-data-class": "operational"
},
"secured_count": {
"type": "integer",
"minimum": 0,
"description": "Their units secured, summed.",
"x-data-class": "operational"
},
"pending_count": {
"type": "integer",
"minimum": 0,
"description": "Their units pending, summed.",
"x-data-class": "operational"
},
"available_secured_count": {
"type": "integer",
"minimum": 0,
"description": "Their units available and secured, summed.",
"x-data-class": "operational"
},
"available_pending_count": {
"type": "integer",
"minimum": 0,
"description": "Their units available and pending, summed.",
"x-data-class": "operational"
},
"split_by": {
"type": "array",
"items": {
"type": "string"
},
"description": "The attributes the groups split by, in the order they nest: the split_by given, or none.",
"x-data-class": "operational"
},
"groups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"lines": {
"type": "integer",
"minimum": 0
},
"catalog_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"total_count": {
"type": "integer",
"minimum": 0
},
"available_count": {
"type": "integer",
"minimum": 0
},
"reserved_count": {
"type": "integer",
"minimum": 0
},
"secured_count": {
"type": "integer",
"minimum": 0
},
"pending_count": {
"type": "integer",
"minimum": 0
},
"available_secured_count": {
"type": "integer",
"minimum": 0
},
"available_pending_count": {
"type": "integer",
"minimum": 0
},
"photo": {
"type": [
"object",
"null"
],
"properties": {
"photo_id": {
"type": "string"
},
"container": {
"type": "string"
},
"taken_at": {
"type": "string"
}
},
"required": [
"photo_id",
"container",
"taken_at"
],
"additionalProperties": false
},
"values": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": [
"string",
"boolean",
"null"
]
},
"name": {
"type": [
"string",
"null"
]
},
"lines": {
"type": "integer",
"minimum": 0
},
"available_count": {
"type": "integer",
"minimum": 0
}
},
"required": [
"value",
"name",
"lines",
"available_count"
],
"additionalProperties": false
}
}
},
"market": {
"type": [
"string",
"null"
]
},
"size": {
"type": [
"string",
"null"
]
},
"type": {
"type": [
"string",
"null"
]
},
"condition": {
"type": [
"string",
"null"
]
},
"splits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"lines": {
"type": "integer",
"minimum": 0
},
"catalog_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"total_count": {
"type": "integer",
"minimum": 0
},
"available_count": {
"type": "integer",
"minimum": 0
},
"reserved_count": {
"type": "integer",
"minimum": 0
},
"secured_count": {
"type": "integer",
"minimum": 0
},
"pending_count": {
"type": "integer",
"minimum": 0
},
"available_secured_count": {
"type": "integer",
"minimum": 0
},
"available_pending_count": {
"type": "integer",
"minimum": 0
},
"photo": {
"type": [
"object",
"null"
],
"properties": {
"photo_id": {
"type": "string"
},
"container": {
"type": "string"
},
"taken_at": {
"type": "string"
}
},
"required": [
"photo_id",
"container",
"taken_at"
],
"additionalProperties": false
},
"values": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": [
"string",
"boolean",
"null"
]
},
"name": {
"type": [
"string",
"null"
]
},
"lines": {
"type": "integer",
"minimum": 0
},
"available_count": {
"type": "integer",
"minimum": 0
}
},
"required": [
"value",
"name",
"lines",
"available_count"
],
"additionalProperties": false
}
}
},
"attribute": {
"type": "string",
"enum": [
"color",
"forklift_pockets",
"lockbox",
"vents",
"handles",
"depot",
"source",
"damage"
]
},
"value": {
"type": [
"string",
"boolean",
"null"
]
},
"name": {
"type": [
"string",
"null"
]
},
"splits": {
"type": "array",
"items": {
"type": "object"
}
}
},
"required": [
"id",
"lines",
"catalog_ids",
"total_count",
"available_count",
"reserved_count",
"secured_count",
"pending_count",
"available_secured_count",
"available_pending_count",
"photo",
"values",
"attribute",
"value",
"name",
"splits"
]
}
}
},
"required": [
"id",
"lines",
"catalog_ids",
"total_count",
"available_count",
"reserved_count",
"secured_count",
"pending_count",
"available_secured_count",
"available_pending_count",
"photo",
"values",
"market",
"size",
"type",
"condition",
"splits"
]
},
"description": "Every line the filters select, grouped by market, size, type and condition, ordered by those four (nulls last). Each group: id, market, size, type, condition, lines, catalog_ids (distinct, sorted), the seven counts summed under their list names (landed is available_secured_count, incoming available_pending_count), values (for every attribute not in split_by, its values with lines and available_count each, most available first; a depot's carries its name) and splits (the first split_by attribute's values, ordered by value, false before true, nulls last; each split: id, attribute, value, name, the same counts, values and its own splits by the next attribute, empty on the last). Every group and split carries photo: one real yard photo of a unit on its lines ({photo_id, container, taken_at}; a sound unit before a damaged one, then the newest, never one an org admin hid), or null when none of its units has one.",
"x-data-class": "operational"
},
"prices": {
"anyOf": [
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"wholesale": {
"type": "object",
"properties": {
"min": {
"type": [
"string",
"null"
],
"pattern": "^-?[0-9]+\\.[0-9]{4}$"
},
"max": {
"type": [
"string",
"null"
],
"pattern": "^-?[0-9]+\\.[0-9]{4}$"
},
"avg": {
"type": [
"string",
"null"
],
"pattern": "^-?[0-9]+\\.[0-9]{4}$"
},
"lines": {
"type": "integer",
"minimum": 0
}
},
"required": [
"min",
"max",
"avg",
"lines"
],
"additionalProperties": false
},
"retail": {
"type": "object",
"properties": {
"min": {
"type": [
"string",
"null"
],
"pattern": "^-?[0-9]+\\.[0-9]{4}$"
},
"max": {
"type": [
"string",
"null"
],
"pattern": "^-?[0-9]+\\.[0-9]{4}$"
},
"avg": {
"type": [
"string",
"null"
],
"pattern": "^-?[0-9]+\\.[0-9]{4}$"
},
"lines": {
"type": "integer",
"minimum": 0
}
},
"required": [
"min",
"max",
"avg",
"lines"
],
"additionalProperties": false
}
},
"required": [
"id",
"wholesale",
"retail"
],
"additionalProperties": false
}
},
{
"const": "•••",
"description": "Masked by the caller's data policy."
},
{
"type": "null",
"description": "Denied by the caller's data policy."
}
],
"description": "One entry per group and split, by its id: wholesale (suggested_price) and retail (retail_price), each min, max and avg (the unweighted mean over the lines that carry that price, rounded half away from zero) as 4-place decimal strings, and the lines priced. A price no line carries is null; the from price is min.",
"x-data-class": "commercial"
}
},
"required": [
"total",
"total_count",
"available_count",
"reserved_count",
"secured_count",
"pending_count",
"available_secured_count",
"available_pending_count",
"split_by",
"groups",
"prices"
],
"additionalProperties": false
} Refusals
group_ceiling_reached· 422 · the filters select more than 50,000 lines, the most one grouped read groups
The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.
Surfaces
DesktopF
MobileF
APIF
MCPF
VoiceD4
PushN
OneBoxN
OutboundN
- Voice: degraded: visualization
- Push: emits nothing
- OneBox: no document originates a catalog summary
- Outbound: a read emits nothing
Events
None emitted.
Related
list_catalog, list_inventory, list_shared_catalog, summarize_inventory