Contract
- shape
- collection
- 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
- search_records
- REST
- POST https://api.containertradehq.com/v1/cap/search_records
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 records to search. |
| q | text | required | 2 to 100 characters What was typed: a number, a name or an address, matched case folded, exactly, as a prefix or inside the text. |
| kinds | record_kinds | optional | 1 to 6 items; unique Only these kinds of record: order, intake, unit, purchase_order, party, share. Absent, every kind. |
| limit | integer | optional | 1 to 50; default 20 How many of the best hits to answer. |
Paginated: next next_after · page_max 50 · walk_max 50 · ceiling declared
Response
items· object[]next_after· stringnull · Pass as `after` for the next page; null on the last one.
Full JSON Schema
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"order",
"intake",
"unit",
"purchase_order",
"party",
"share"
],
"description": "What kind of record it is.",
"x-data-class": "operational"
},
"id": {
"type": "string",
"description": "The record's id: an order, intake, asset, contact or share id.",
"x-data-class": "operational"
},
"label": {
"type": "string",
"description": "What the record is called: the invoice number, booking number, BIC number, PO number, name, or the id when it has none.",
"x-data-class": "operational"
},
"subtitle": {
"anyOf": [
{
"type": [
"string",
"null"
]
},
{
"const": "•••",
"description": "Masked by the caller's data policy."
},
{
"type": "null",
"description": "Denied by the caller's data policy."
}
],
"description": "A short line beside the label: an order's customer, an intake's or purchase order's supplier, a unit's inventory status, a party's role (customer or supplier), or the share recipient whose address matched.",
"x-data-class": "personal"
},
"route": {
"type": "string",
"description": "The web route that opens the record.",
"x-data-class": "operational"
},
"match": {
"type": "string",
"enum": [
"exact",
"prefix",
"contains"
],
"description": "How it matched: exactly (for a BIC number, its first ten characters whatever the check digit), as a prefix, or inside the text.",
"x-data-class": "operational"
}
},
"required": [
"kind",
"id",
"label",
"subtitle",
"route",
"match"
],
"additionalProperties": false
},
"maxItems": 50
},
"next_after": {
"type": [
"string",
"null"
],
"description": "Pass as `after` for the next page; null on the last one."
}
},
"required": [
"items",
"next_after"
],
"additionalProperties": false
} Refusals
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 record search
- Outbound: a read emits nothing
Events
None emitted.