Skip to main content

Work with tracer

Use the Tracer API when you already have records and need the relationships between them, for example which verification record supports which system requirement.

The main public workflow​

The most useful public tracing workflow today is batch retrieval:

curl -X POST "https://tracer.prod.certhub-containers.containers.certhub.tech/traces/batch/list" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [
      {"node_id": "RECORD_ID_1", "node_type": "Record", "version": ""},
      {"node_id": "RECORD_ID_2", "node_type": "Record", "version": ""}
    ],
    "n_hops": 1,
    "mode": "legacy_connected_nodes"
  }'

What the request means​

  • node_id is the record _id
  • node_type should be "Record" for Records API rows
  • version is typically an empty string in this pattern
  • n_hops controls how many link levels to traverse
  • mode: "legacy_connected_nodes" returns the directly connected nodes for this use case
  1. Export the records you care about first
  2. Collect their record _id values
  3. Call POST /traces/batch/list
  4. Interpret the returned edges according to your CertHub use-case relationships

If you need the record data as well as the traces, start with Export Records from CertHub.

Operational note​

In practice, the batch list flow is the safest starting point for API-key-based integrations. Keep the request bounded to the records you actually care about rather than trying to traverse everything.

Create a trace​

POST /trace links two objects, for example a verification record to the requirement it covers:

curl -X POST "https://tracer.prod.certhub-containers.containers.certhub.tech/trace" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "RECORD_ID_1",
    "sourceType": "Record",
    "sourceVersion": "",
    "target": "RECORD_ID_2",
    "targetType": "Record",
    "targetVersion": "",
    "relation_type": "is_related",
    "create_bidirectional": true,
    "backward_relation_type": "is_related"
  }'
  • source* and target* name the two objects the same way node_id, node_type and version do above
  • relation_type is the relation from source to target
  • with create_bidirectional: true Tracer also stores the trace from target to source with backward_relation_type, so the link shows up when you read the traces of either object
  • a missing object gets its node on the fly; the response is the created trace with its trace_id

Typical outcomes​

Teams use this to:

  • reconstruct requirement-to-verification chains
  • enrich exported records with trace relationships
  • feed documentation or traceability tooling outside CertHub
Working example

Cadence (CertHub’s public engineering example) uses this batch-list pattern to reconstruct requirement-to-verification chains. See Working example.

Next steps​