The AI-ready envelope · Docs

Every report is one typed payload (protocol version 1.0), identical across platforms, designed so a developer or an AI agent can act on it without asking what happened.

Top-level shape

{
  "protocolVersion": "1.0",
  "reportId": "<uuid>",
  "submittedAt": "2026-06-15T12:00:00.000Z",
  "sdk": { name, version, platform, formFactor },
  "reporter": { title, description, user? },
  "captures": { screenshot, uiTree, focus, logs, network },
  "captureControl": { included[], excluded[], degradedReason? },
  "payload": { uiTree?, reactTree?, focus?, breadcrumbs?, annotations?, redactions?, extra?, reportTarget? },
  "context": { app, device, route? },
  "attachments": [ AttachmentRef, … ]
}

Fields

Field	What it is
`protocolVersion`	Schema version. Currently `"1.0"`.
`reportId`	Unique id for the report (UUID).
`submittedAt`	ISO-8601 timestamp of submission.
`sdk`	`name`, `version`, `platform` (web, ios, android, tvos, …) and `formFactor` (phone, tablet, desktop, tv).
`reporter`	The user’s `title` (≤ 50 chars) and `description` (≤ 600 chars), plus an optional `user` ({ id?, email?, displayName? }).
`captures`	Booleans recording which capture types were enabled for this report.
`captureControl`	What was actually `included` / `excluded`, and a `degradedReason` if a capture couldn’t run.
`payload`	The captured artifacts (see below).
`context`	App and device context, and the current `route`.
`attachments`	References to binary parts (screenshot, recording, …).

payload

uiTree — the native UI tree of the screen (see below).
reactTree — the React component tree, when applicable, for cross-tree component lookup.
focus — the focused component when the report was opened.
breadcrumbs — the action timeline leading up to the report: up to 128 kind-tagged entries (navigation, tap, console, network, lifecycle, error, custom) on one shared epoch-ms clock that also stamps the replay. See screen & navigation tracking.
logs / network — captured console and network entries. Deprecated: both are derived from breadcrumbs, which newer receivers should read instead.
annotations / redactions — the user’s drawings and any redacted regions.
extra — free-form string you attach (≤ 2000 chars).
reportTarget — up to two paths (uiTree and/or reactTree) marking the exact element the user tapped to identify.

UI tree

A UITree is a recursive snapshot of what was on screen:

{
  "root": UINode,
  "capturedAt": "<iso>",
  "rendererHint": "dom" | "rn-fabric" | "rn-paper" | "uikit" | "android",
  "truncated": false
}

// UINode
{
  "componentType": "<string>",
  "componentName": "CheckoutButton",
  "identifiers": { … },
  "rect": { x, y, width, height },
  "safeProps": { … },
  "children": [ UINode, … ],
  "sensitive": false,
  "nodeKind": "dom" | "view" | "compose"
}

Nodes marked sensitive have their descendants omitted — a privacy guarantee enforced by the SDK before the report leaves the device.

focus

{
  "path": [0, 3, 1],
  "componentPath": "App > CheckoutScreen > TextField",
  "source": "touch" | "mouse" | "keyboard" | "remote" | "programmatic",
  "cursor": { x, y }
}

attachments

Binary artifacts are referenced, not inlined. Each AttachmentRef carries:

{
  "partName": "screenshot",
  "kind": "screenshot" | "annotated-screenshot" | "video" | "audio" | "other",
  "contentType": "image/png",
  "byteLength": 84213,
  "sha256": "<hex>",
  "width": 1170, "height": 2532
}

On delivery, TraceItX injects a short-lived presigned url (and an expiresAt) for each attachment so your receiver can download the bytes directly. See webhooks.

The envelope is validated against a typed schema on ingest and is forward-compatible — unknown fields are preserved, so newer SDKs can add data without breaking your receiver.