Book a demo

record_report_open

Record a report open

act entity tenant-private since 2026-10-01

Records that the caller opened a report in an org, as one event of its own: each open is a row, never a counter, and list_report_opens counts them over the last 90 days to order the Reports list by how often the person opens each report. Send an Idempotency-Key per open: the same key again is that open, never a second one.

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
keyed
emits
none
MCP tool
record_report_open
decision_set
approve, reject
REST
POST https://api.containertradehq.com/v1/cap/record_report_open

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

Idempotency: keyed by the caller's Idempotency-Key, which is required: the same key and inputs replay the first result, the same key with other inputs is 409 idempotency_key_reused

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org the report was opened in.
reportone_ofrequiredone of available_to_promise, yard_fees_by_unit, yard_monthly_fees, sourced_overall, sourced_by_supplier, orders_overall, orders_by_customer, activity_log, inventory_audit, failed_comms, depot_inventory, asset_inventory, cash_flow_audit
The report opened, by name.

Response

  • open_id · string · The open, derived from the call's Idempotency-Key.
  • user_id · string · Who opened it: the caller.
  • report · string · The report opened.
  • opened_at · string · When it was opened.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "open_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 open, derived from the call's Idempotency-Key.",
      "x-data-class": "operational"
    },
    "user_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who opened it: the caller.",
      "x-data-class": "operational"
    },
    "report": {
      "type": "string",
      "enum": [
        "available_to_promise",
        "yard_fees_by_unit",
        "yard_monthly_fees",
        "sourced_overall",
        "sourced_by_supplier",
        "orders_overall",
        "orders_by_customer",
        "activity_log",
        "inventory_audit",
        "failed_comms",
        "depot_inventory",
        "asset_inventory",
        "cash_flow_audit"
      ],
      "description": "The report opened.",
      "x-data-class": "operational"
    },
    "opened_at": {
      "type": "string",
      "format": "date-time",
      "description": "When it was opened.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "open_id",
    "user_id",
    "report",
    "opened_at"
  ],
  "additionalProperties": false
}

Refusals

  • idempotency_key_reused · 409 · this Idempotency-Key already recorded a different open, past the retry store's retention
  • retry_key_mismatch · 409 · the Idempotency-Key was already used with a different request
  • retry_key_in_flight · 409 · a request with this Idempotency-Key is still running
  • retry_key_lost · 409 · another request took over this Idempotency-Key first; nothing was applied

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
  • MCP: approval required
  • Voice: a report is opened on a screen; the page records its own open
  • Push: emits nothing
  • OneBox: no document originates a report open
  • Outbound: crosses to no counterparty

Events

None emitted.

Related

None.