reply_to_report · Reply to a report · Container Trade HQ API

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`); account.owner (account role owner or higher in the account of the org `org_id`); a deactivated caller is refused first
idempotency: keyed
emits: none
MCP tool: reply_to_report
decision_set: approve, reject
REST: POST https://api.containertradehq.com/v1/cap/reply_to_report

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

name	type	required	validation
org_id	org_id	required	tradehq-org-id; 1 to 20 characters The org the report is of.
report_id	uuid	required	UUID The report, as list_reports and get_report name it.
body	text	required	1 to 5000 characters Your reply.

Response

reply_id · string · The reply: rr and thirty characters, derived from the Idempotency-Key.
report_id · string · The report.
ticket · string · The report's reference (CUS-n).
at · string · When the reply was recorded on the report's timeline.
text · string · The reply as the timeline shows it: your words, with anything that looks like a password, card or account number masked.
emailed · boolean · Whether it also went to the report's email thread (a report filed by email).

Full JSON Schema

{
  "type": "object",
  "properties": {
    "reply_id": {
      "type": "string",
      "description": "The reply: rr and thirty characters, derived from the Idempotency-Key.",
      "x-data-class": "operational"
    },
    "report_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 report.",
      "x-data-class": "operational"
    },
    "ticket": {
      "type": "string",
      "description": "The report's reference (CUS-n).",
      "x-data-class": "operational"
    },
    "at": {
      "type": "string",
      "format": "date-time",
      "description": "When the reply was recorded on the report's timeline.",
      "x-data-class": "operational"
    },
    "text": {
      "type": "string",
      "description": "The reply as the timeline shows it: your words, with anything that looks like a password, card or account number masked.",
      "x-data-class": "operational"
    },
    "emailed": {
      "type": "boolean",
      "description": "Whether it also went to the report's email thread (a report filed by email).",
      "x-data-class": "operational"
    }
  },
  "required": [
    "reply_id",
    "report_id",
    "ticket",
    "at",
    "text",
    "emailed"
  ],
  "additionalProperties": false
}

Refusals

report_not_found · 422 · the org has no such report, or it is private to its reporter
reply_not_delivered · 422 · the reply could not be delivered just now; send it again with the same Idempotency-Key
reports_unavailable · 422 · this deployment has no broker credential for reports yet; nothing was sent
retry_key_mismatch · 409 · the Idempotency-Key was already used with a different reply
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

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: a reply is written by a person, not read off a document
Outbound: goes to Trade HQ's support, never to a counterparty

Events

None emitted.

confirm_report, follow_report, get_report, mark_report_seen, reopen_report, unfollow_report