preview_data_share · Preview a data share

Contract

shape: entity
authority: read
evidence: none
subscription: false
permission: any one of: org.admin (carried by the caller's role template in the org `org_id`); share (org.member carried by the caller's role template in an org that has claimed the share's party, for a stored share named by data_share_id that is not revoked or declined); a deactivated caller is refused first
idempotency: safe
emits: none
MCP tool: preview_data_share
REST: POST https://api.containertradehq.com/v1/cap/preview_data_share

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 sharing its data.
data_share_id	uuid	optional	UUID A stored share to preview. Leave out to preview a proposed one.
party_id	uuid	optional	UUID For a proposed share: the counterparty.
query	one_of	optional	one of vendor_bill_request, vendor_forecast, vendor_sell_through The saved query: vendor_forecast (the org's open purchase orders with the vendor, with ETAs and units), vendor_sell_through (units bought from the vendor, sold and on hand, by size, type and condition) or vendor_bill_request (one bill request's units, as the cash flow audit's vendor export lists them).
contact_id	contact_id	optional	tradehq-contact-id; 3 to 20 characters For vendor_forecast and vendor_sell_through: the vendor, one of the org's own contacts. The party must hold the seller seat on at least one of the org's purchase orders with it, and only those purchase orders are shared. When the vendor is itself a Trade HQ org, the party must be the one that org has claimed.
request_id	bill_request_id	optional	tradehq-vendor-bill-request-id; 3 to 20 characters For vendor_bill_request: the cash flow audit's vendor bill request. Its units' one vendor is the vendor, and the party must hold the seller seat on every purchase order the units came in on.

Response

data_share_id · stringnull · The stored share; null for a proposed one.
org_id · string · The org sharing.
org_name · stringnull · The org's name, as the counterparty reads it.
party_id · string · The counterparty.
party_name · string · The counterparty's name in the directory.
query · string · The saved query.
title · string · The saved query's title.
columns · object[] · The columns, in the order of every row's cells.
rows · value · The rows the counterparty receives, at most 1000.
row_total · integer · How many rows there are in all.
truncated · boolean · Whether rows holds fewer than row_total.
floor · object[] · The party's seats on the purchase orders this share's rows come from, at most 1000. The party's whole floor is list_data_shares', inside Trade HQ; a share never sends more of it than its own rows stand on.
floor_total · integer · How many such seats there are in all.
recipients · value · A stored share's recipients; empty for a proposed one.
cadence · stringnull · A stored share's cadence; null for a proposed one.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "data_share_id": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$",
      "format": "uuid",
      "description": "The stored share; null for a proposed one.",
      "x-data-class": "operational"
    },
    "org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org sharing.",
      "x-data-class": "operational"
    },
    "org_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "The org's name, as the counterparty reads it.",
      "x-data-class": "operational"
    },
    "party_id": {
      "type": "string",
      "pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$",
      "format": "uuid",
      "description": "The counterparty.",
      "x-data-class": "operational"
    },
    "party_name": {
      "type": "string",
      "description": "The counterparty's name in the directory.",
      "x-data-class": "operational"
    },
    "query": {
      "type": "string",
      "enum": [
        "vendor_bill_request",
        "vendor_forecast",
        "vendor_sell_through"
      ],
      "description": "The saved query.",
      "x-data-class": "operational"
    },
    "title": {
      "type": "string",
      "description": "The saved query's title.",
      "x-data-class": "operational"
    },
    "columns": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "title": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "title"
        ],
        "additionalProperties": false
      },
      "description": "The columns, in the order of every row's cells.",
      "x-data-class": "operational"
    },
    "rows": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "array",
            "items": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        },
        {
          "const": "•••",
          "description": "Masked by the caller's data policy."
        },
        {
          "type": "null",
          "description": "Denied by the caller's data policy."
        }
      ],
      "description": "The rows the counterparty receives, at most 1000.",
      "x-data-class": "commercial"
    },
    "row_total": {
      "type": "integer",
      "minimum": 0,
      "description": "How many rows there are in all.",
      "x-data-class": "operational"
    },
    "truncated": {
      "type": "boolean",
      "description": "Whether rows holds fewer than row_total.",
      "x-data-class": "operational"
    },
    "floor": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "document_kind": {
            "type": "string",
            "enum": [
              "asset_intake",
              "order"
            ]
          },
          "document_id": {
            "type": "string"
          },
          "seat": {
            "type": "string",
            "enum": [
              "buyer",
              "lessee",
              "lessor",
              "seller"
            ]
          }
        },
        "required": [
          "document_kind",
          "document_id",
          "seat"
        ],
        "additionalProperties": false
      },
      "description": "The party's seats on the purchase orders this share's rows come from, at most 1000. The party's whole floor is list_data_shares', inside Trade HQ; a share never sends more of it than its own rows stand on.",
      "x-data-class": "operational"
    },
    "floor_total": {
      "type": "integer",
      "minimum": 0,
      "description": "How many such seats there are in all.",
      "x-data-class": "operational"
    },
    "recipients": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "string",
            "pattern": "^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(\\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*@([A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?\\.)+([A-Za-z]{2,}|[Xx][Nn]--[A-Za-z0-9-]*[A-Za-z0-9])$",
            "maxLength": 254
          },
          "uniqueItems": true
        },
        {
          "const": "•••",
          "description": "Masked by the caller's data policy."
        },
        {
          "type": "null",
          "description": "Denied by the caller's data policy."
        }
      ],
      "description": "A stored share's recipients; empty for a proposed one.",
      "x-data-class": "personal"
    },
    "cadence": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "daily",
        "hourly",
        null
      ],
      "description": "A stored share's cadence; null for a proposed one.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "data_share_id",
    "org_id",
    "org_name",
    "party_id",
    "party_name",
    "query",
    "title",
    "columns",
    "rows",
    "row_total",
    "truncated",
    "floor",
    "floor_total",
    "recipients",
    "cadence"
  ],
  "additionalProperties": false
}

Refusals

not yet declared

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

Surfaces

DesktopF

MobileF

APIF

MCPF

VoiceN

PushN

OneBoxN

OutboundN

Voice: a rendered table is read, not heard (D4 visualization)
Push: emits nothing
OneBox: no document originates a preview
Outbound: a preview is sent to nobody

Events

None emitted.

claim_party, create_data_share, decline_data_share, invite_guest, list_data_shares, revoke_data_share, search_party_directory