REST API: Reports, Decks & Exports — Operalta Help

Report generation, frozen reads, decks, and exports.

Report generation

-POST /api/reports/generate — queue async synthesis. Returns { jobId, reportId, status, streamUrl }.
-GET /api/reports/:id/stream — SSE: init, section_start, section_complete, complete, error.

Reports & frozen reads

-GET /api/reports?companyId=... — list reports.
-GET /api/reports/:id — frozen report content (does not fall back to live metrics).
-POST /api/reports/:id/send — record a send (recipient, period, version).

Reports & public links

-POST /api/reports/share — create or revoke a share token.
-GET /api/reports/public/:slug/:period/:version/:token — frozen public read.
-GET /api/reports/public/typed/:type/... — same with template-aware validation.

Decks

-GET /api/decks?companyId=... — list (snake_case rows).
-POST /api/decks — create. Returns { deck, progressUrl, streamUrl }.
-PATCH /api/decks/:id — update a slide.
-GET /api/decks/:id/progress — SSE generation events.

Decks & public links

-POST|DELETE /api/decks/:id/share — create or revoke a public deck link.
-GET /api/decks/public/:token — read a public deck without auth.

Exports & downloads

-POST /api/exports — generate from markdown, tables, metrics, or deck data.
-GET /api/exports / GET /api/exports/:id — list or read with a fresh downloadUrl.
-GET /api/exports/:id/preview — preview completed .xlsx exports as workbook sheets without downloading the file.
-PATCH /api/exports/:id — link an export to a room or update reviewStatus.
-GET|POST /api/exports/style — list stylists or style a deck/report/financial/artifact.
-Stylists: deck, report, financial, artifact-to-excel.

Spreadsheet sandbox runs

-POST /api/sandbox/runs with jobType: "office.generate" — queue a sandbox Office run for rich .xlsx creation or update.
-Create requests use metadata.officeGeneration with kind: "spreadsheet", mode: "create", and either simple data or a rich workbookPlan for sheets, formulas, styles, widths, merges, and validation checks.
-Update requests use mode: "update", a completed .xlsx sourceExportId, and explicit operations. Updates create a new generated export and do not mutate the source workbook.
-Scopes: sandbox.runs:write to create runs, sandbox.runs:read to poll runs, exports:read to read or preview completed exports, and exports:write to review/link exports.

{
  "jobType": "office.generate",
  "metadata": {
    "officeGeneration": {
      "kind": "spreadsheet",
      "mode": "create",
      "title": "Q3 Operating Model",
      "outputBasename": "q3-operating-model",
      "workbookPlan": {
        "sheets": [
          {
            "name": "Summary",
            "cells": [
              { "cell": "A1", "value": "Metric" },
              { "cell": "B1", "value": "Value" },
              { "cell": "B2", "formula": "=Inputs!B2*12" }
            ]
          }
        ],
        "validation": [
          { "sheet": "Summary", "cell": "B2", "expect": "number" }
        ]
      }
    }
  }
}