Traceability snapshot operations

Snapshots preserve a versioned project, group, or portfolio state for later inspection, comparison, and export. Use the REST API with an access token. The examples below cover the full workflow, from a baseline snapshot to an exported comparison.

Why save snapshots

Create a baseline snapshot before a change or release, then save a second state when the project metrics have updated. Comparing the two IDs shows the saved values and available differences. Export the comparison to share these values and both snapshot records with your team.

Follow this sequence: read the policy → create the baseline → make the change and refresh checks → create the current snapshot → compare the IDs → export the package. Keep both IDs with the release revision so reviewers can reopen the same data.

Base route and scope

These examples use Bash and curl 7.76 or newer. You can run them from any directory; the export file is written to the current directory. Sign in and get project access. Set CODEGRAPH_URL to the HTTPS API origin without a trailing slash or /api/v1. Keep the access token in CODEGRAPH_TOKEN in the current terminal. Set CODEGRAPH_PROJECT_ID to the UUID of an accessible project from the projects API response. Keep the token outside the repository. Before running the examples, turn off Bash command tracing with set +x.

The examples pass the authorization header through standard input with curl -H @- to keep the token out of process arguments.

All operations use:

/api/v1/traceability/snapshots

CodeGraph checks project and group access for every operation. Your access token and selected project determine which snapshot IDs you can read and compare.

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.

Check request and response fields against the deployed version’s OpenAPI schema at /api/openapi.json. It defines the current constraints.

Create a snapshot

Read /policy first. Check the available scopes, immutability and retention rules. Immutable snapshots remain stored as evidence; the available operations are create, list, inspect, compare and export.

printf 'Authorization: Bearer %s\n' "$CODEGRAPH_TOKEN" |
curl --fail-with-body -H @- "$CODEGRAPH_URL/api/v1/traceability/snapshots/policy" \
  -H "X-Project-ID: $CODEGRAPH_PROJECT_ID"

printf 'Authorization: Bearer %s\n' "$CODEGRAPH_TOKEN" |
curl --fail-with-body -H @- -X POST "$CODEGRAPH_URL/api/v1/traceability/snapshots" \
  -H "X-Project-ID: $CODEGRAPH_PROJECT_ID" \
  -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. CodeGraph checks access when you select another project.

A successful request returns JSON containing id. Save it as SNAPSHOT_ID. Comparison requires two actual snapshots: set their identifiers as BASELINE_ID and CURRENT_ID. Inspect scope_ref, project_name, timestamp, immutable, basis_mode and coherence_status; a stored snapshot can still contain incomplete data.

Read the snapshot basis

basis_mode describes how the data is assembled. In best_effort mode, CodeGraph collects the available project state. strict_audit requires a coherent analysis basis for views that use this mode.

coherence_status describes the links between the code graph, audit run, and saved results:

Read the snapshot basis
Value	How to read the result
`coherent`	The analysis artifacts are linked. Match `cpg_revision_id`, `audit_run_id`, and `audit_snapshot_id` to the revision under review.
`stale_cpg`	The graph is older than the source state, or the audit uses an earlier graph revision. Refresh the graph and run the audit.
`stale_audit`	The saved audit result refers to a different run. Refresh the results and create the next snapshot.
`audit_snapshot_only` / `dashboard_snapshot_only`	The basis contains a saved result of only one kind. Identify which second artifact needs to be generated.
`unknown`	The record uses the initial status value. Check the analysis identifiers before comparing snapshots.

The manual creation route used here saves project metrics with basis_mode: best_effort, coherence_status: unknown, and empty analysis identifiers. This also applies when the project already has a completed audit. Use these snapshots to inspect and compare saved metrics. For a review of remediation results, attach the audit report and its graph revision separately; the snapshot export supplies the saved states.

List and inspect

printf 'Authorization: Bearer %s\n' "$CODEGRAPH_TOKEN" |
curl --fail-with-body -H @- "$CODEGRAPH_URL/api/v1/traceability/snapshots?scope=project&limit=20&offset=0" \
  -H "X-Project-ID: $CODEGRAPH_PROJECT_ID"

printf 'Authorization: Bearer %s\n' "$CODEGRAPH_TOKEN" |
curl --fail-with-body -H @- "$CODEGRAPH_URL/api/v1/traceability/snapshots/$SNAPSHOT_ID" \
  -H "X-Project-ID: $CODEGRAPH_PROJECT_ID"

Omitting limit uses the configured maximum. Valid values are 1 through that maximum, with offset at least 0. An excessive limit or negative offset is rejected with HTTP 422; check the deployed OpenAPI schema for the maximum. The list response contains items, total, limit, offset, has_next and has_prev.

Compare snapshots

Prefer immutable IDs for release evidence:

printf 'Authorization: Bearer %s\n' "$CODEGRAPH_TOKEN" |
curl --fail-with-body -H @- -X POST "$CODEGRAPH_URL/api/v1/traceability/snapshots/compare" \
  -H "X-Project-ID: $CODEGRAPH_PROJECT_ID" \
  -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

printf 'Authorization: Bearer %s\n' "$CODEGRAPH_TOKEN" |
curl --fail-with-body -H @- -X POST "$CODEGRAPH_URL/api/v1/traceability/snapshots/$CURRENT_ID/export" \
  -H "X-Project-ID: $CODEGRAPH_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -o snapshot-export.bin \
  -d "{\"format\":\"json\",\"language\":\"en\",\"baseline_snapshot_id\":\"$BASELINE_ID\"}"

With baseline_snapshot_id, the export contains a comparison package:

Export
Field	Contents
`target_name`	The project or group name associated with the result.
`from_snapshot`	The baseline snapshot record, including its ID and timestamp.
`to_snapshot`	The current snapshot record.
`diff`	The comparison result for these snapshots.

To export a single snapshot, omit baseline_snapshot_id from the request body.

Check the HTTP status, content type and creation of a new export file. With format: json, snapshot-export.bin contains JSON. --fail-with-body reports HTTP errors as command failures, but an export error body can still be written to the output file. File existence alone does not prove success.

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.
For 403, check your role and access to the selected project. For 404, check the snapshot ID and access to its project.
Verify the exact operation set against live OpenAPI for the deployed revision.

Related guides

REST API reference — API connection, authentication, and project access.
Troubleshooting — connection checks and error diagnosis.