Sigma Reports

Sigma Reports (Code Representation via REST API)

Use this skill for Sigma reports, the fixed-page authoring surface exposed by /v2/reports. Reports are a private-beta resource. They share common element shapes with workbooks but have a different resource lifecycle and a different layout language.

Choose the correct resource

Use a report for invoices, statements, regulatory packets, printable forms, branded documents, and other outputs whose physical page size matters. Use sigma-workbooks for responsive dashboards, exploratory analysis, application workflows, containers, tabs, modals, drawers, or workbook navigation.

Never create a report by sending kind: report to a workbook endpoint. The resource families are separate:

• Reports: POST /v2/reports, GET /v2/reports/{reportId}?includeContents=true, PUT /v2/reports/{reportId}/contents
• Workbooks: POST /v2/workbooks, GET /v2/workbooks/{workbookId}?includeContents=true, PUT /v2/workbooks/{workbookId}/contents
• Conversion: /v2/workbooks/{workbookId}/convertToReport

Source of truth

Use the current compiled OpenAPI for endpoint envelopes and published shapes:

https://assets.sigmacomputing.com/openapi/public-rest-api/sigma-computing-public-rest-api.json

The report endpoints currently declare application/json only. Author JSON unless a live request proves another media type works. The schema is broader than the documented report contract, so a published element kind is not proof that reports can safely author it. Read reference/specification/support-matrix.md before selecting elements.

Live baseline, verified 2026-08-11: a JSON report with a warehouse-table source, text, KPI, combo-chart, bar-chart, grouped presentation table, data bars, a hidden dependency page, and header/footer panels passed a dryRun: true dry run, created successfully, survived GET readback, updated as a new document version, and exported as a one-page landscape PDF with populated data. The support matrix records which findings this proves and which schema-published features remain gated.

Shared-shape refresh, verified 2026-09-15 against the compiled OpenAPI and a non-persistent dryRun: true request: common element pointers now use {columnId: ...}, pivot shelves use {columnId: ...}, and seriesLineAreaStyle is a list of {columnId, style} objects. Text/KPI alignment uses directional values (left/center/right and top/center/bottom), not start/middle/end. The old pointer, map, and alignment forms returned HTTP 400 while the replacement forms verified valid:true. Report PUT also publishes optional documentVersion for optimistic concurrency.

When documentation, this skill, and a live verify/readback disagree, prefer the live result and preserve the evidence.

Prerequisites and safety

1. Authenticate with the sigma-api skill. Set SIGMA_BASE_URL and SIGMA_API_TOKEN.
2. Confirm reports are enabled for the organization and the caller has Create, edit, and publish reports permission. Updating also requires Can edit access to the report.
3. Treat every create as persistent. The current OpenAPI exposes no report DELETE endpoint. Do not create a probe report without explicit user approval and a named destination folder.
4. Treat PUT as full-contents replacement, and remember it's contents-only — name, folderId, or description sent alongside contents are silently ignored, not applied. Always GET, back up, compare, edit, validate, verify, PUT with the retrieved documentVersion, and read back.
5. A report GET can omit unsupported UI-authored features. Never assume a GET representation is lossless merely because the request succeeded.

Recommended workflow

Step 1: Discover identity, folder, and a reference report

curl -sf -H "Authorization: Bearer $SIGMA_API_TOKEN" \
  "$SIGMA_BASE_URL/v2/whoami" > /tmp/whoami.json

curl -sf -H "Authorization: Bearer $SIGMA_API_TOKEN" \
  "$SIGMA_BASE_URL/v2/reports?limit=50" > /tmp/reports.json

Use a recent reference report to obtain the current schemaVersion and study literal element shapes. Do not hardcode a schema version from an example.

Step 2: Load the relevant references

Always read:

• reference/specification/schema.md
• reference/specification/layout.md
• reference/specification/support-matrix.md
• reference/workflows/validate.md

Also read reference/workflows/crud.md before an API write and reference/workflows/convert.md before converting a workbook.

Common element internals, source formulas, and column shapes are published in the same OpenAPI union used by workbooks. If sigma-workbooks is installed, its table, chart, map, KPI, control, source, formula, and formatting references are useful shape recipes. Apply only kinds allowed by the report support matrix, and never copy workbook grid layout or workbook-only elements.

For shared shapes changed by the released code contract:

• use columnId, never id, in map channels and pivot rowsBy/columnsBy shelf entries;
• emit seriesLineAreaStyle and theme colorOverrides as lists, not ID/name-keyed maps;
• use verticalAlign: top|center|bottom;
• use KPI layout.anchor: left|center|right and layout.verticalAnchor: top|center|bottom;
• wrap page background URLs as backgroundImage: {source: {kind: url, url: ...}, style: ...};
• use settings.theme.{name,overrides}, not the removed contents-level themeName/themeOverrides.

Step 3: Draft a wrapped JSON representation

Start with reference/specification/example-minimal.json. The create and verify envelope is:

{
  "name": "Monthly Statement",
  "folderId": "<folder-id>",
  "contents": {
    "schemaVersion": 1,
    "kind": "report",
    "config": {"pageWidth": 816, "pageHeight": 1056, "margin": 48},
    "elements": [],
    "pages": [{"id": "page-1", "name": "Page 1"}],
    "layout": "<Page id=\"page-1\"></Page>"
  }
}

Rules:

• Keep literal elements in flat contents.elements.
• Keep pages and panels as metadata; never nest elements inside them.
• Put all placement in contents.layout XML.
• Place leaves with absolute x, y, width, and height pixel values.
• Use report panels only for header and footer regions.
• Do not emit workbook gridColumn, gridRow, container, tab, overlay, or sidebar syntax.

Step 4: Validate locally

ruby scripts/validate-spec.rb --mode create /tmp/report-spec.json

Fix every error. Warnings identify schema-only or unknown capabilities that need a live verification decision.

Step 5: Verify without persistence

Add "dryRun": true to the request body (contents is required when dryRun is true — a 400 results otherwise), then POST to the same create endpoint:

curl -sf -X POST \
  -H "Authorization: Bearer $SIGMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-binary @/tmp/report-spec-dry-run.json \
  "$SIGMA_BASE_URL/v2/reports" \
  > /tmp/report-verify.json

A valid spec returns either bare metadata (no valid key) or {"valid": true, "warnings": [...]}; an invalid one returns {"valid": false, "errors": [{"summary": ...}], "warnings": [...]}. Verification checks server-side representation and dependencies without creating a report. It does not prove the PDF layout is correct or that GET will round-trip every UI feature.

Step 6: Create only with explicit approval

After the user approves the persistent write and destination folder:

curl -sf -X POST \
  -H "Authorization: Bearer $SIGMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-binary @/tmp/report-spec.json \
  "$SIGMA_BASE_URL/v2/reports" \
  > /tmp/report-create.json

Save the submitted representation under a report-ID-specific path. Report the report URL, ID, and saved path.

Step 7: Read back and inspect output

Immediately GET the representation and compare normalized documents. Confirm that optional fields survived and that no element, panel, page, or setting was silently dropped. Then export the affected pages to PDF and inspect the actual page breaks, clipping, typography, header/footer repetition, and margins.

Do not claim parity from a successful POST or PUT alone.

Step 8: Update with a loss check

Follow reference/workflows/crud.md. The short version is:

1. GET and back up the current report representation (GET /v2/reports/{id}?includeContents=true).
2. Inventory report pages, controls, and elements through their resource APIs.
3. Stop if the inventory contains content absent from the GET representation.
4. Edit the complete contents.
5. Validate in --mode update and dry-run it with POST /v2/reports + dryRun: true, assembled from the current name/folder and edited contents.
6. PUT {"contents": {...}, "documentVersion": <version-from-GET>} to PUT /v2/reports/{id}/contents. The version is optional in OpenAPI but strongly recommended so a concurrent edit fails instead of being overwritten. Sending name/folderId/description here is silently ignored — this endpoint only ever touches contents.
7. GET again, compare, export, and inspect.

Reference index

Troubleshooting

Reports are private beta. Prefer explicit evidence and reversible local edits over speculative API writes.