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
- list_saved_views
- REST
- POST https://api.containertradehq.com/v1/cap/list_saved_views
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 views they are. |
| capability | one_of | optional | one of list_inventory, summarize_catalog, list_catalog Only the views of this list capability. Every list's when left out. |
| tab | one_of | optional | one of depots, sell, source, intel Only the views pinned to this tab's Home for the caller (theirs, or an org admin's for everyone), and no system view. Every view when left out. |
| mode | one_of | optional | one of inventory, sales, sales_lines Only the views of this mode: inventory, or sales (the Sales catalog's). Every mode's when left out. |
Paginated: next next_after · page_max 200 · walk_max 200 · 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": {
"view_id": {
"type": "string",
"description": "The view: a UUID, or system:<name> for a system view.",
"x-data-class": "operational"
},
"capability": {
"type": "string",
"enum": [
"list_inventory",
"summarize_catalog",
"list_catalog"
],
"description": "The list capability it calls.",
"x-data-class": "operational"
},
"mode": {
"type": [
"string",
"null"
],
"enum": [
"inventory",
"sales",
"sales_lines",
null
],
"description": "inventory: a grid of units. sales: a Sales catalog view, the grouped read with its split_by, source slice and layout. sales_lines: the sales grid's line table, a list_catalog call. Null only for a capability in no mode, which every_savable_capability_is_in_exactly_one_mode holds never happens.",
"x-data-class": "operational"
},
"contract": {
"type": "string",
"description": "The capability's contract and the stored call's version, <id>@<n>.",
"x-data-class": "operational"
},
"args": {
"type": "object",
"properties": {
"filters": {
"type": "object",
"description": "The list's filters input, as the capability declares it."
},
"q": {
"type": "string",
"description": "The list's q input."
},
"sort": {
"type": "array",
"minItems": 1,
"maxItems": 1,
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "One of the called capability's sort keys."
},
"dir": {
"type": "string",
"enum": [
"asc",
"desc"
],
"description": "Leave out for the key's own direction."
}
},
"required": [
"key"
],
"additionalProperties": false
},
"description": "The list's sort input: one key and its direction."
},
"fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "The list's fields input."
},
"limit": {
"type": "integer",
"description": "The list's limit input."
},
"split_by": {
"type": "array",
"items": {
"type": "string"
},
"description": "A Sales catalog view's split_by, in the order the attributes were switched on (summarize_catalog's input)."
},
"slice": {
"type": "string",
"enum": [
"owned",
"partner",
"supplier",
"all"
],
"description": "A Sales catalog view's source slice: owned, partner, supplier or all."
},
"layout": {
"type": "string",
"enum": [
"cards",
"rows"
],
"description": "A Sales catalog view's layout: cards or rows."
}
},
"additionalProperties": false,
"description": "The call's arguments: filters, q, sort, fields and limit, as given.",
"x-data-class": "operational"
},
"title": {
"type": "string",
"description": "What it is called.",
"x-data-class": "operational"
},
"pinned": {
"type": "boolean",
"description": "Whether it is pinned to the top.",
"x-data-class": "operational"
},
"visibility": {
"type": "string",
"enum": [
"private",
"org-read",
"org-write"
],
"description": "private: its owner alone. org-read: every member reads it. org-write: every member reads, changes and deletes it. A system view is org-read.",
"x-data-class": "operational"
},
"system": {
"type": "boolean",
"description": "A system view: declared for every org, never changed.",
"x-data-class": "operational"
},
"owner_user_id": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Za-z0-9_-]{1,20}$",
"format": "tradehq-user-id",
"description": "Who saved it; null for a system view and for a moved view whose owner is gone.",
"x-data-class": "operational"
},
"writable": {
"type": "boolean",
"description": "Whether the caller may change or delete it.",
"x-data-class": "operational"
},
"unmapped": {
"type": "array",
"items": {
"type": "string"
},
"description": "What of an older saved search the call could not carry, each as field: why. Empty for a view saved as a call.",
"x-data-class": "operational"
},
"updated_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When it last changed; null for a system view.",
"x-data-class": "operational"
},
"shared_with": {
"type": "array",
"items": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"format": "tradehq-user-id",
"description": "The teammate it is shared with."
},
"shared_by": {
"type": "string",
"format": "tradehq-user-id",
"description": "Who shared it: its owner."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When."
}
},
"required": [
"user_id",
"shared_by",
"created_at"
],
"additionalProperties": false
},
"description": "The teammates its owner shared it with by name, each {user_id, shared_by, created_at}, by user id. Empty for a system view.",
"x-data-class": "operational"
},
"pins": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tab": {
"type": "string",
"enum": [
"depots",
"sell",
"source",
"intel"
],
"description": "The tab whose Home shows it."
},
"for": {
"type": "string",
"enum": [
"me",
"everyone"
],
"description": "me: the caller's own pin. everyone: an org admin's, on every member's Home."
},
"user_id": {
"type": [
"string",
"null"
],
"format": "tradehq-user-id",
"description": "The caller, on their own pin; null on the org's."
},
"pinned_by": {
"type": "string",
"format": "tradehq-user-id",
"description": "Who pinned it: the caller, or the org admin who pinned it for everyone."
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "When."
}
},
"required": [
"tab",
"for",
"user_id",
"pinned_by",
"created_at"
],
"additionalProperties": false
},
"description": "Where it is pinned for the caller, by tab: their own pins (for me) and the org's (for everyone, an org admin's). Empty for a system view.",
"x-data-class": "operational"
}
},
"required": [
"view_id",
"capability",
"mode",
"contract",
"args",
"title",
"pinned",
"visibility",
"system",
"owner_user_id",
"writable",
"unmapped",
"updated_at",
"shared_with",
"pins"
],
"additionalProperties": false
},
"maxItems": 200
},
"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
too_many_views· 422 · the caller may read more than 200 views of this capability in the org, the most one listing answers
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 saved view
- Outbound: a read emits nothing
Events
None emitted.
Related
create_api_key, create_service_account, get_api_usage, get_view_default, pin_view, save_view, set_my_view_default, set_org_view_default