DigitalStack Developers
Sign inGet API keys

Coming soon · Contract draft

Portfolio Reporting

Planned

A portfolio-reporting contract for rollups, saved reporting views, asynchronous exports, report snapshots, and threshold events with explicit metric definitions.

Reviewable specification — not callable

Documentation-first contract draft. The proposed additions on this page are not callable or available yet. Paths, payloads, scopes, names, and examples are intentionally concrete so customers can review the intended contract before and during implementation.

Canonical owner

Portfolio reporting, saved view, and export services

Contract posture

P2 · Documentation first · implementation follows approval

Contract metadata

Draft version

0.2 review draft

Review owner

Delivery/Execute + Developer Platform

Last reviewed

July 14, 2026

Target wave

Wave 2 · Portfolio intelligence

Contract dependencies

  • • Canonical domain service adapter
  • • Optimistic concurrency and idempotency policy
  • • Transactional event outbox

What this unlocks

Build executive dashboards

Read a stable domain model for portfolio reporting without depending on GUI routes or database shapes.

Export governed portfolio data

Create a reviewable proposal and apply only the bounded commands the canonical owner permits.

Subscribe to portfolio thresholds

React to durable lifecycle facts and connect external systems with explicit direction and provenance.

Lifecycle and invariants

Portfolio Reporting exposes a bounded lifecycle with explicit commands and named authority at every transition.

draftreviewapprovedpublishedsuperseded
FromToCommandAuthority
draftreviewReview Portfolio ReportingPortfolio reporting, saved view, and export services
reviewapprovedApprove Portfolio ReportingPortfolio reporting, saved view, and export services
approvedpublishedPublish Portfolio ReportingPortfolio reporting, saved view, and export services
publishedsupersededSupersede Portfolio ReportingPortfolio reporting, saved view, and export services

Lifecycle invariants

  • • Published report metrics use stable definitions.
  • • Rollups and exports are read-only projections over the projects the caller can access; they never mutate delivery truth.

Authority boundaries

The interfaces expose canonical capabilities; they do not become a second owner of domain rules or state.

DigitalStack owns

  • • Portfolio metric definitions
  • • Saved report and export lifecycle
  • • Threshold and snapshot history

Explicitly not building

  • • Unbounded analytics queries
  • • Reports mutating project truth
  • • Financial leakage through broad report scopes

Surface decisions

Deliberate additions, retained boundaries, and removals from the proposed external contract.

add

Portfolio Reporting REST, GraphQL, MCP, webhook, and connected-app surfaces

The capability should return to the live Capabilities section only when every advertised interface has a backed runtime contract.

keep

Portfolio Reporting as documentation-first until runtime parity exists

Partial runtime slices should not appear as a fully available customer capability.

remove

Claims that Portfolio Reporting is available before REST, GraphQL, MCP, and webhooks are implemented

The developer docs must not make customers infer support that does not exist yet.

add

Project/engagement-scoped filtering on every read and command

A workspace API key is not a licence to read every project. Access composes workspace membership with per-project visibility, so integrators receive exactly the engagements they are entitled to.

Interface plan

REST API

Planned

Versioned portfolio reporting resources, commands, idempotency, and operation status.

Read only

GraphQL

Planned

Composable, read-only portfolio reporting discovery through the canonical service.

Read only · no customer mutations

MCP / Agent API

Planned

Bounded read, draft, and confirmed apply tools with evidence and audit attribution.

Read only

Webhooks

Planned

Past-tense portfolio report lifecycle facts with minimal payloads.

Past-tense durable facts only

Connected Apps

Planned

Power BI / Tableau / warehouse plus consumer clients, with declared direction and authority.

Declared direction and field authority required

Cross-interface parity

Each surface delegates to the named canonical owner; a blank surface is an intentional denial of authority, not missing documentation.

CapabilityRESTGraphQLMCPWebhookCanonical owner
Primary readGET /portfolio/reportsportfolioReport(id: ID!): PortfolioReportget_portfolio_reporting—Portfolio reporting, saved view, and export services
Primary commandNot exposedNot exposedNot exposedportfolio_report.createdPortfolio reporting, saved view, and export services

Proposed scopes

Proposed scopes are not grantable yet.

portfolio-reporting:readplanned scope
Read governed portfolio rollups, saved report views, and generated exports. This is an advisory read surface — it exposes no write or operate scope.

Behavioral contract

Cross-cutting rules every implementation and interface must satisfy.

Project / engagement-scoped access

A project and its engagement are the same object here. Resources are scoped to the projects the principal can access: workspace membership plus project-level visibility — owners and admins see every project, other principals see only the projects they created, were role-assigned, or were added to as members. List endpoints return only visible projects’ resources; detail endpoints enforce that visibility before returning or changing anything.

Canonical delegation

Every interface delegates to Portfolio reporting, saved view, and export services; no resolver, gateway, worker, or connector reimplements domain rules.

Least-privilege principals

Scopes are evaluated with tenant, role, field-visibility, and principal-type constraints before data is read or changed.

Transactional facts

Webhook facts are emitted from the canonical commit path, versioned, minimal, and safe to redeliver.

Declared provider authority

Every Connected App declares direction, field authority, provenance, and conflict behavior before activation.

REST API

Proposed endpoints

Planned
GET/api/v1/portfolio/reports

List portfolio rollups

Return stable portfolio rollups aggregated over the projects the caller can access.

portfolio-reporting:read

Execution
Synchronous
GET/api/v1/portfolio/reports/{id}

Get a portfolio report

Return one saved report view with its metric definitions and current values.

portfolio-reporting:read

Execution
Synchronous
GET/api/v1/portfolio/reports/{id}/exports

List report exports

Return the generated, cost-bounded exports available for one report.

portfolio-reporting:read

Execution
Synchronous

List portfolio rollups

curl --request GET \
  --url "https://www.digitalstack360.com/api/v1/portfolio/reports" \
  --header "Authorization: Bearer $DSTACK_API_KEY"
Planned response
{
  "data": [
    {
      "id": "portfolio-reporting_123",
      "status": "available",
      "version": 1
    }
  ]
}

GraphQL

Proposed graph

Planned

Types

PortfolioReport
PortfolioReportConnection
PortfolioReportChangeProposal
Operation

Queries

portfolioReport(id: ID!): PortfolioReport
portfolioReportList(filter: PortfolioReportFilter, pagination: PaginationInput): PortfolioReportConnection!

No GraphQL mutations planned

Read only. Customer callers cannot create, edit, publish, or administer these DigitalStack-owned resources.
Planned GraphQL query
query PortfolioReportDetail($id: ID!) {
  portfolioReport(id: $id) {
    id
    status
    version
    updatedAt
    allowedActions { id label requiresConfirmation }
    source { kind externalId }
  }
}

MCP / Agent API

Proposed tools

Planned

Get Portfolio Reporting

get_portfolio_reporting
Planned

Read the authorized portfolio reporting state, provenance, and allowed actions.

Scope
portfolio-reporting:read
Input
Resource id or a bounded filter.
Output
Canonical detail with source provenance and allowed actions.
Write boundary
Read only.
Planned agent workflow
User: Explain the current portfolio reporting for a project I can access.

1. Call get_portfolio_reporting to read the authorized state, contributing evidence, and provenance.
2. Summarize the facts and their evidence for the user.

This is a read-only surface: there is no draft, apply, or command tool to call.

Webhooks

Proposed event catalog

Planned

Event types

portfolio_report.createdplanned event

A canonical PortfolioReport was created.

payload: portfolio_report_id, status, created_at

portfolio_report.updatedplanned event

Governed PortfolioReport fields changed.

payload: portfolio_report_id, changed_fields, version, occurred_at

portfolio_report.completedplanned event

The run command completed.

payload: portfolio_report_id, prior_status, status, occurred_at

Planned event example
{
  "event_id": "evt_01k4...",
  "type": "portfolio_report.completed",
  "event_version": 1,
  "occurred_at": "2026-07-16T14:22:04Z",
  "workspace_id": "ws_abc123",
  "resource": {
    "type": "portfolio_report",
    "id": "portfolio_report_123"
  },
  "actor": {
    "id": "user_123"
  },
  "payload": {
    "portfolio_report_id": "portfolio_report_123",
    "prior_status": "draft",
    "status": "completed"
  },
  "source": null
}

Connected Apps

Proposed connection roles

Planned

Claude / ChatGPT / IDE clients

Consumer application

Read, explain, and submit bounded portfolio reporting proposals through MCP.

Authority: Client access never implies domain approval or unrestricted mutation authority.

Power BI / Tableau / warehouse

Analytics sink

Consume governed report exports and threshold facts.

Authority: Read-only reporting; external tools cannot write operational truth.

Open contract decisions

Resolve before implementation approval

  • • Which aggregate filters are safe for synchronous REST versus asynchronous export operations?

Proof obligations

Must remain trueFailure indicator
Portfolio reporting, saved view, and export services remains the singular canonical owner.An interface or connector persists a second authoritative lifecycle state.
Draft and apply remain separate actions.An agent or integration silently converts inferred intent into a canonical mutation.
Every write is attributable, versioned, and idempotent.A retry duplicates work or stale state overwrites a newer human decision.
Connected App direction and field authority are explicit.Provider data silently becomes canonical or conflicts are resolved without policy.