Traceability snapshot operations

Snapshots preserve a versioned project, group, or portfolio state for later inspection, comparison, and export. Use the authenticated REST surface for user workflows; direct storage access belongs to maintainer diagnostics.

Base route and scope

All operations in this guide use:

/api/v1/traceability/snapshots

The route is mounted in src/api/app_routers.py, listed in src/api/route_contracts.py, and implemented by src/api/routers/dashboard_core/dashboard_v2_snapshots.py.

Project and group access is resolved from the authenticated ProjectContext. Non-admin callers cannot use query fields to escape that context. Treat a snapshot ID as an identifier, not as authorization.

Operations

Operations
Method and route	Purpose
`POST /api/v1/traceability/snapshots`	Create a manual project, group, or portfolio snapshot.
`GET /api/v1/traceability/snapshots`	List accessible snapshots with bounded pagination.
`GET /api/v1/traceability/snapshots/policy`	Read the effective immutable-snapshot governance policy.
`GET /api/v1/traceability/snapshots/{snapshot_id}`	Read one accessible snapshot record.
`POST /api/v1/traceability/snapshots/compare`	Compare two snapshot IDs or two project timestamps.
`POST /api/v1/traceability/snapshots/{snapshot_id}/export`	Export one snapshot or a comparison with a baseline snapshot.

The live OpenAPI schema is authoritative for request and response fields. Do not reuse examples from older dashboard routes.

Create a snapshot

curl -X POST "$CODEGRAPH_URL/api/v1/traceability/snapshots" \
  -H "Authorization: Bearer $CODEGRAPH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "project",
    "reason": "pre-release baseline",
    "trigger_source": "manual",
    "immutable": true,
    "retention_class": "standard"
  }'

For project scope, omit project_name to use the active project. Supplying another project does not bypass ProjectContext.

List and inspect

curl "$CODEGRAPH_URL/api/v1/traceability/snapshots?scope=project&limit=20&offset=0" \
  -H "Authorization: Bearer $CODEGRAPH_TOKEN"

curl "$CODEGRAPH_URL/api/v1/traceability/snapshots/$SNAPSHOT_ID" \
  -H "Authorization: Bearer $CODEGRAPH_TOKEN"

The service applies the configured maximum page size even when a caller requests more.

Compare snapshots

Prefer immutable IDs for release evidence:

curl -X POST "$CODEGRAPH_URL/api/v1/traceability/snapshots/compare" \
  -H "Authorization: Bearer $CODEGRAPH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"from_snapshot_id\":\"$BASELINE_ID\",\"to_snapshot_id\":\"$CURRENT_ID\",\"include_drilldown\":true}"

Timestamp comparison is supported for project snapshots. Aggregate group and portfolio comparisons require snapshot IDs.

Export

curl -X POST "$CODEGRAPH_URL/api/v1/traceability/snapshots/$CURRENT_ID/export" \
  -H "Authorization: Bearer $CODEGRAPH_TOKEN" \
  -H "Content-Type: application/json" \
  -o snapshot-export.bin \
  -d "{\"format\":\"json\",\"language\":\"en\",\"baseline_snapshot_id\":\"$BASELINE_ID\"}"

When baseline_snapshot_id is present, the export is a comparison package rather than a standalone snapshot.

Operational checks

Read /policy before relying on immutability, retention, or export behavior.
Preserve the snapshot IDs, current project identity, request time, and release revision in acceptance evidence.
A successful snapshot request supplies one evidence artifact. Record release readiness from the complete acceptance package.
Diagnose 403 as a scope or role issue and 404 as an absent or inaccessible record. Do not retry with raw storage access.
Verify the exact operation set against live OpenAPI for the deployed revision.

Source references

src/api/route_contracts.py
src/api/app_routers.py
src/api/routers/dashboard_core/dashboard_v2_snapshots.py
src/api/schemas/dashboard_v2_snapshots.py