Global Reports

Create, edit, and read saved cross-run reports programmatically

A Global Report is a named, user- (or agent-) curated view over the canonical dataset: one tab per entity with an ordered column selection. The report stores only its definition — every read recomputes fresh rows from the latest data (with a short server-side cache), so a report is always current.

Auth as everywhere: Authorization: Bearer ds_live_.... Reads need reports:read, writes reports:write (both in the Agent preset). Deleting a report deletes a view definition — never researched data.

Discover the column vocabulary first

bash

curl -s $BASE_URL/v1/reports/columns -H "Authorization: Bearer $DEEPSIEVE_API_KEY"

Returns the selectable columns per entity (own columns + relationship pill columns). Like everything Blueprint-shaped: discover, don't guess.

Create

bash

curl -s -X POST $BASE_URL/v1/reports \
  -H "Authorization: Bearer $DEEPSIEVE_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Vendor shortlist",
       "config": {"tabs": [{"id": "t1", "name": "Companies",
                            "entity_key": "companies",
                            "columns": ["name", "hq_city", "funding_total"]}]}}'

Invalid entities/columns are rejected with a typed 400 pointing back at /v1/reports/columns.

Read, update, delete

bash

curl -s $BASE_URL/v1/reports -H "Authorization: Bearer $DEEPSIEVE_API_KEY"          # list
curl -s $BASE_URL/v1/reports/{id} -H "Authorization: Bearer $DEEPSIEVE_API_KEY"     # definition
curl -s -X PATCH $BASE_URL/v1/reports/{id} -H "Authorization: Bearer $DEEPSIEVE_API_KEY" \
  -H "Content-Type: application/json" -d '{"name": "Renamed"}'                       # update
curl -s -X DELETE $BASE_URL/v1/reports/{id} -H "Authorization: Bearer $DEEPSIEVE_API_KEY"

Read a tab's data

bash

curl -s $BASE_URL/v1/reports/{id}/tabs/{tab_id}/data \
  -H "Authorization: Bearer $DEEPSIEVE_API_KEY"

Fresh cross-run rows for that tab's entity, with the same per-cell evidence the UI shows. (The full column payload is returned; the tab's column selection defines the curated view in the app and its exports.) Free-preview accounts are row-capped here exactly as on every other read surface.

A row also carries holds, {column: {source, set_at, pending_finding}}, for the cells a person set on purpose; research never overwrites those. In a pivot tab a hold also carries address ({entity_key, record_id, column}), the cell itself, because a pivot key is a generated column. To act on one, find its cell_id in GET /v1/holds and use POST /v1/cells/{cell_id}/apply, keep or release (see Dataset sync). A row's evidence lists each cell's rows newest first, including rows recorded beside the cell (beside_cell set): the cell's own receipt is its rows with beside_cell null.

For raw entity access with sync cursors, use Dataset sync instead — reports are for curated, shareable views.