# Controls Map data retrieval

Start with [/data/v1/catalog.json](/data/v1/catalog.json). It lists domain topics, source bundles, record indexes, a JSON Schema and provenance metadata. Select a topic or source before fetching individual records. For readable pages, [browse the catalog](/agents/catalog.html).

Keep the catalog's `catalogRevision` for the entire request. Follow its content-hashed `/assets/agent_*.json` URLs and each page's `next` URL. Bundle pages contain at most 40 records; index pages contain at most 100 summaries. `total` describes the complete selection. `next: null` ends the selection. Domain bundles mark direct matches and the context needed to explain them. They do not recursively expand shared frameworks or workflows.

Use `recordDirectory` to resolve a relationship's `sourceId` and `targetId` to immutable record JSON. Record JSON includes incident relationships, mapping properties and the original public details. Directory pages include every record, including workflows with no mapped controls. Filter summaries by `type` and `attributes`, then fetch only the matching records.

The directory is the exact published record set. Source notes may mention withdrawn entries retained only upstream. Do not synthesize missing records or infer that those entries are published here.

| Record type | Meaning |
| --- | --- |
| `standard` | A framework, regulation or guidance source. |
| `control` | A source requirement or guidance proposition. |
| `unified` | A reusable control connected to source requirements or guidance. |
| `risk` | A catalog risk. |
| `workflow` | A canonical process template. |

| Relationship | Direction | Meaning |
| --- | --- | --- |
| `mitigates` | unified → risk | The control addresses the risk. |
| `maps_to` | unified → control | The control maps to a source requirement; coverage may be partial. Read the mapping properties and residual requirements. |
| `informed_by` | unified → control | A guidance proposition informs the control. This relationship does not establish requirement coverage. |
| `belongs_to` | control → standard | The requirement or proposition belongs to the source. |
| `operates` | workflow → unified | The workflow operates the control. |
| `tests` | workflow → unified | The workflow tests the control. |
| `oversees` | workflow → unified | The workflow oversees the control. |

For workflows, `sourceIds` derives from recorded control mappings, while `details.standards` contains the workflow's declared standards tags. The fields can differ. Neither field establishes company applicability.

Stable `/data/v1/` paths are sharing aliases. They can change during deployment. Check every envelope's `schemaVersion` and `catalogRevision`; reject mismatches and restart from the catalog. Do not combine records from different revisions. Relationship `sourceDetailPath` and `targetDetailPath` are stable aliases with an `expectedCatalogRevision`; resolve endpoint IDs using the pinned directory whenever possible. If an immutable resource is unavailable, retry that URL or restart from a new catalog. Do not silently substitute a stable alias.

## Freshness and history

Read the current mutable [`history.json`](/data/v1/history.json) and compare `history.current` with your pinned `catalogRevision`. A pinned catalog's revision-addressed history URL is an immutable snapshot of history at that release. It does not tell you whether a newer release exists.

To catch up, walk the release entries newest-first until you reach the pinned revision. Then apply those releases' `changes.json` change sets oldest-first and re-pin the current catalog. Applying additions and removals newest-first can restore a record that a later release removed. If the pinned revision is unknown, or if an intervening release is marked as rolled back (`rolledBack: true`), do not mix records from the two states. Choose the intended release and deliberately re-pin its catalog and immutable assets.

Each change set separates added, changed and removed ids. A `changed` entry's `fields` names the record fields whose published values changed. Removed records appear only in change sets and are absent from the current record directory. Release `counts` describe catalog changes; they do not establish when a record was first created or changed in an upstream source.

A record's `history.updatedAt` is the catalog release timestamp when that published record last changed, not its upstream publication date.

History availability begins at the September 17 baseline. That immutable original baseline catalog and its records preserve their pre-history bytes, so their record envelopes do not contain history. A consumer pinned to that baseline can use the current history alias and intervening change sets, then re-pin to retrieve current record envelopes with history. Read [`sources.json`](/data/v1/sources.json) for the upstream sources and each source's `status`.

Workflow `download.url` returns the unchanged template envelope. Its `releaseId` is separate from the catalog revision. The wrapper provides the download's release metadata; the template body is exempt from the data-envelope schema.

Read `metadata` for aliases, provenance and limitations. Preserve null source URLs: they indicate that no record-specific citation was supplied. Mappings may cover only part of a requirement. Keep coverage, residual requirements and guidance relationships in any answer. `informed_by` expresses guidance; it does not establish a mandatory obligation. Cite the source URL when present and the record's map or canonical URL for catalog context.

Readable topic, source and record pages use explicit `.html` paths under `/agents/` and work without JavaScript. The interactive map is at [/](https://evidenceflows.com/). The Workflow Library, which publishes the canonical workflow templates, is at [/workflows/](https://evidenceflows.com/workflows/).