# ControlsMap 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.

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://controlsmap.com/).