# Reports

Query engine, dashboard CRUD, card CRUD, and funnel configuration for the workspace reporting system. Dashboards support per-record visibility (all_users or restricted) with ACL-based access grants.

**Base URL:** `https://api.trustpager.com/functions/v1/api/v1`

## Endpoints

### POST /reports/query

Run a report query. Returns aggregated rows for charts, or individual rows for drilldowns. Sources: "deals" (pipeline performance, revenue, win/loss) and "tasks" (open/overdue/by-assignee). In drilldown mode, the dimensions[] array controls which columns are returned and in what order (up to 8 columns via display_config.columns on a saved card).

**Scopes:** `opportunities:read` — [full detail](./reports/post-reports-query.md)

### GET /reports/sources

List available data sources ("deals", "tasks") with supported measures, dimensions, and filter fields. Dimensions with virtual:true are computed in JS post-fetch -- they cannot be used in filters or order_by, only in dimensions[] for display column selection.

**Scopes:** `opportunities:read` — [full detail](./reports/get-reports-sources.md)

### GET /reports/templates

List available dashboard templates: sales_overview, staff_accountability, pipeline_health, marketing_roi.

**Scopes:** `opportunities:read` — [full detail](./reports/get-reports-templates.md)

### POST /report-dashboards

Create a report dashboard. Supports template expansion with optional pipeline_id scoping. Set visibility to "restricted" then use POST /report-dashboards/:id/acl to grant per-user/role access.

**Scopes:** `opportunities:read` — [full detail](./reports/post-report-dashboards.md)

### GET /report-dashboards

List all report dashboards for the company.

**Scopes:** `opportunities:read` — [full detail](./reports/get-report-dashboards.md)

### GET /report-dashboards/:id

Get a dashboard with all its cards. Each card includes title, visualization_type, size, position, and full query_spec.

**Scopes:** `opportunities:read` — [full detail](./reports/get-report-dashboards-id.md)

### PATCH /report-dashboards/:id

Partial update -- rename, re-describe, or change visibility of a dashboard. Changing visibility to "all_users" removes the restriction but does not delete existing ACL entries.

**Scopes:** `opportunities:read` — [full detail](./reports/patch-report-dashboards-id.md)

### DELETE /report-dashboards/:id

Delete a dashboard and all its cards permanently.

**Scopes:** `opportunities:read` — [full detail](./reports/delete-report-dashboards-id.md)

### GET /report-dashboards/:id/acl

List ACL entries for a restricted dashboard. Each entry has user_id or role_name indicating who has access.

**Scopes:** `opportunities:read` — [full detail](./reports/get-report-dashboards-id-acl.md)

### POST /report-dashboards/:id/acl

Grant a user or role access to a restricted dashboard. Set visibility="restricted" on the dashboard first.

**Scopes:** `opportunities:read` — [full detail](./reports/post-report-dashboards-id-acl.md)

### POST /report-dashboards/:id/cards

Add a chart or table card to a dashboard. Use display_config.columns to control which columns appear in email digest renders for table/drilldown cards.

**Scopes:** `opportunities:read` — [full detail](./reports/post-report-dashboards-id-cards.md)

### PATCH /report-cards/:id

Partial update on a card -- change title, visualization type, query spec, display_config, size, or position.

**Scopes:** `opportunities:read` — [full detail](./reports/patch-report-cards-id.md)

### DELETE /report-cards/:id

Remove a card from its dashboard. Dashboard itself is not affected.

**Scopes:** `opportunities:read` — [full detail](./reports/delete-report-cards-id.md)

### PUT /report-dashboards/:id/reorder

Reorder cards by providing an ordered array of card UUIDs.

**Scopes:** `opportunities:read` — [full detail](./reports/put-report-dashboards-id-reorder.md)

### POST /reports/send

Send a report dashboard as an email digest. Dashboard cards render server-side and are inlined into the email body. Each recipient is scoped via current_user_id so cards filtered to "the current user" naturally show per-recipient data. Returns per-recipient send status with skipped_reason when a send is suppressed.

**Scopes:** `opportunities:read` — [full detail](./reports/post-reports-send.md)

### GET /report-funnels

Get funnel step configuration for a pipeline.

**Scopes:** `opportunities:read` — [full detail](./reports/get-report-funnels.md)

### PUT /report-funnels

Create or update funnel step configuration for a pipeline.

**Scopes:** `opportunities:read` — [full detail](./reports/put-report-funnels.md)

### DELETE /report-funnels/:id

Delete a funnel config.

**Scopes:** `opportunities:read` — [full detail](./reports/delete-report-funnels-id.md)