> ## Documentation Index
> Fetch the complete documentation index at: https://chatobserver.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How can my assistant compose and assess a report?

> Stage native changes, compose and assess an immutable candidate, then commit the exact measured result.

Report assessment is available to eligible workspaces when enabled by Chatobserver. Approve **Reports: read** for report discovery and assessment. Approve **Data: read** separately when the report uses cached connector outputs. Current report grants, connection permissions and Data access still apply.

## Upload a supplied logo or image

With **Reports: write**, use `reports_upload_image` to ingest a user-supplied public HTTPS URL or canonical base64 image bytes. PNG, JPEG and WebP are supported, up to 1MB. The server validates public DNS and every redirect, checks the image's actual format and decodability, and stores the original bytes in the selected workspace.

For a URL, supply `request.version=1` and `request.source={"kind":"url","url":"https://example.com/logo.png"}`, plus a stable UUID `idempotencyKey`. For bytes, use `source.kind=base64`, `source.mimeType` and `source.data`. An optional `expectedSha256` pins the exact file. Preserve the same command and key after an uncertain response. Completed retries read the stored asset rather than fetching the URL again; conflicting commands or changed reserved bytes are rejected.

The result includes `assetId`, `filePath`, dimensions, format, byte size, alpha information and SHA-256. Bind an **image** element through `settings.assetId`, use contain fitting and preserve its aspect ratio. Do not put this ID in `settings.logoId`: workspace logos and uploaded report images are distinct resources. Upload before sealing the authoring change set. This tool returns metadata rather than image previews and does not change workspace branding, report content, Data, sharing or PDF state.

## Read the native design first

Use `reports_get_authoring_context` to confirm the selected workspace, accessible logo IDs and dimensions, approved fonts, current authoring availability and the versioned guide. Follow its logo cursor. Prefer an appropriate workspace logo, report label, consistent shared header and numbered footer across logical pages; keep cover and distinct-purpose exceptions explicit.

`reports_get` returns the native manifest and exact revision/hash, including page and element-set hashes. Report lists default to 50 and accept at most 100 reports per page. Read `reports_get_configuration` for the complete layout/print settings, theme, controls, parameters, semantic definitions, policy and composition intent. Read `reports_get_page` for each native page and every element's rich text, configuration, styles, bindings, interactions and freeform/responsive placements.

These reads preserve native fields in lossless JSON records. A response is bounded to 1 MiB and at most 100 records; large values span chunks of at most 65,536 characters. A large native page envelope sets `pageInRecords=true` and supplies its full value in page records. Group records by kind, ID and value hash, concatenate JSON chunks in index order, require every declared chunk and then parse and validate the complete value against its capability schema. Follow the cursor until exhausted. Cursors bind the actor, delegation, report revision/hash, selection and record-set identity. Changed content or independent metadata requires a fresh read. Content is never silently shortened.

Optional effective configuration uses the same outer-surface style resolver as the viewer and identifies element, theme and native-default origins. Its declared exclusions include inner-component inheritance, rich-text run overrides, resolved responsive geometry and measured bounds. This metadata is separate from rendered assessment evidence.

`reports_list_data_sources` returns independently authorized attachment/version definitions, catalogues and source/output identities. Blend inputs are checked recursively. Historical version records withhold newer current-output metadata. Definitions remain in the separate Data feature, and none of these reads executes or refreshes a query. Current Data consent, query/connection permissions, network policy and asset references are rechecked.

Use `reports_get_publication_state` to compare private document/current Data identities with existing shares. Missing artifacts, invalid manifests, legacy metadata, revoked/expired shares and different identities are explicit. Matching metadata does not validate the complete shared payload or rendering: `payloadIntegrity` remains `not_assessed`. This tool never creates or updates a share.

## Stage native report changes

Staged authoring requires separately approved **Reports: write**, current report edit permission and workspace authoring availability. Stages are private to the authorizing account or connection and leave the saved report unchanged.

1. Discover the native configuration schemas and read the exact saved revision/hash. Use `reports_create_change_set` with authoring version 2, native document version 4 and a UUID retry key.
2. Use `reports_append_changes` for typed native pages, elements, content, styles, controls, semantic definitions, attachments and composition intent. Both freeform and responsive use their own native contracts. Each batch carries its ID, next sequence and the last confirmed cumulative hash. Preserve the entire batch on an uncertain retry; its ID is the retry key.
3. Use `reports_get_change_set` to reconcile accepted sequence and receipts. References may be supplied across multiple batches, but must resolve before sealing.
4. Use `reports_seal_change_set` at the confirmed cumulative hash to validate and freeze the complete native graph. A seal is not a rendered assessment or a saved-report commit.
5. Use `reports_discard_change_set` at the confirmed hash to abandon an uncommitted stage. It does not delete the report or undo a completed commit.

Each streamed request is limited to 512 KiB and 256 operations. A stage is limited to 256 batches, 8192 operations and 32 MiB and expires after 24 hours. Creation and append reject changed retry payloads. Seal and discard are repeatable at the same cumulative hash. Access and consent are checked again on every command and private read. Revocation stops access to the candidate as well as future writes.

## Compose and commit the measured candidate

For a desktop shared report link, set `compositionIntent.deliveryTarget` to `desktop`. The composer then certifies every logical page in private/shared desktop contexts. `desktop_and_print` also requires native PDF evidence; omission preserves that broader requirement. Desktop certification makes no PDF claim. Keep the finite `qualityPolicy` requirements for the requested delivery target.

Native V4 shared reports open at 100% to preserve authored readable type. Responsive layouts reflow to the reading area; freeform canvases retain their geometry with scrolling. Explicit viewer zoom and fit choices remain available.

Use authoring-context workspace logo IDs through `settings.logoId`; uploaded report assets use a separate `assetId`. Date definitions use `date-range-control`, while other selectors use `report-control`. Core bar/line/area/combo charts use a `visualization_chart` view with dimension and measure field IDs, or a matching explicit visualization specification. Section titles follow the authored theme typography, including in recipient delivery.

Measured composition also requires **Reports: write** and current edit permission. Keep **Reports: read** consent to poll the shared canvas job tools. Prepare existing readable Data outputs independently before composing; report permissions do not grant connection access or query execution.

1. Use `reports_compose` with the sealed change-set identity, exact saved revision/hash, declared `fixed` or `responsive` mode, profile, locale and timezone. `compose` placement policy uses semantic relationships; `preserve` measures intentional existing placements. Preserve the request and UUID idempotency key after an uncertain response.
2. Poll `reports_get_canvas_job`. A successful composition returns an immutable plan ID, plan hash and candidate document hash. Cancellation fences late workers and leaves the saved report unchanged.
3. Use `reports_get_plan` to review required coverage, readiness and findings. Read placements by `pageId` and follow `placements.pageInfo.nextCursor`. Follow `findings.pageInfo.nextOffset` through every finding page and review each page's required advisory IDs. `currentInputsMatch` is informational; commit checks the inputs again.
4. Use `reports_commit_plan` with the exact plan hash, expected revision/document/dependency hashes and explicitly reviewed advisory IDs. Commit installs the assessed candidate in one transaction and returns its new revision and immutable receipt. A changed source, input or runtime requires a new composition; commit never rebases or adjusts layout.
5. Retry an uncertain commit with the identical plan, request and UUID key. The original receipt remains replayable after later report edits or temporary-plan cleanup. Publication remains a separate operation.

Composition requests stream at most 16 KiB; commit requests stream at most 32 MiB, including bounded advisory acknowledgments. Jobs have bounded rendering work, retries and retention. A stage or successful job alone is not evidence that every report dimension passed. Unverified coverage remains explicit.

## Find and assess the intended report

1. Use `reports_list` with the exact workspace name and report search. Follow `pageInfo.nextCursor` when there are more results.
2. Use `reports_get` for the report's current revision, document hash, native layout mode and page IDs. Confirm `assessmentSupport` is `saved_revision`. Unsupported native documents and frozen legacy bundles are explicit.
3. Read `reports_get_capabilities` for supported contexts, profiles and guidance. Use `reports_assess` with the discovered report ID, exact revision/hash, selected pages and contexts. Preserve one UUID idempotency key when retrying the same request.
4. Use `reports_get_canvas_job` until the job reaches a terminal state. A queued or running job is unfinished work. Use `reports_cancel_canvas_job` to stop derived work when appropriate.
5. Read `reports_get_assessment` after completion. Follow `findings.pageInfo.nextOffset` to read every finding.

An assessment distinguishes native structure, measured layout, design advice, Data readiness and publication identity. Complete required coverage is necessary: unsupported probes, unavailable fonts, missing outputs and unknown evidence are reported explicitly. Job completion and `safeToCommit` do not certify aesthetic quality or authorize a write.

## Freeform, responsive and delivery contexts

The native `fixed` mode is freeform. Responsive mode uses the report's native layout and breakpoints. Contexts state the layout mode, viewport, canvas width, delivery scale, locale and timezone. Use a locale listed by `reports_get_capabilities`; regional aliases produce an explicit coverage gap when native formatting cannot be matched. Start with the saved defaults; arbitrary viewer-state scenarios are unsupported in this assessment release. Use private, shared-projection or print contexts only where their probes report complete evidence. Assessment of an independently saved shared artifact is not supported yet.

Capability discovery lists `elementProbes` for every native kind, including required evidence and the conditions under which it can be measured. Native rendering support does not imply complete assessment coverage. Straight solid/double dividers, rectangular fills and solid borders can provide paint evidence; masked, rounded or other unsupported paint returns an explicit gap. Check the completed assessment for the exact report and contexts.

For supported single-sheet text layouts, physical print evidence checks the exact ordered styled text against its printed fill colors as well as text ownership and bounds. Mixed text colors do not require screenshots. Unsupported effects and multi-sheet geometry remain explicit gaps; logical text continuity alone does not certify physical print layout.

Use `reports_list_capabilities` to discover native configuration contracts by family or element kind. Follow its cursor through the complete index. Use `reports_get_capability_schema` with the returned schema ID to inspect exact nested properties, enums, ranges, defaults and nullability. The root `value` property contains the configuration contract. Preserve its `schemaHash` when planning changes; an index cursor is bound to the index hash and chosen filters. Entries currently report `authoringStatus: contract_only`: configuration discovery does not by itself grant staged writes or measured commits. These generic schemas contain no saved report content, connector rows or credentials.

Assessments consume existing, readable, pinned cached outputs. They never execute a query, refresh data, set a schedule, autosave, freeze a report or publish a share. Missing or stale outputs remain separate from layout findings. Data connections and reusable queries remain in the Data feature.

## Design guidance

Use `reports_create` with Reports write consent to create a private native empty draft in the declared freeform (`fixed`) or responsive mode. Choose an approved theme preset from `reports_get_authoring_context`, or supply a complete native theme. Initial page and print settings use their owning native schemas. Keep the same client report UUID, UUID retry key and original command after an uncertain response: an identical retry returns the original creation manifest even after later edits. Creation does not attach Data, execute providers, publish a report or certify layout. Continue through native change sets, measured composition and atomic commit.

The shared job tools are available with Reports read or write consent. Each job still requires its exact current family consent and report permission: read for assessment, write for composition. Preserve a UUID retry key when cancelling. Completion status is only progress; inspect the full assessment or plan before claiming success.

When planning a report, use the workspace logo where appropriate, the report label, a consistent header, and coherent footers with logical page numbers. Covers and distinct page purposes may have deliberate exceptions. Keep a small typography hierarchy, consistent margins and spacing, readable text, aligned related content, room for chart labels and table headings, and correct logo aspect ratios.

These tools discover and assess saved reports and, when separately enabled, stage, compose and commit native changes. Report publication through this connector remains unavailable. The assessor returns semantic evidence; it does not send screenshots or ask the assistant to nudge blocks. Composition is available only when its workspace feature and protected renderer are configured; these documentation contracts do not indicate activation in a particular workspace.

See [Reports API](/docs/api-reference/reports) for the HTTP contracts and [connector capabilities](/docs/mcp/capabilities) for other supported workflows.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.