Skip to main content
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 for the HTTP contracts and connector capabilities for other supported workflows.