pin_view · Pin a saved view to a tab's Home

Contract

shape: entity
authority: act
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: natural
emits: none
MCP tool: pin_view
decision_set: approve, reject
REST: POST https://api.containertradehq.com/v1/cap/pin_view

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the contract's own inputs: the same inputs replay the first call's result

Inputs

name	type	required	validation
org_id	org_id	required	tradehq-org-id; 1 to 20 characters The org the view is in.
view_id	text	required	1 to 64 characters The view to pin.
tab	one_of	required	one of depots, sell, source, intel The tab whose Home shows it.
for	one_of	optional	one of me, everyone; default "me" me (the default): the caller's own Home. everyone: every member's, an org admin's to pin.
pinned	boolean	optional	false takes the pin down. Pinned when left out.

Response

view_id · string · The view: a UUID, or system:<name> for a system view.
capability · string · The list capability it calls.
mode · stringnull · 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.
contract · string · The capability's contract and the stored call's version, <id>@<n>.
args · object · The call's arguments: filters, q, sort, fields and limit, as given.
title · string · What it is called.
pinned · boolean · Whether it is pinned to the top.
visibility · string · 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.
system · boolean · A system view: declared for every org, never changed.
owner_user_id · stringnull · Who saved it; null for a system view and for a moved view whose owner is gone.
writable · boolean · Whether the caller may change or delete it.
unmapped · string[] · What of an older saved search the call could not carry, each as field: why. Empty for a view saved as a call.
updated_at · stringnull · When it last changed; null for a system view.
shared_with · object[] · The teammates its owner shared it with by name, each {user_id, shared_by, created_at}, by user id. Empty for a system view.
pins · object[] · 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.

Full JSON Schema

{
  "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
}

Refusals

unknown_view · 422 · the org has no view by that id that the caller may read
view_read_only · 422 · a system view, or a view the caller may read and not change: another member's, shared org-read
org_pin_admin_only · 422 · a pin for everyone in the org is made or removed only by an org admin
view_not_shared_with_org · 422 · a view is pinned for everyone only once its owner has shared it with the org, so no member is shown a card they cannot open

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF

MobileF

APIF

MCPF*

VoiceD2

PushN

OneBoxN

OutboundN

MCP: approval required
Voice: degraded: confirmation
Push: emits nothing
OneBox: no document originates a saved view
Outbound: crosses to no counterparty

Events

None emitted.

delete_view, get_view, get_view_default, list_saved_views, save_view, set_my_view_default, set_org_view_default, share_view