list_depot_references · List an org's depot links

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_depot_references
REST: POST https://api.containertradehq.com/v1/cap/list_depot_references

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 links to list.
query	text	optional	1 to 100 characters A case-insensitive substring of the org's name or code for the depot, or the start of a BFC.
bfc	bfcs	optional	0 to 200 items; unique Only the links to these BFCs: a page of list_depot_registry, to join to it. A set: in any order, each code once (a repeat is refused). An empty list matches none.
limit	integer	optional	1 to 200; default 50 The page size.
after	uuid	optional	UUID The previous page's next_after. An id that is not one of this org's links ends the listing: an empty page.

Paginated: next next_after · page_max 200 · walk_max 10000 · 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": {
          "depot_reference_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 link's id: what remove_depot_reference names.",
            "x-data-class": "operational"
          },
          "bfc": {
            "type": "string",
            "pattern": "^[A-Z]{2}[A-Z2-9]{3}[A-Z0-9]{4}$",
            "format": "bic-facility-code",
            "description": "The depot's BIC Facility Code.",
            "x-data-class": "operational"
          },
          "depot_name": {
            "type": "string",
            "description": "The depot's name in the registry.",
            "x-data-class": "operational"
          },
          "alias": {
            "type": "string",
            "description": "The org's name for the depot.",
            "x-data-class": "operational"
          },
          "private_code": {
            "type": "string",
            "description": "The org's code for the depot; its name when it gave none.",
            "x-data-class": "operational"
          },
          "created_by": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20,
            "pattern": "^[A-Za-z0-9_-]{1,20}$",
            "format": "tradehq-user-id",
            "description": "The member who made the link.",
            "x-data-class": "operational"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When the link was made.",
            "x-data-class": "operational"
          }
        },
        "required": [
          "depot_reference_id",
          "bfc",
          "depot_name",
          "alias",
          "private_code",
          "created_by",
          "created_at"
        ],
        "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

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 depot link
Outbound: crosses to no counterparty

Events

None emitted.

claim_depot, list_depot_registry, reference_depot