{"openapi":"3.1.0","info":{"title":"Reporting Manager API","version":"0.1.0","description":"The reporting engine's service shell. Owns no commands and no journal of its own: its database holds local mirrors of the inventory, purchasing, fulfillment, and crm journal tables, fed by Postgres logical replication, so heavy analytical reads (and direct BI joins) land here and never on the operational primaries. The mirror tables carry row-level security keyed on `tenant_id`, so a direct BI connection is tenant-scoped by the database itself. Behind the mirrors an incremental fold builds the reporting star schema — dimension rows, fact rows with drill-through event ids, and daily balance snapshots — reusing the shared costing fold so ledger figures reconcile with accounting to the cent. On top of the star sits the public reporting surface: a report library of saved definitions (journalled as `reporting.report-saved`), execution by the reference interpreter with job-gated field visibility, and drill-through from any leaf cell back to the journal facts behind it. The home dashboard reads its analytics strip from the same star and keeps each person's dismissed cards as `reporting.widget-dismissed` facts. The operational readout (replica and fold health) rides alongside."},"paths":{"/model":{"get":{"tags":["model"],"operationId":"model.model","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"EntityGraph","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntityGraph"},"examples":{"contract":{"summary":"Trimmed to the two entities a units-by-SKU report walks; the full model lists every reportable entity.","value":{"entities":[{"name":"sku","label":"SKU","dimensions":[{"name":"sku","label":"SKU","type":"string","scopes":["stock:read","receiving:read","purchasing:read","products:read","reports:read","financials:read"]},{"name":"name","label":"Item name","type":"string","scopes":["stock:read","receiving:read","purchasing:read","products:read","reports:read","financials:read"]}],"measures":[]},{"name":"stockMovement","label":"Stock movement","dimensions":[{"name":"day","label":"Day","type":"date","scopes":["stock:read","receiving:read","purchasing:read","products:read","reports:read","financials:read"]},{"name":"currency","label":"Currency","type":"string","scopes":["stock:read","receiving:read","purchasing:read","products:read","reports:read","financials:read"]}],"measures":[{"name":"quantity","label":"Units moved","kind":"flow","aggregation":"sum","scopes":["stock:read","receiving:read","purchasing:read","products:read","reports:read","financials:read"]}]}],"edges":[{"name":"sku","from":"stockMovement","to":"sku","cardinality":"one"}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The entity graph as THIS caller may see it: the reportable entities with their labelled dimensions and measures (each measure carrying its kind, `flow` or `balance`, and its aggregation), and the declared edges between the entities that survived — filtered **server-side** to the fields the caller's jobs may reference, so a report builder driven by this answer can only offer what a save or a run would accept. This is the sanctioned introspection surface: pure declared data with no engine and no SQL behind it — the underlying engine's own metadata endpoints must never be proxied in its place. Requires the `analyse`, `account` or `admin` job.\n\nRequires `reports:read`.","x-mcp-tool":{"name":"reporting_describe_model","title":"Reporting: Describe model","toolset":"reporting","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["reports:read"],"x-example-source":{"origin":"contract"}}},"/reports":{"get":{"tags":["reports"],"operationId":"reports.list","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SavedReport"}},"examples":{"contract":{"summary":"reports.list","value":[{"reportId":"rpt_01a1586d-1d4c-7444-8444-444444444444","name":"Units by SKU, last 30 days","definition":{"entity":"stockMovement","hops":["sku"],"groupBy":[{"field":"sku"}],"measures":["quantity"],"period":{"_tag":"preset","preset":"30d"},"filters":[],"derived":[],"limit":100}}]}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"List the tenant's saved reports whose every referenced field the caller's jobs may see — a report built on ledger fields is simply absent for a caller without the `account` job, the same answer the run would give. Requires the `analyse`, `account` or `admin` job.\n\nRequires `reports:read`.","x-mcp-tool":{"name":"reporting_list_reports","title":"Reporting: List reports","toolset":"reporting","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["reports:read"],"x-example-source":{"origin":"contract"}},"post":{"tags":["reports"],"operationId":"reports.save","parameters":[],"security":[{"bearer":[]}],"responses":{"201":{"description":"SavedReport","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedReport_1"},"examples":{"contract":{"summary":"reports.save","value":{"reportId":"rpt_01a1586d-1d4c-7444-8444-444444444444","name":"Units moved by SKU","definition":{"entity":"stockMovement","hops":["sku"],"groupBy":[{"field":"sku"}],"measures":["quantity"],"period":{"_tag":"preset","preset":"30d"},"filters":[],"derived":[],"limit":100}}}}}}},"400":{"description":"ReportDefinitionRefused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportDefinitionRefusedEncoded"}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"ReportFieldsForbidden | TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ReportFieldsForbiddenEncoded"},{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Save a report into the tenant's library under a client-minted `rpt_` id. The definition is held against the entity graph with the caller's jobs before anything is written: a definition that does not hold is refused 400 `ReportDefinitionRefused` with merchant-readable refusals, and one naming a field the caller's jobs may not see is refused 403 `ReportFieldsForbidden`. Appends `reporting.report-saved`. Idempotent on `reportId`: a retry is acknowledged with the originally saved report before any validation and appends nothing. Requires the `analyse`, `account` or `admin` job.\n\nRequires `reports:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveReport"},"example":{"reportId":"rpt_01a1586d-1d4c-7444-8444-444444444444","name":"Units moved by SKU","definition":{"entity":"stockMovement","hops":["sku"],"groupBy":[{"field":"sku"}],"measures":["quantity"],"period":{"_tag":"preset","preset":"30d"}}}}},"required":true},"x-mcp-tool":{"name":"reporting_save_report","title":"Reporting: Save report","toolset":"reporting","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["reports:write"],"x-example-source":{"origin":"contract"}}},"/reports/{reportId}":{"put":{"tags":["reports"],"operationId":"reports.replace","parameters":[{"name":"reportId","in":"path","schema":{"$ref":"#/components/schemas/RptId"},"required":true,"example":"rpt_01a1586d-1d4c-7444-8444-444444444444"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"SavedReport","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavedReport"},"examples":{"contract":{"summary":"reports.replace","value":{"reportId":"rpt_01a1586d-1d4c-7444-8444-444444444444","name":"Units by SKU, last 30 days","definition":{"entity":"stockMovement","hops":["sku"],"groupBy":[{"field":"sku"}],"measures":["quantity"],"period":{"_tag":"preset","preset":"30d"},"filters":[],"derived":[],"limit":100}}}}}}},"400":{"description":"ReportDefinitionRefused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportDefinitionRefusedEncoded"}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"ReportFieldsForbidden | TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ReportFieldsForbiddenEncoded"},{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ReportNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Replace a saved report's name and definition wholesale, validated exactly as the save is (400 `ReportDefinitionRefused` / 403 `ReportFieldsForbidden`); 404 `ReportNotFound` when the id was never saved. Appends `reporting.report-saved` with the report as it reads afterwards. Idempotent by content: a retry saying what the library already says appends nothing. Requires the `analyse`, `account` or `admin` job.\n\nRequires `reports:write`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplaceReport"},"example":{"name":"Units by SKU, last 30 days","definition":{"entity":"stockMovement","hops":["sku"],"groupBy":[{"field":"sku"}],"measures":["quantity"],"period":{"_tag":"preset","preset":"30d"}}}}},"required":true},"x-mcp-tool":{"name":"reporting_replace_report","title":"Reporting: Replace report","toolset":"reporting","readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["reports:write"],"x-example-source":{"origin":"contract"}}},"/report-runs":{"post":{"tags":["runs"],"operationId":"runs.run","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"RunReportResult","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunReportResult"},"examples":{"contract":{"summary":"runs.run","value":{"result":{"groupBy":["sku"],"measures":["quantity"],"derived":[],"period":{"firstDay":"2026-09-21","lastDay":"2026-10-20"},"rows":[{"level":1,"key":["WIDGET-BLUE"],"measures":{"quantity":40},"derived":{},"present":true},{"level":1,"key":["WIDGET-RED"],"measures":{"quantity":30},"derived":{},"present":true},{"level":0,"key":[],"measures":{"quantity":70},"derived":{},"present":true}],"meta":{"leafRows":2,"emittedLeafRows":2,"truncated":false,"cells":4}},"asOf":[{"source":"inventory","tenants":1,"maxFoldedSequence":128,"lastRun":{"at":"2026-10-20T08:59:58.000Z","outcome":"folded","folded":3,"skipped":0,"durationMs":41}},{"source":"fulfillment","tenants":1,"maxFoldedSequence":77,"lastRun":{"at":"2026-10-20T08:59:58.000Z","outcome":"empty","folded":0,"skipped":0,"durationMs":6}}],"includesHistory":false}}}}}},"400":{"description":"ReportDefinitionRefused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportDefinitionRefusedEncoded"}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"ReportFieldsForbidden | TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ReportFieldsForbiddenEncoded"},{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ReportNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Execute a report — a saved one by `reportId`, or an inline `definition` validated exactly as a save is — with the reference interpreter over the reporting star schema, and answer the grouped result plus `asOf`, the fold's per-source watermarks at the moment of the read. The caller's jobs gate every referenced field at run time, so a saved report outlives a revoked grant only as a 403 `ReportFieldsForbidden`. Appends nothing: a run is a pure query over the derived read model — the facts behind every number were journalled by the services that own them, and the request row is acknowledged rather than committed. No idempotency key: nothing is written, and the same definition over the same read model answers the same. Requires the `analyse`, `account` or `admin` job.\n\nRequires `reports:read`.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunReport"},"example":{"reportId":"rpt_01a1586d-1d4c-7444-8444-444444444444"}}},"required":true},"x-mcp-tool":{"name":"reporting_run_report","title":"Reporting: Run report","toolset":"reporting","readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false},"x-required-scopes":["reports:read"],"x-example-source":{"origin":"contract"}}},"/report-runs/drill":{"get":{"tags":["runs"],"operationId":"runs.drill","parameters":[{"name":"reportId","in":"query","schema":{"$ref":"#/components/schemas/RptId"},"required":true,"example":"rpt_01a1586d-1d4c-7444-8444-444444444444"},{"name":"measure","in":"query","schema":{"type":"string"},"required":true,"example":"quantity"},{"name":"key","in":"query","schema":{"type":"string"},"required":true,"example":"[\"WIDGET-BLUE\"]"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"DrillResult","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrillResult"},"examples":{"contract":{"summary":"runs.drill","value":{"measure":"quantity","key":["WIDGET-BLUE"],"value":40,"rows":[{"entity":"stockMovement","id":"mov_01a13891-2a00-7d4e-ac17-9d606148e08b","eventIds":["evt_01a13891-2a00-7d4e-ac17-9d606148e08c"]}]}}}}}},"400":{"description":"ReportDefinitionRefused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportDefinitionRefusedEncoded"}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"ReportFieldsForbidden | TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ReportFieldsForbiddenEncoded"},{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"404":{"description":"ReportNotFound","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportNotFoundEncoded"}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The facts behind one leaf cell of a saved report: the distinct fact rows that summed into `measure` for the leaf group `key` (a JSON array with one value per grouping), each with its stable row id and the journal `evt_` ids it was folded from — the drill-through trail back to the exact facts. Read-only, gated by the same job visibility as the run. Requires the `analyse`, `account` or `admin` job.\n\nRequires `reports:read`.","x-mcp-tool":{"name":"reporting_drill_report","title":"Reporting: Drill report","toolset":"reporting","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["reports:read"],"x-example-source":{"origin":"contract"}}},"/dashboard":{"get":{"tags":["dashboard"],"operationId":"dashboard.layout","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"DashboardLayout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardLayout"},"examples":{"contract":{"summary":"dashboard.layout","value":{"userId":"usr_01a12e7b-6080-7a3c-a1fc-94dbc33aeadb","dismissed":["sales-trend"]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"DashboardNeedsPerson | TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/DashboardNeedsPersonEncoded"},{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The caller's own home dashboard as they left it: the cards they dismissed (`dismissed`, widget keys oldest first). A person who never dismissed anything reads an empty list. Every member reads their own layout and nobody else's — the user is the verified session's, never a parameter; a system session has no dashboard and is refused 403 `DashboardNeedsPerson`.\n\nRequires a signed-in session: the layout read is always the caller's own, keyed by the verified session user","x-mcp-withheld":"A person's own admin home-screen layout; an agent has no dashboard, and the figures behind it are reporting_get_analytics_summary.","x-requires":{"kind":"signed-in","reason":"the layout read is always the caller's own, keyed by the verified session user"},"x-example-source":{"origin":"contract"}}},"/dashboard/dismissals/{widget}":{"put":{"tags":["dashboard"],"operationId":"dashboard.dismiss","parameters":[{"name":"widget","in":"path","schema":{"$ref":"#/components/schemas/DashboardWidgetKey"},"required":true,"example":"sales-trend"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"DashboardLayout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardLayout"},"examples":{"contract":{"summary":"dashboard.dismiss","value":{"userId":"usr_01a12e7b-6080-7a3c-a1fc-94dbc33aeadb","dismissed":["sales-trend"]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"DashboardNeedsPerson | TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/DashboardNeedsPersonEncoded"},{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Dismiss one card from the caller's own dashboard. `widget` is the card's key: its kind (`sales-trend`, `top-mover`, `connect-channel`, `invite-team`) or its kind and subject (`top-mover:WIDGET-1`), so hiding today's top mover does not hide the next one. Appends `reporting.widget-dismissed` and answers the layout as it reads afterwards. Idempotent by state: a card is dismissed once, so dismissing one already dismissed appends nothing and answers the same layout.\n\nRequires a signed-in session: the dismissal is the caller's own, keyed by the verified session user","x-mcp-withheld":"Hiding a card on a person's own admin home screen is that person's click in the admin, not an agent's action.","x-requires":{"kind":"signed-in","reason":"the dismissal is the caller's own, keyed by the verified session user"},"x-example-source":{"origin":"contract"}}},"/dashboard/dismissals":{"delete":{"tags":["dashboard"],"operationId":"dashboard.restore","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"DashboardLayout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardLayout"},"examples":{"contract":{"summary":"dashboard.restore","value":{"userId":"usr_01a12e7b-6080-7a3c-a1fc-94dbc33aeadb","dismissed":[]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"DashboardNeedsPerson | TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/DashboardNeedsPersonEncoded"},{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Bring back every card the caller dismissed from their own dashboard. Appends `reporting.widgets-restored` naming the cards it brought back and answers the emptied layout. Idempotent by state: a layout with nothing dismissed has nothing to restore, so a repeat appends nothing.\n\nRequires a signed-in session: the restore is the caller's own, keyed by the verified session user","x-mcp-withheld":"Bringing back a person's hidden home-screen cards is that person's click in the admin, not an agent's action.","x-requires":{"kind":"signed-in","reason":"the restore is the caller's own, keyed by the verified session user"},"x-example-source":{"origin":"contract"}}},"/analytics/summary":{"get":{"tags":["analytics"],"operationId":"analytics.summary","parameters":[{"name":"period","in":"query","schema":{"anyOf":[{"$ref":"#/components/schemas/PeriodPreset"},{"type":"null"}]},"required":false,"example":"7d"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"AnalyticsSummary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsSummary"},"examples":{"contract":{"summary":"analytics.summary","value":{"period":{"firstDay":"2026-10-14","lastDay":"2026-10-20"},"comparePeriod":{"firstDay":"2026-10-07","lastDay":"2026-10-13"},"currency":"AUD","salesCents":{"current":296100,"previous":255600},"orders":{"current":24,"previous":21},"units":{"current":57,"previous":53},"averageOrderCents":{"current":12338,"previous":12171},"daily":[{"day":"2026-10-14","salesCents":48200,"orders":4,"units":9},{"day":"2026-10-15","salesCents":61500,"orders":5,"units":12},{"day":"2026-10-16","salesCents":0,"orders":0,"units":0},{"day":"2026-10-17","salesCents":35800,"orders":3,"units":7},{"day":"2026-10-18","salesCents":72900,"orders":6,"units":14},{"day":"2026-10-19","salesCents":54300,"orders":4,"units":10},{"day":"2026-10-20","salesCents":23400,"orders":2,"units":5}],"previousDaily":[{"day":"2026-10-07","salesCents":39100,"orders":3,"units":8},{"day":"2026-10-08","salesCents":44800,"orders":4,"units":9},{"day":"2026-10-09","salesCents":51200,"orders":4,"units":11},{"day":"2026-10-10","salesCents":0,"orders":0,"units":0},{"day":"2026-10-11","salesCents":28700,"orders":2,"units":6},{"day":"2026-10-12","salesCents":60300,"orders":5,"units":13},{"day":"2026-10-13","salesCents":31500,"orders":3,"units":6}],"movers":[{"sku":"WIDGET-BLUE","name":"Blue widget, 40mm","units":22,"previousUnits":14,"salesCents":54780,"daily":[3,5,0,2,6,4,2],"previousDaily":[2,2,3,0,1,4,2]}],"includesHistory":false,"unconvertedLines":0,"asOf":[{"source":"inventory","tenants":1,"maxFoldedSequence":128,"lastRun":{"at":"2026-10-20T08:59:58.000Z","outcome":"folded","folded":3,"skipped":0,"durationMs":41}},{"source":"fulfillment","tenants":1,"maxFoldedSequence":77,"lastRun":{"at":"2026-10-20T08:59:58.000Z","outcome":"empty","folded":0,"skipped":0,"durationMs":6}}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The dashboard's analytics strip over the last 7, 30 or 90 days (`period`, 30d by default) against the same length of time just before it: total sales (integer cents, net of discounts and of tax), orders placed, units sold and average order value, each as `current` and `previous`; the window day by day (every day present, for the sparklines) and the previous window likewise; and up to three `movers`, the SKUs whose units sold grew most. Read from the reporting star's order-line facts, so an order counts on the day it was placed, and `asOf` carries the fold's watermarks so a consumer can tell zero from not-yet-folded. A management view on either accounting basis, not the books: the general ledger recognises revenue at invoice or at payment.\n\nRequires `reports:read` or `financials:read`.","x-mcp-tool":{"name":"reporting_get_analytics_summary","title":"Reporting: Get analytics summary","toolset":"reporting","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["reports:read","financials:read"],"x-example-source":{"origin":"contract"}}},"/analytics/slow-movers":{"get":{"tags":["analytics"],"operationId":"analytics.slowMovers","parameters":[{"name":"days","in":"query","schema":{"anyOf":[{"type":"string"},{"type":"null"}]},"required":false,"example":"60"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"SlowMovers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SlowMovers"},"examples":{"contract":{"summary":"analytics.slowMovers","value":{"days":60,"since":"2026-08-21","skus":2,"items":[{"sku":"BRACKET-STEEL-L","name":"Steel L-bracket","onHand":120,"lastSoldDay":null},{"sku":"WIDGET-GREEN","name":"Green widget, 40mm","onHand":35,"lastSoldDay":"2026-07-30"}],"asOf":[{"source":"inventory","tenants":1,"maxFoldedSequence":128,"lastRun":{"at":"2026-10-20T08:59:58.000Z","outcome":"folded","folded":3,"skipped":0,"durationMs":41}},{"source":"fulfillment","tenants":1,"maxFoldedSequence":77,"lastRun":{"at":"2026-10-20T08:59:58.000Z","outcome":"empty","folded":0,"skipped":0,"durationMs":6}}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The stock sitting still: every SKU with units on hand (summed from the reporting star's stock movements) and no order placed for it in the last `days` days (60 by default, 7–365). `skus` counts them all; `items` lists up to 200 — never-sold first, then the longest unsold, then the most units — each with `onHand` and `lastSoldDay` (null when it never sold). Units only: the money tied up in them is accounting's `GET /valuation`. `asOf` carries the fold's watermarks.\n\nRequires `reports:read` or `financials:read`.","x-mcp-tool":{"name":"reporting_list_slow_movers","title":"Reporting: List slow movers","toolset":"reporting","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["reports:read","financials:read"],"x-example-source":{"origin":"contract"}}},"/analytics/margin":{"get":{"tags":["analytics"],"operationId":"analytics.margin","parameters":[{"name":"period","in":"query","schema":{"anyOf":[{"$ref":"#/components/schemas/PeriodPreset"},{"type":"null"}]},"required":false,"example":"7d"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"MarginSummary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarginSummary"},"examples":{"contract":{"summary":"analytics.margin","value":{"period":{"firstDay":"2026-10-14","lastDay":"2026-10-20"},"currency":"AUD","proceedsCents":296100,"costedProceedsCents":281400,"cogsCents":168200,"lines":31,"costedLines":29,"unconvertedLines":0,"marginPercent":40.2,"belowCost":[{"sku":"WIDGET-RED","name":"Red widget, 40mm","units":3,"proceedsCents":2970,"cogsCents":3540}],"asOf":[{"source":"inventory","tenants":1,"maxFoldedSequence":128,"lastRun":{"at":"2026-10-20T08:59:58.000Z","outcome":"folded","folded":3,"skipped":0,"durationMs":41}},{"source":"fulfillment","tenants":1,"maxFoldedSequence":77,"lastRun":{"at":"2026-10-20T08:59:58.000Z","outcome":"empty","folded":0,"skipped":0,"durationMs":6}}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The margin over the last 7, 30 or 90 days (`period`, 30d by default), read from the reporting star's order-line facts. A line's cost of goods is known once the dispatch that fixes it has been folded, so the margin is taken over the costed lines only (`costedProceedsCents` against `cogsCents`, `marginPercent` to one place, null with nothing costed) and `lines` / `costedLines` say how much of the window that covers; `proceedsCents` is every line's, net of discounts and of tax. `belowCost` names up to five SKUs whose costed sales came in under their cost, the biggest loss first.\n\nRequires `financials:read`.","x-mcp-tool":{"name":"reporting_get_margin","title":"Reporting: Get margin","toolset":"reporting","readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},"x-required-scopes":["financials:read"],"x-example-source":{"origin":"contract"}}},"/commissions/mine":{"get":{"tags":["commissions"],"operationId":"commissions.mine","parameters":[{"name":"from","in":"query","schema":{"$ref":"#/components/schemas/IsoDay"},"required":false,"example":"2026-10-01"},{"name":"to","in":"query","schema":{"$ref":"#/components/schemas/IsoDay"},"required":false,"example":"2026-10-31"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"MyCommission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MyCommissionEncoded"},"examples":{"contract":{"summary":"commissions.mine","value":{"repId":"usr_019e5a10-51b0-7a42-8c1d-0e9f3a6b2c71","from":"2026-10-01","to":"2026-10-31","earnedCents":720,"clawbackCents":-120,"commissionCents":600,"basisCents":12000,"lines":[{"day":"2026-10-12","orderId":"ord_01a158e0-8b90-7ca1-9db2-1b2c3d4e5f60","lineId":"lin_01a158e0-8b90-7ca1-9db2-2c3d4e5f6071","sku":"MUG-BLUE","kind":"earned","rateBps":500,"basisCents":14400,"commissionCents":720},{"day":"2026-10-20","orderId":"ord_01a158e0-8b90-7ca1-9db2-1b2c3d4e5f60","lineId":"lin_01a158e0-8b90-7ca1-9db2-2c3d4e5f6071","sku":"MUG-BLUE","kind":"clawback","rateBps":500,"basisCents":-2400,"commissionCents":-120}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The signed-in rep's own commission (`docs/commissions.md` › §5) over a window of days (`from`/`to`, inclusive; this month to date when omitted): what they earned, what refunds clawed back, the net owed and the commissionable revenue, all in the home currency, with every line behind it. Every rep's commission is the `commission` entity of the report library, for `commissions:read`.\n\nRequires a signed-in session: a rep reads only their own commission: the rows are the session's own user, never a parameter","x-mcp-withheld":"A rep's own commission is theirs to read in the admin; an agent reads every rep's through the report library's `commission` entity (`reporting_run_report`), which `commissions:read` opens.","x-requires":{"kind":"signed-in","reason":"a rep reads only their own commission: the rows are the session's own user, never a parameter"},"x-example-source":{"origin":"contract"}}},"/events":{"get":{"tags":["events"],"operationId":"events.list","parameters":[{"name":"since","in":"query","schema":{"type":"string"},"required":false,"example":"2"},{"name":"limit","in":"query","schema":{"type":"string"},"required":false,"example":"500"},{"name":"upTo","in":"query","schema":{"type":"string"},"required":false}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/reporting.report-savedEncoded"},{"$ref":"#/components/schemas/reporting.widget-dismissedEncoded"},{"$ref":"#/components/schemas/reporting.widgets-restoredEncoded"}]}},"examples":{"contract":{"summary":"events.list","value":[{"_tag":"reporting.report-saved","eventId":"evt_01a13d49-a900-7c3e-9ed6-6bd67d1d0ecf","txId":"tx_01a13d49-a900-7c3e-9ed6-6bd67d1d0ed0","tenantId":"org_01a1586e-f9f6-7a8b-9c7d-6e5f4a3b2c1d","sequence":2,"occurredAt":"2026-10-20T08:41:12.000Z","source":"reporting-manager","version":1,"actor":{"_tag":"user","id":"usr_01a12e7b-6080-7a3c-a1fc-94dbc33aeadb"},"correlationId":"req_01a13d49-a8f0-7a51-8e1d-4c2b9a7f3e61","payload":{"reportId":"rpt_01a1586d-1d4c-7444-8444-444444444444","name":"Units by SKU, last 30 days","definition":{"entity":"stockMovement","hops":["sku"],"groupBy":[{"field":"sku"}],"measures":["quantity"],"period":{"_tag":"preset","preset":"30d"},"filters":[],"derived":[],"limit":100}}}]}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Replay committed reporting events at-or-after `since` (a journal sequence number), oldest first. The journal holds the report library's changes (`reporting.report-saved`) and the dashboard cards people dismiss and restore (`reporting.widget-dismissed`, `reporting.widgets-restored`); the read model the reports run over is folded from other services' journals and never lands here. `limit` caps a page (default 500, capped at 5000); repeat with `since=<last sequence + 1>` until a short page. `upTo` (inclusive) ends the replay at a sequence instead of the journal's head — with `GET /events/head` it replays the journal as it stood at a moment. Appends nothing: a read of facts already journalled.\n\nRequires `reports:read`.","x-mcp-withheld":"The journal replay a consumer pages through to build its projection; agents read the projections the list and get tools serve, and the audit trail (`audit_trail`) for history.","x-required-scopes":["reports:read"],"x-example-source":{"origin":"contract"}}},"/events/head":{"get":{"tags":["events"],"operationId":"events.head","parameters":[{"name":"at","in":"query","schema":{"type":"string"},"required":true,"example":"2026-10-20T09:00:00.000Z"}],"security":[{"bearer":[]}],"responses":{"200":{"description":"Where a tenant's journal stood at a moment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JournalHead"},"examples":{"contract":{"summary":"events.head","value":{"at":"2026-10-20T09:00:00.000Z","sequence":2}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"The journal's position at a moment: the last `sequence` the database had recorded for this tenant at `at` (absent when it held nothing yet), by the database's own clock rather than the service's. Replaying with `upTo=<sequence>` then gives the journal exactly as it stood then; a set of heads taken at one `at` is a consistent cut across journals. Appends nothing: a read of facts already journalled.\n\nRequires `reports:read`.","x-mcp-withheld":"Where a journal stood at a moment, for a consumer cutting journals to replay them as of then; agents read history through the audit trail (`audit_trail`).","x-required-scopes":["reports:read"],"x-example-source":{"origin":"contract"}}},"/replica/status":{"get":{"tags":["replica"],"operationId":"replica.status","parameters":[],"security":[{"bearer":[]}],"responses":{"200":{"description":"ReportingStatusReport","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingStatusReport"},"examples":{"contract":{"summary":"replica.status","value":{"warnBytes":268435456,"slots":[{"source":"inventory","slot":"reporting_inventory_events_sub","active":true,"lagBytes":4096,"stalled":false},{"source":"fulfillment","slot":"reporting_fulfillment_events_sub","active":true,"lagBytes":0,"stalled":false}],"fold":[{"source":"inventory","tenants":1,"maxFoldedSequence":128,"lastRun":{"at":"2026-10-20T08:59:58.000Z","outcome":"folded","folded":3,"skipped":0,"durationMs":41}},{"source":"fulfillment","tenants":1,"maxFoldedSequence":77,"lastRun":{"at":"2026-10-20T08:59:58.000Z","outcome":"empty","folded":0,"skipped":0,"durationMs":6}}]}}}}}},"401":{"description":"Unauthorized | TokenAlreadyUsed","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/UnauthorizedEncoded"},{"$ref":"#/components/schemas/TokenAlreadyUsedEncoded"}]}}}},"402":{"description":"SubscriptionRequired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequiredEncoded"}}}},"403":{"description":"TenantRequired | ScopeRequired | PlatformAdminRequired","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/TenantRequiredEncoded"},{"$ref":"#/components/schemas/ScopeRequiredEncoded"},{"$ref":"#/components/schemas/PlatformAdminRequiredEncoded"}]}}}},"409":{"description":"MirroredFromSource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MirroredFromSourceEncoded"}}}},"503":{"description":"RequestLogUnavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestLogUnavailableEncoded"}}}}},"description":"Replication-slot health for reporting's read replica, one entry per configured source journal (inventory, purchasing, fulfillment, crm). Each entry reports the slot name, whether a walsender is attached (`active`), and `lagBytes` — the WAL the source database is retaining for this consumer, measured on the source as `pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)`. `stalled` is true when the slot is inactive, missing, unreachable, or lagging past `warnBytes` (`REPLICA_LAG_WARN_BYTES`, default 256 MiB). This matters because a stalled slot retains WAL on the *source* until its disk fills — check here (or the periodic `reporting.replica` log line) before that happens. `fold` reports the read-model fold behind the mirrors: one entry per source with the highest folded journal sequence across tenants (the fold's watermark), how many tenants have one, and what the most recent fold run did (`folded`/`empty`/`failed`, with row and skip counts) — plus a `derived` entry for the costing rebuild pass that keeps ledger facts and balance snapshots reconciled with accounting. Liveness is deliberately separate: `/healthz` stays 200 while this payload carries the warning. Empty `slots` means reporting is running without a replica (memory fallback). Requires the `account` or `admin` job. Break-glass for a permanently dead consumer: `SELECT pg_drop_replication_slot('<slot>')` on the source, then re-establish the subscription. Appends nothing: a read of facts already journalled.\n\nRequires `activity:read`.","x-mcp-withheld":"Replication lag between the journals and this service's read model: an operator's health signal, not merchant data.","x-required-scopes":["activity:read"],"x-example-source":{"origin":"contract"}}}},"components":{"schemas":{"ReportEntityName":{"type":"string","pattern":"^[a-z][a-zA-Z0-9]*$","description":"A camelCase field name, e.g. orderedAt"},"ReportFieldName":{"type":"string","pattern":"^[a-z][a-zA-Z0-9]*$","description":"A camelCase field name, e.g. orderedAt"},"ReportFieldType":{"type":"string","enum":["string","number","date","boolean"],"description":"The value shape of a dimension, which decides the filter ops it accepts"},"Scope":{"type":"string","enum":["products:read","products:write","catalogs:read","catalogs:write","stock:read","stock:write","receiving:read","receiving:write","allocations:read","allocations:write","locations:read","locations:write","orders:read","orders:write","shipping:read","shipping:write","payments:read","payments:write","purchasing:read","purchasing:write","customers:read","customers:write","companies:read","companies:write","privacy:read","privacy:write","financials:read","financials:write","books:read","books:write","margins:read","margins:write","reports:read","reports:write","imports:read","imports:write","integrations:read","integrations:write","setup:read","setup:write","billing:read","billing:write","activity:read","activity:write","settings:read","settings:write","notifications:read","notifications:write","saved-views:read","saved-views:write","commissions:read","commissions:write","catalog-override:read","catalog-override:write","printing:read","printing:write"],"description":"A permission an endpoint requires, `<resource>:<read|write>`; holding `write` implies `read`."},"DimensionDef":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/ReportFieldName"},"label":{"type":"string","minLength":1},"type":{"$ref":"#/components/schemas/ReportFieldType"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/Scope"},"minItems":1}},"required":["name","label","type","scopes"],"additionalProperties":false},"MeasureKind":{"type":"string","enum":["flow","balance"],"description":"How a measure relates to time: a `flow` is summed over the period; a `balance` is as-of a date, answered from the daily balance snapshots"},"MeasureDef":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/ReportFieldName"},"label":{"type":"string","minLength":1},"kind":{"$ref":"#/components/schemas/MeasureKind"},"aggregation":{"type":"string","enum":["sum"]},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/Scope"},"minItems":1}},"required":["name","label","kind","aggregation","scopes"],"additionalProperties":false},"EntityDef":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/ReportEntityName"},"label":{"type":"string","minLength":1},"dimensions":{"type":"array","items":{"$ref":"#/components/schemas/DimensionDef"}},"measures":{"type":"array","items":{"$ref":"#/components/schemas/MeasureDef"}}},"required":["name","label","dimensions","measures"],"additionalProperties":false},"EdgeCardinality":{"type":"string","enum":["one","many"],"description":"How many rows an edge reaches from one row: `one`, or `many` (walking it multiplies rows)"},"EdgeDef":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/ReportFieldName"},"from":{"$ref":"#/components/schemas/ReportEntityName"},"to":{"$ref":"#/components/schemas/ReportEntityName"},"cardinality":{"$ref":"#/components/schemas/EdgeCardinality"}},"required":["name","from","to","cardinality"],"additionalProperties":false},"EntityGraph":{"type":"object","properties":{"entities":{"type":"array","items":{"$ref":"#/components/schemas/EntityDef"}},"edges":{"type":"array","items":{"$ref":"#/components/schemas/EdgeDef"}}},"required":["entities","edges"],"additionalProperties":false},"UnauthorizedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["Unauthorized"]},"reason":{"type":"string"}},"required":["_tag","reason"],"additionalProperties":false},"TokenAlreadyUsedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["TokenAlreadyUsed"]},"tokenId":{"type":"string"}},"required":["_tag","tokenId"],"additionalProperties":false},"RequestLogUnavailableEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["RequestLogUnavailable"]},"tokenId":{"type":"string"},"reason":{"type":"string"}},"required":["_tag","tokenId","reason"],"additionalProperties":false},"TenantRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["TenantRequired"]},"userId":{"type":"string"}},"required":["_tag","userId"],"additionalProperties":false},"ScopeRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ScopeRequired"]},"required":{"type":"array","items":{"type":"string"}}},"required":["_tag","required"],"additionalProperties":false},"PlatformAdminRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["PlatformAdminRequired"]},"userId":{"type":"string"}},"required":["_tag","userId"],"additionalProperties":false},"SubscriptionRequiredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["SubscriptionRequired"]},"status":{"type":"string"}},"required":["_tag","status"],"additionalProperties":false},"MirroredFromSourceEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["MirroredFromSource"]},"source":{"type":"string"}},"required":["_tag","source"],"additionalProperties":false},"RptId":{"type":"string","pattern":"^rpt_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A rpt-prefixed uuid, e.g. rpt_9f8c1c2e-0000-4000-8000-000000000000"},"FieldRef":{"type":"string","pattern":"^[a-z][a-zA-Z0-9]*(\\.[a-z][a-zA-Z0-9]*)?$","description":"A field name, optionally entity-qualified: \"proceeds\" or \"order.proceeds\""},"ReportFilterOp":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["eq"]},"field":{"$ref":"#/components/schemas/FieldRef"},"value":{"anyOf":[{"type":"string"},{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}]}},"required":["_tag","field","value"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["neq"]},"field":{"$ref":"#/components/schemas/FieldRef"},"value":{"anyOf":[{"type":"string"},{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}]}},"required":["_tag","field","value"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["in"]},"field":{"$ref":"#/components/schemas/FieldRef"},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}]},"minItems":1}},"required":["_tag","field","values"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["contains"]},"field":{"$ref":"#/components/schemas/FieldRef"},"value":{"type":"string","minLength":1}},"required":["_tag","field","value"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["gte"]},"field":{"$ref":"#/components/schemas/FieldRef"},"value":{"anyOf":[{"type":"string"},{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}]}},"required":["_tag","field","value"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["lte"]},"field":{"$ref":"#/components/schemas/FieldRef"},"value":{"anyOf":[{"type":"string"},{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}]}},"required":["_tag","field","value"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["between"]},"field":{"$ref":"#/components/schemas/FieldRef"},"from":{"anyOf":[{"type":"string"},{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}]},"to":{"anyOf":[{"type":"string"},{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}]}},"required":["_tag","field","from","to"],"additionalProperties":false}]},"ReportFilter":{"type":"object","properties":{"at":{"type":"integer","minimum":0},"op":{"$ref":"#/components/schemas/ReportFilterOp"}},"required":["at","op"],"additionalProperties":false},"DateBucket":{"type":"string","enum":["day","week","month"],"description":"The calendar bucket a date dimension is grouped into: `day`, `week` or `month`"},"ReportGroupBy":{"type":"object","properties":{"field":{"$ref":"#/components/schemas/FieldRef"},"bucket":{"$ref":"#/components/schemas/DateBucket"}},"required":["field"],"additionalProperties":false},"DerivedFieldName":{"type":"string","pattern":"^[a-z][a-zA-Z0-9]*$"},"MeasureOperator":{"type":"string","enum":["add","subtract","multiply","divide"],"description":"The arithmetic a derived field applies to its two sides: `add`, `subtract`, `multiply` or `divide`"},"MeasureExpr":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["measure"]},"name":{"$ref":"#/components/schemas/FieldRef"}},"required":["_tag","name"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["const"]},"value":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["_tag","value"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"$ref":"#/components/schemas/MeasureOperator"},"left":{"$ref":"#/components/schemas/MeasureExpr"},"right":{"$ref":"#/components/schemas/MeasureExpr"}},"required":["_tag","left","right"],"additionalProperties":false}]},"DerivedField":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/DerivedFieldName"},"expr":{"$ref":"#/components/schemas/MeasureExpr"}},"required":["name","expr"],"additionalProperties":false},"PeriodPreset":{"type":"string","enum":["7d","30d","90d"],"description":"A preset report window: the last `7d`, `30d` or `90d` days"},"IsoDay":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"A calendar day, e.g. 2026-03-31"},"ReportPeriod":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["preset"]},"preset":{"$ref":"#/components/schemas/PeriodPreset"}},"required":["_tag","preset"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["custom"]},"from":{"$ref":"#/components/schemas/IsoDay"},"to":{"$ref":"#/components/schemas/IsoDay"}},"required":["_tag","from","to"],"additionalProperties":false}]},"ReportPeriod_1":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["preset"]},"preset":{"$ref":"#/components/schemas/PeriodPreset"}},"required":["_tag","preset"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["custom"]},"from":{"$ref":"#/components/schemas/IsoDay"},"to":{"$ref":"#/components/schemas/IsoDay"}},"required":["_tag","from","to"],"additionalProperties":false}]},"SortOrder":{"type":"string","enum":["asc","desc"],"description":"The direction a list is ordered in: `asc` (ascending) or `desc` (descending)"},"ReportSort":{"type":"object","properties":{"by":{"$ref":"#/components/schemas/FieldRef"},"order":{"$ref":"#/components/schemas/SortOrder"}},"required":["by","order"],"additionalProperties":false},"ReportDefinition":{"type":"object","properties":{"entity":{"type":"string","minLength":1},"hops":{"type":"array","items":{"type":"string","minLength":1},"maxItems":4},"filters":{"type":"array","items":{"$ref":"#/components/schemas/ReportFilter"}},"groupBy":{"type":"array","items":{"$ref":"#/components/schemas/ReportGroupBy"},"maxItems":4},"measures":{"type":"array","items":{"$ref":"#/components/schemas/FieldRef"},"minItems":1},"derived":{"type":"array","items":{"$ref":"#/components/schemas/DerivedField"}},"period":{"$ref":"#/components/schemas/ReportPeriod"},"compare":{"$ref":"#/components/schemas/ReportPeriod_1"},"sort":{"$ref":"#/components/schemas/ReportSort"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":1000}},"required":["entity","hops","measures","period"],"additionalProperties":false},"SavedReport":{"type":"object","properties":{"reportId":{"$ref":"#/components/schemas/RptId"},"name":{"type":"string","minLength":1},"definition":{"$ref":"#/components/schemas/ReportDefinition"}},"required":["reportId","name","definition"],"additionalProperties":false},"SaveReport":{"type":"object","properties":{"reportId":{"$ref":"#/components/schemas/RptId"},"name":{"type":"string","minLength":1,"maxLength":120},"definition":{"$ref":"#/components/schemas/ReportDefinition"}},"required":["reportId","name","definition"],"additionalProperties":false},"SavedReport_1":{"type":"object","properties":{"reportId":{"$ref":"#/components/schemas/RptId"},"name":{"type":"string","minLength":1},"definition":{"$ref":"#/components/schemas/ReportDefinition"}},"required":["reportId","name","definition"],"additionalProperties":false},"ReportRefusal":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},"ReportDefinitionRefusedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ReportDefinitionRefused"]},"refusals":{"type":"array","items":{"$ref":"#/components/schemas/ReportRefusal"}}},"required":["_tag","refusals"],"additionalProperties":false},"ReportFieldsForbiddenEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ReportFieldsForbidden"]},"refusals":{"type":"array","items":{"$ref":"#/components/schemas/ReportRefusal"}}},"required":["_tag","refusals"],"additionalProperties":false},"ReplaceReport":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"definition":{"$ref":"#/components/schemas/ReportDefinition"}},"required":["name","definition"],"additionalProperties":false},"ReportNotFoundEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["ReportNotFound"]},"reportId":{"type":"string"}},"required":["_tag","reportId"],"additionalProperties":false},"ReportFilterOp_1":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["eq"]},"field":{"$ref":"#/components/schemas/FieldRef"},"value":{"anyOf":[{"type":"string"},{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}]}},"required":["_tag","field","value"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["neq"]},"field":{"$ref":"#/components/schemas/FieldRef"},"value":{"anyOf":[{"type":"string"},{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}]}},"required":["_tag","field","value"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["in"]},"field":{"$ref":"#/components/schemas/FieldRef"},"values":{"type":"array","items":{"anyOf":[{"type":"string"},{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}]},"minItems":1}},"required":["_tag","field","values"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["contains"]},"field":{"$ref":"#/components/schemas/FieldRef"},"value":{"type":"string","minLength":1}},"required":["_tag","field","value"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["gte"]},"field":{"$ref":"#/components/schemas/FieldRef"},"value":{"anyOf":[{"type":"string"},{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}]}},"required":["_tag","field","value"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["lte"]},"field":{"$ref":"#/components/schemas/FieldRef"},"value":{"anyOf":[{"type":"string"},{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}]}},"required":["_tag","field","value"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["between"]},"field":{"$ref":"#/components/schemas/FieldRef"},"from":{"anyOf":[{"type":"string"},{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}]},"to":{"anyOf":[{"type":"string"},{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}]}},"required":["_tag","field","from","to"],"additionalProperties":false}]},"ReportFilter_1":{"type":"object","properties":{"at":{"type":"integer","minimum":0},"op":{"$ref":"#/components/schemas/ReportFilterOp_1"}},"required":["at","op"],"additionalProperties":false},"DateBucket_1":{"type":"string","enum":["day","week","month"],"description":"The calendar bucket a date dimension is grouped into: `day`, `week` or `month`"},"ReportGroupBy_1":{"type":"object","properties":{"field":{"$ref":"#/components/schemas/FieldRef"},"bucket":{"$ref":"#/components/schemas/DateBucket_1"}},"required":["field"],"additionalProperties":false},"MeasureExpr_1":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["measure"]},"name":{"$ref":"#/components/schemas/FieldRef"}},"required":["_tag","name"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["const"]},"value":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["_tag","value"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"$ref":"#/components/schemas/MeasureOperator"},"left":{"$ref":"#/components/schemas/MeasureExpr_1"},"right":{"$ref":"#/components/schemas/MeasureExpr_1"}},"required":["_tag","left","right"],"additionalProperties":false}]},"ReportPeriod_2":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["preset"]},"preset":{"$ref":"#/components/schemas/PeriodPreset"}},"required":["_tag","preset"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["custom"]},"from":{"$ref":"#/components/schemas/IsoDay"},"to":{"$ref":"#/components/schemas/IsoDay"}},"required":["_tag","from","to"],"additionalProperties":false}]},"ReportSort_1":{"type":"object","properties":{"by":{"$ref":"#/components/schemas/FieldRef"},"order":{"$ref":"#/components/schemas/SortOrder"}},"required":["by","order"],"additionalProperties":false},"RunReport":{"type":"object","properties":{"reportId":{"$ref":"#/components/schemas/RptId"},"definition":{"type":"object","properties":{"entity":{"type":"string","minLength":1},"hops":{"type":"array","items":{"type":"string","minLength":1},"maxItems":4},"filters":{"type":"array","items":{"$ref":"#/components/schemas/ReportFilter_1"}},"groupBy":{"type":"array","items":{"$ref":"#/components/schemas/ReportGroupBy_1"},"maxItems":4},"measures":{"type":"array","items":{"$ref":"#/components/schemas/FieldRef"},"minItems":1},"derived":{"type":"array","items":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/DerivedFieldName"},"expr":{"$ref":"#/components/schemas/MeasureExpr_1"}},"required":["name","expr"],"additionalProperties":false}},"period":{"$ref":"#/components/schemas/ReportPeriod_1"},"compare":{"$ref":"#/components/schemas/ReportPeriod_2"},"sort":{"$ref":"#/components/schemas/ReportSort_1"},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":1000}},"required":["entity","hops","measures","period"],"additionalProperties":false}},"additionalProperties":false},"ReportWindow":{"type":"object","properties":{"firstDay":{"$ref":"#/components/schemas/IsoDay"},"lastDay":{"$ref":"#/components/schemas/IsoDay"}},"required":["firstDay","lastDay"],"additionalProperties":false},"ReportCellValue":{"anyOf":[{"type":"string"},{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},{"type":"boolean"},{"type":"null"}]},"ReportResultRow":{"type":"object","properties":{"level":{"type":"integer","minimum":0},"key":{"type":"array","items":{"$ref":"#/components/schemas/ReportCellValue"}},"measures":{"type":"object","additionalProperties":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"derived":{"type":"object","additionalProperties":{"anyOf":[{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},{"type":"null"}]}},"present":{"type":"boolean"},"compare":{"type":"object","properties":{"measures":{"type":"object","additionalProperties":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"derived":{"type":"object","additionalProperties":{"anyOf":[{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},{"type":"null"}]}},"present":{"type":"boolean"}},"required":["measures","derived","present"],"additionalProperties":false}},"required":["level","key","measures","derived","present"],"additionalProperties":false},"ReportResult":{"type":"object","properties":{"groupBy":{"type":"array","items":{"type":"string"}},"measures":{"type":"array","items":{"type":"string"}},"derived":{"type":"array","items":{"type":"string"}},"period":{"$ref":"#/components/schemas/ReportWindow"},"comparePeriod":{"$ref":"#/components/schemas/ReportWindow"},"rows":{"type":"array","items":{"$ref":"#/components/schemas/ReportResultRow"}},"meta":{"type":"object","properties":{"leafRows":{"type":"integer"},"emittedLeafRows":{"type":"integer"},"truncated":{"type":"boolean"},"cells":{"type":"integer"}},"required":["leafRows","emittedLeafRows","truncated","cells"],"additionalProperties":false}},"required":["groupBy","measures","derived","period","rows","meta"],"additionalProperties":false},"FoldRunOutcome":{"type":"string","enum":["folded","empty","failed"],"description":"What a fold run did: `folded` — rows were applied; `empty` — nothing was above the watermark; `failed` — an error"},"FoldRunSummary":{"type":"object","properties":{"at":{"type":"string"},"outcome":{"$ref":"#/components/schemas/FoldRunOutcome"},"folded":{"type":"integer"},"skipped":{"type":"integer"},"durationMs":{"type":"integer"}},"required":["at","outcome","folded","skipped","durationMs"],"additionalProperties":false},"FoldSourceStatus":{"type":"object","properties":{"source":{"type":"string"},"tenants":{"type":"integer"},"maxFoldedSequence":{"anyOf":[{"type":"integer"},{"type":"null"}]},"lastRun":{"$ref":"#/components/schemas/FoldRunSummary"}},"required":["source","tenants","maxFoldedSequence"],"additionalProperties":false},"RunReportResult":{"type":"object","properties":{"result":{"$ref":"#/components/schemas/ReportResult"},"asOf":{"type":"array","items":{"$ref":"#/components/schemas/FoldSourceStatus"}},"includesHistory":{"type":"boolean"}},"required":["result","asOf","includesHistory"],"additionalProperties":false},"DrillRow":{"type":"object","properties":{"entity":{"type":"string"},"id":{"type":"string"},"eventIds":{"type":"array","items":{"type":"string"}}},"required":["entity","id","eventIds"],"additionalProperties":false},"DrillResult":{"type":"object","properties":{"measure":{"type":"string"},"key":{"type":"array","items":{"anyOf":[{"type":"string"},{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},{"type":"boolean"},{"type":"null"}]}},"value":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"rows":{"type":"array","items":{"$ref":"#/components/schemas/DrillRow"}}},"required":["measure","key","value","rows"],"additionalProperties":false},"UsrId":{"type":"string","pattern":"^usr_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A usr-prefixed uuid, e.g. usr_9f8c1c2e-0000-4000-8000-000000000000"},"DashboardWidgetKey":{"type":"string","maxLength":160},"DashboardLayout":{"type":"object","properties":{"userId":{"$ref":"#/components/schemas/UsrId"},"dismissed":{"type":"array","items":{"$ref":"#/components/schemas/DashboardWidgetKey"}}},"required":["userId","dismissed"],"additionalProperties":false},"DashboardNeedsPersonEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["DashboardNeedsPerson"]},"userId":{"type":"string"}},"required":["_tag","userId"],"additionalProperties":false},"AnalyticsWindow":{"type":"object","properties":{"firstDay":{"$ref":"#/components/schemas/IsoDay"},"lastDay":{"$ref":"#/components/schemas/IsoDay"}},"required":["firstDay","lastDay"],"additionalProperties":false},"CurrencyCode":{"type":"string"},"AnalyticsFigure":{"type":"object","properties":{"current":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"previous":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]}},"required":["current","previous"],"additionalProperties":false},"AnalyticsDay":{"type":"object","properties":{"day":{"$ref":"#/components/schemas/IsoDay"},"salesCents":{"type":"integer"},"orders":{"type":"integer"},"units":{"type":"integer"}},"required":["day","salesCents","orders","units"],"additionalProperties":false},"AnalyticsMover":{"type":"object","properties":{"sku":{"type":"string"},"name":{"type":"string"},"units":{"type":"integer"},"previousUnits":{"type":"integer"},"salesCents":{"type":"integer"},"daily":{"type":"array","items":{"type":"integer"}},"previousDaily":{"type":"array","items":{"type":"integer"}}},"required":["sku","name","units","previousUnits","salesCents","daily","previousDaily"],"additionalProperties":false},"AnalyticsSummary":{"type":"object","properties":{"period":{"$ref":"#/components/schemas/AnalyticsWindow"},"comparePeriod":{"$ref":"#/components/schemas/AnalyticsWindow"},"currency":{"anyOf":[{"$ref":"#/components/schemas/CurrencyCode"},{"type":"null"}]},"salesCents":{"$ref":"#/components/schemas/AnalyticsFigure"},"orders":{"$ref":"#/components/schemas/AnalyticsFigure"},"units":{"$ref":"#/components/schemas/AnalyticsFigure"},"averageOrderCents":{"$ref":"#/components/schemas/AnalyticsFigure"},"daily":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsDay"}},"previousDaily":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsDay"}},"movers":{"type":"array","items":{"$ref":"#/components/schemas/AnalyticsMover"}},"includesHistory":{"type":"boolean"},"unconvertedLines":{"type":"integer"},"asOf":{"type":"array","items":{"$ref":"#/components/schemas/FoldSourceStatus"}}},"required":["period","comparePeriod","currency","salesCents","orders","units","averageOrderCents","daily","previousDaily","movers","includesHistory","unconvertedLines","asOf"],"additionalProperties":false},"SlowMover":{"type":"object","properties":{"sku":{"type":"string"},"name":{"type":"string"},"onHand":{"type":"integer"},"lastSoldDay":{"anyOf":[{"$ref":"#/components/schemas/IsoDay"},{"type":"null"}]}},"required":["sku","name","onHand","lastSoldDay"],"additionalProperties":false},"SlowMovers":{"type":"object","properties":{"days":{"type":"integer"},"since":{"$ref":"#/components/schemas/IsoDay"},"skus":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/SlowMover"}},"asOf":{"type":"array","items":{"$ref":"#/components/schemas/FoldSourceStatus"}}},"required":["days","since","skus","items","asOf"],"additionalProperties":false},"BelowCostSku":{"type":"object","properties":{"sku":{"type":"string"},"name":{"type":"string"},"units":{"type":"integer"},"proceedsCents":{"type":"integer"},"cogsCents":{"type":"integer"}},"required":["sku","name","units","proceedsCents","cogsCents"],"additionalProperties":false},"MarginSummary":{"type":"object","properties":{"period":{"$ref":"#/components/schemas/AnalyticsWindow"},"currency":{"anyOf":[{"$ref":"#/components/schemas/CurrencyCode"},{"type":"null"}]},"proceedsCents":{"type":"integer"},"costedProceedsCents":{"type":"integer"},"cogsCents":{"type":"integer"},"lines":{"type":"integer"},"costedLines":{"type":"integer"},"unconvertedLines":{"type":"integer"},"marginPercent":{"anyOf":[{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},{"type":"null"}]},"belowCost":{"type":"array","items":{"$ref":"#/components/schemas/BelowCostSku"}},"asOf":{"type":"array","items":{"$ref":"#/components/schemas/FoldSourceStatus"}}},"required":["period","currency","proceedsCents","costedProceedsCents","cogsCents","lines","costedLines","unconvertedLines","marginPercent","belowCost","asOf"],"additionalProperties":false},"Cents":{"type":"integer","description":"A signed amount in integer cents"},"OrdId":{"type":"string","pattern":"^ord_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A ord-prefixed uuid, e.g. ord_9f8c1c2e-0000-4000-8000-000000000000"},"CommissionKind":{"type":"string","enum":["earned","clawback"],"description":"A commission row's kind: `earned` (invoiced, shipped or paid, by the order's setting) or `clawback` (a refund taking it back)"},"MyCommissionLine":{"type":"object","properties":{"day":{"$ref":"#/components/schemas/IsoDay"},"orderId":{"$ref":"#/components/schemas/OrdId"},"lineId":{"type":"string","minLength":1},"sku":{"type":"string","minLength":1},"kind":{"$ref":"#/components/schemas/CommissionKind"},"rateBps":{"type":"integer"},"basisCents":{"$ref":"#/components/schemas/Cents"},"commissionCents":{"$ref":"#/components/schemas/Cents"}},"required":["day","orderId","lineId","sku","kind","rateBps"],"additionalProperties":false},"MyCommissionEncoded":{"type":"object","properties":{"repId":{"type":"string"},"from":{"$ref":"#/components/schemas/IsoDay"},"to":{"$ref":"#/components/schemas/IsoDay"},"earnedCents":{"$ref":"#/components/schemas/Cents"},"clawbackCents":{"$ref":"#/components/schemas/Cents"},"commissionCents":{"$ref":"#/components/schemas/Cents"},"basisCents":{"$ref":"#/components/schemas/Cents"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/MyCommissionLine"}}},"required":["repId","from","to","earnedCents","clawbackCents","commissionCents","basisCents","lines"],"additionalProperties":false},"EvtId":{"type":"string","pattern":"^evt_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A evt-prefixed uuid, e.g. evt_9f8c1c2e-0000-4000-8000-000000000000"},"TxId":{"type":"string","pattern":"^tx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A tx-prefixed uuid, e.g. tx_9f8c1c2e-0000-4000-8000-000000000000"},"TenantId":{"type":"string","pattern":"^org_(test_)?[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"An org-prefixed uuid, e.g. org_9f8c1c2e-0000-4000-8000-000000000000; a sandbox tenant is org_test_<uuid>"},"AppId":{"type":"string","pattern":"^app_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A app-prefixed uuid, e.g. app_9f8c1c2e-0000-4000-8000-000000000000"},"InsId":{"type":"string","pattern":"^ins_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A ins-prefixed uuid, e.g. ins_9f8c1c2e-0000-4000-8000-000000000000"},"CplId":{"type":"string","pattern":"^cpl_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","description":"A cpl-prefixed uuid, e.g. cpl_9f8c1c2e-0000-4000-8000-000000000000"},"Actor":{"anyOf":[{"type":"object","properties":{"_tag":{"type":"string","enum":["user"]},"id":{"$ref":"#/components/schemas/UsrId"},"impersonatedBy":{"type":"string","minLength":1},"viaPartner":{"type":"string","minLength":1}},"required":["_tag","id"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["system"]},"id":{"type":"string","minLength":1}},"required":["_tag","id"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["app"]},"id":{"$ref":"#/components/schemas/AppId"},"installationId":{"$ref":"#/components/schemas/InsId"}},"required":["_tag","id","installationId"],"additionalProperties":false},{"type":"object","properties":{"_tag":{"type":"string","enum":["customer"]},"id":{"$ref":"#/components/schemas/CplId"}},"required":["_tag","id"],"additionalProperties":false}]},"reporting.report-savedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["reporting.report-saved"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"reportId":{"$ref":"#/components/schemas/RptId"},"name":{"type":"string","minLength":1},"definition":{"$ref":"#/components/schemas/ReportDefinition"}},"required":["reportId","name","definition"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"reporting.widget-dismissedEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["reporting.widget-dismissed"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"userId":{"$ref":"#/components/schemas/UsrId"},"widget":{"$ref":"#/components/schemas/DashboardWidgetKey"}},"required":["userId","widget"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"reporting.widgets-restoredEncoded":{"type":"object","properties":{"_tag":{"type":"string","enum":["reporting.widgets-restored"]},"eventId":{"$ref":"#/components/schemas/EvtId"},"txId":{"$ref":"#/components/schemas/TxId"},"tenantId":{"$ref":"#/components/schemas/TenantId"},"sequence":{"type":"integer","minimum":0},"occurredAt":{"type":"string"},"source":{"type":"string","minLength":1},"version":{"type":"number","enum":[1]},"actor":{"$ref":"#/components/schemas/Actor"},"correlationId":{"type":"string","minLength":1},"causationId":{"type":"string","minLength":1},"payload":{"type":"object","properties":{"userId":{"$ref":"#/components/schemas/UsrId"},"widgets":{"type":"array","items":{"$ref":"#/components/schemas/DashboardWidgetKey"}}},"required":["userId","widgets"],"additionalProperties":false}},"required":["_tag","eventId","txId","tenantId","sequence","occurredAt","source","version","actor","correlationId","payload"],"additionalProperties":false},"JournalHead":{"type":"object","properties":{"at":{"type":"string"},"sequence":{"type":"integer","minimum":0}},"required":["at"],"additionalProperties":false,"description":"Where a tenant's journal stood at a moment."},"ReplicaSlotStatus":{"type":"object","properties":{"source":{"type":"string"},"slot":{"type":"string"},"active":{"type":"boolean"},"lagBytes":{"anyOf":[{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},{"type":"null"}]},"stalled":{"type":"boolean"},"reason":{"type":"string"}},"required":["source","slot","active","lagBytes","stalled"],"additionalProperties":false},"ReportingStatusReport":{"type":"object","properties":{"warnBytes":{"anyOf":[{"type":"number"},{"type":"string","enum":["Infinity","-Infinity","NaN"]}]},"slots":{"type":"array","items":{"$ref":"#/components/schemas/ReplicaSlotStatus"}},"fold":{"type":"array","items":{"$ref":"#/components/schemas/FoldSourceStatus"}}},"required":["warnBytes","slots","fold"],"additionalProperties":false}},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"A tenant JWT: sign in through the auth service, choose the organization, then `GET /api/auth/token`. Tokens last 15 minutes."}}},"security":[],"tags":[{"name":"model","description":"Introspection: what can be reported on, filtered to the caller's jobs."},{"name":"reports","description":"The tenant's report library: definitions saved as journalled documents."},{"name":"runs","description":"Report execution: run a definition, and drill a cell back to its facts."},{"name":"dashboard","description":"The home dashboard: each person's own choice of the cards they see."},{"name":"analytics","description":"Store analytics: sales, orders and units over a window, against the one before."},{"name":"commissions","description":"A rep's own commission, earned and clawed back."},{"name":"events","description":"The reporting append-only event log."},{"name":"replica","description":"Operational visibility into the logical-replication read replica."}],"servers":[{"url":"https://reporting.getmanifold.io","description":"Production"}]}