get_report · Get a customer report · Container Trade HQ API

Contract

shape: entity
authority: read
evidence: none
subscription: false
permission: any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); account.owner (account role owner or higher in the account of the org `org_id`); 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: get_report
REST: POST https://api.containertradehq.com/v1/cap/get_report

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 that filed the report.
report_id	uuid	required	UUID The report's id, as list_reports answers it.

Response

report_id · string · The report's id: its ticket's id in the support tracker.
org_id · string · The org that filed it.
ticket · string · Its reference, CUS-n, as the customer quotes it.
org_name · stringnull · That org's name.
title · string · The first line of the reporter's own words.
kind · string · Feedback, a problem or a question.
filed_via · string · How it was filed: in the app, by email, or by staff for the customer.
reporter · value · The member who filed it in the app, {user_id, name}; null when it was filed by email or by staff.
reporter_email · value · The sender's address, for a report filed by email.
impact · stringnull · How much it hurts, in the reporter's estimate.
private · boolean · Whether only its reporter and staff see it.
reported_at · string · When it was filed.
status · string · Where it stands.
status_at · string · When it reached that status.
window · stringnull · When a planned report is expected: next release, this month or later; null unless planned.
note · stringnull · The latest note written for the customer.
release_note_url · stringnull · The customer-facing release note of the fix, when it has one.
duplicate_of · stringnull · The report this one duplicates, when that report is this org's and the person asking may see it.
duplicate_status · stringnull · The status of the report this one duplicates.
fixed_at · stringnull · When the fix went live for the org.
days_to_fix · integernull · Calendar days, Pacific time, from the day reported to the day fixed.
last_event_at · stringnull · When its timeline last changed.
following · boolean · Whether the person asking follows it.
unread · boolean · Whether it changed since the person asking last saw it.
text · string · The reporter's own words, masked as filed; shown only inside the org.
page · stringnull · The app page it was filed from.
record · objectnull · The record the reporter was on, {kind, id}.
reopened_from · stringnull · The fixed or answered report this one reports again as still broken.
followers · value · Who follows it, [{user_id, name}], longest-standing first.
timeline · object[] · Every event, oldest first: {event_id, at, kind} and, by kind, from and to (status, window), text (note), from, user_id, name and text (reply), user_id and name (confirmed, followed, unfollowed), report_id and ticket (reopened).
seen_through · stringnull · The newest event the person asking has seen.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "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's id: its ticket's id in the support tracker.",
      "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 that filed it.",
      "x-data-class": "operational"
    },
    "ticket": {
      "type": "string",
      "description": "Its reference, CUS-n, as the customer quotes it.",
      "x-data-class": "operational"
    },
    "org_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "That org's name.",
      "x-data-class": "operational"
    },
    "title": {
      "type": "string",
      "description": "The first line of the reporter's own words.",
      "x-data-class": "operational"
    },
    "kind": {
      "type": "string",
      "enum": [
        "feedback",
        "problem",
        "question"
      ],
      "description": "Feedback, a problem or a question.",
      "x-data-class": "operational"
    },
    "filed_via": {
      "type": "string",
      "enum": [
        "app",
        "email",
        "staff"
      ],
      "description": "How it was filed: in the app, by email, or by staff for the customer.",
      "x-data-class": "operational"
    },
    "reporter": {
      "anyOf": [
        {
          "type": [
            "object",
            "null"
          ]
        },
        {
          "const": "•••",
          "description": "Masked by the caller's data policy."
        },
        {
          "type": "null",
          "description": "Denied by the caller's data policy."
        }
      ],
      "description": "The member who filed it in the app, {user_id, name}; null when it was filed by email or by staff.",
      "x-data-class": "personal"
    },
    "reporter_email": {
      "anyOf": [
        {
          "type": [
            "string",
            "null"
          ]
        },
        {
          "const": "•••",
          "description": "Masked by the caller's data policy."
        },
        {
          "type": "null",
          "description": "Denied by the caller's data policy."
        }
      ],
      "description": "The sender's address, for a report filed by email.",
      "x-data-class": "personal"
    },
    "impact": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "blocking",
        "slowing",
        "suggestion",
        null
      ],
      "description": "How much it hurts, in the reporter's estimate.",
      "x-data-class": "operational"
    },
    "private": {
      "type": "boolean",
      "description": "Whether only its reporter and staff see it.",
      "x-data-class": "operational"
    },
    "reported_at": {
      "type": "string",
      "format": "date-time",
      "description": "When it was filed.",
      "x-data-class": "operational"
    },
    "status": {
      "type": "string",
      "enum": [
        "received",
        "waiting_on_you",
        "planned",
        "fixed",
        "answered",
        "wont_fix",
        "duplicate"
      ],
      "description": "Where it stands.",
      "x-data-class": "operational"
    },
    "status_at": {
      "type": "string",
      "format": "date-time",
      "description": "When it reached that status.",
      "x-data-class": "operational"
    },
    "window": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "next_release",
        "this_month",
        "later",
        null
      ],
      "description": "When a planned report is expected: next release, this month or later; null unless planned.",
      "x-data-class": "operational"
    },
    "note": {
      "type": [
        "string",
        "null"
      ],
      "description": "The latest note written for the customer.",
      "x-data-class": "operational"
    },
    "release_note_url": {
      "type": [
        "string",
        "null"
      ],
      "description": "The customer-facing release note of the fix, when it has one.",
      "x-data-class": "operational"
    },
    "duplicate_of": {
      "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 report this one duplicates, when that report is this org's and the person asking may see it.",
      "x-data-class": "operational"
    },
    "duplicate_status": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "received",
        "waiting_on_you",
        "planned",
        "fixed",
        "answered",
        "wont_fix",
        "duplicate",
        null
      ],
      "description": "The status of the report this one duplicates.",
      "x-data-class": "operational"
    },
    "fixed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the fix went live for the org.",
      "x-data-class": "operational"
    },
    "days_to_fix": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Calendar days, Pacific time, from the day reported to the day fixed.",
      "x-data-class": "operational"
    },
    "last_event_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When its timeline last changed.",
      "x-data-class": "operational"
    },
    "following": {
      "type": "boolean",
      "description": "Whether the person asking follows it.",
      "x-data-class": "operational"
    },
    "unread": {
      "type": "boolean",
      "description": "Whether it changed since the person asking last saw it.",
      "x-data-class": "operational"
    },
    "text": {
      "type": "string",
      "description": "The reporter's own words, masked as filed; shown only inside the org.",
      "x-data-class": "operational"
    },
    "page": {
      "type": [
        "string",
        "null"
      ],
      "description": "The app page it was filed from.",
      "x-data-class": "operational"
    },
    "record": {
      "type": [
        "object",
        "null"
      ],
      "description": "The record the reporter was on, {kind, id}.",
      "x-data-class": "operational"
    },
    "reopened_from": {
      "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 fixed or answered report this one reports again as still broken.",
      "x-data-class": "operational"
    },
    "followers": {
      "anyOf": [
        {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        {
          "const": "•••",
          "description": "Masked by the caller's data policy."
        },
        {
          "type": "null",
          "description": "Denied by the caller's data policy."
        }
      ],
      "description": "Who follows it, [{user_id, name}], longest-standing first.",
      "x-data-class": "personal"
    },
    "timeline": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Every event, oldest first: {event_id, at, kind} and, by kind, from and to (status, window), text (note), from, user_id, name and text (reply), user_id and name (confirmed, followed, unfollowed), report_id and ticket (reopened).",
      "x-data-class": "operational"
    },
    "seen_through": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "The newest event the person asking has seen.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "report_id",
    "org_id",
    "ticket",
    "org_name",
    "title",
    "kind",
    "filed_via",
    "reporter",
    "reporter_email",
    "impact",
    "private",
    "reported_at",
    "status",
    "status_at",
    "window",
    "note",
    "release_note_url",
    "duplicate_of",
    "duplicate_status",
    "fixed_at",
    "days_to_fix",
    "last_event_at",
    "following",
    "unread",
    "text",
    "page",
    "record",
    "reopened_from",
    "followers",
    "timeline",
    "seen_through"
  ],
  "additionalProperties": false
}

Refusals

report_not_found · 422 · no report by that id in that org is one the caller may see: it does not exist, it is another org's, or it is private to its reporter

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 report; the box reaches it through the intent surface, which serves what MCP serves
Outbound: a read emits nothing

Events

None emitted.

confirm_report, follow_report, mark_report_seen, reopen_report, reply_to_report, unfollow_report