# Read an organisation's compliance evidence

> Page: https://docs.plotwork.dev/api/get-orgs-org-evidence. Index of every page: https://docs.plotwork.dev/llms.txt

Whether the plan includes compliance evidence, the settings, each framework with each control's share of current diagrams, every repository and diagram with its status, and the hand-drawn Mermaid found, with hints.

`GET /orgs/{org}/evidence`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Read an organisation's compliance evidence. |
| What does it take? | `org` in the path. |
| What does it return? | Status 200 with a body of type [`OrgEvidence`](https://docs.plotwork.dev/api/schemas.md#orgevidence). |
| What can go wrong? | `401` not signed in; `404` no such organisation, or the caller is not a member of it; `429` too many requests; `503` organisations are not set up on this server. Every failure uses the one error envelope. |

## What it does

Whether the plan includes compliance evidence, the settings, each framework with each control's share of current diagrams, every repository and diagram with its status, and the hand-drawn Mermaid found, with hints. Evidence for controls, never a claim that one is met. Every member.

## Path parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `org` | `string` | yes | The organisation's id or its slug. |

## Responses

| Status | Meaning | Body |
|---|---|---|
| 200 | The evidence. | [`OrgEvidence`](https://docs.plotwork.dev/api/schemas.md#orgevidence) |
| 401 | Not signed in. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 404 | No such organisation, or the caller is not a member of it. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 429 | Too many requests. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 503 | Organisations are not set up on this server. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

A 200 answer has the type [`OrgEvidence`](https://docs.plotwork.dev/api/schemas.md#orgevidence).

| Field | Type | Required | Description |
|---|---|---|---|
| `active` | `boolean` | yes | True when the plan includes compliance evidence (Enterprise). When false the lists are empty. |
| `plan` | `"free" \| "pro" \| "enterprise"` | yes |  |
| `retentionDays` | `integer` | yes | minimum 0. |
| `legalHold` | `boolean` | yes |  |
| `githubLinked` | `boolean` | yes |  |
| `settings` | `EvidenceSettings` | yes |  |
| `settings.frameworks` | `("pci-dss" \| "soc2" \| "iso27001" \| "nist-800-53")[]` | yes |  |
| `settings.staleDays` | `integer` | yes |  |
| `settings.defaults` | `boolean` | yes | True when nothing was saved and these are the defaults: every framework, 14 days. |
| `frameworks` | `EvidenceFrameworkSummary[]` | yes |  |
| `frameworks[].id` | `"pci-dss" \| "soc2" \| "iso27001" \| "nist-800-53"` | yes |  |
| `frameworks[].name` | `string` | yes |  |
| `frameworks[].version` | `string` | yes |  |
| `frameworks[].mark` | `string` | yes |  |
| `frameworks[].source` | `string` | yes |  |
| `frameworks[].chosen` | `boolean` | yes |  |
| `frameworks[].controls` | `EvidenceControlSummary[]` | yes |  |
| `frameworks[].controls[].id` | `string` | yes |  |
| `frameworks[].controls[].ref` | `string` | yes |  |
| `frameworks[].controls[].title` | `string` | yes |  |
| `frameworks[].controls[].evidence` | `string` | yes |  |
| `frameworks[].controls[].text` | `string` | yes |  |
| `frameworks[].controls[].paraphrased` | `boolean` | yes |  |
| `frameworks[].controls[].how` | `string` | yes |  |
| `frameworks[].controls[].limit` | `string` | yes |  |
| `frameworks[].controls[].total` | `integer` | yes | Diagrams mapped to it, hand-drawn ones included. minimum 0. |
| `frameworks[].controls[].current` | `integer` | yes | Of those, the ones that are current. minimum 0. |
| `repositories` | `EvidenceRepository[]` | yes |  |
| `repositories[].repository` | `string` | yes |  |
| `repositories[].status` | `"current" \| "drifted" \| "stale" \| "unknown"` | yes | current, drifted, stale or unknown, by the checks on the default branch (docs/architecture/compliance-evidence.md, section 2). |
| `repositories[].repositoryId` | `string \| null` | yes | The GitHub App's id of the repository, when an installation reaches it. |
| `repositories[].private` | `boolean \| null` | yes |  |
| `repositories[].archived` | `boolean` | yes |  |
| `repositories[].setup` | `"none" \| "pr_open" \| "merged" \| "closed" \| null` | yes |  |
| `repositories[].diagrams` | `integer` | yes | minimum 0. |
| `repositories[].current` | `integer` | yes | minimum 0. |
| `repositories[].drifted` | `integer` | yes | minimum 0. |
| `repositories[].stale` | `integer` | yes | minimum 0. |
| `repositories[].unknown` | `integer` | yes | minimum 0. |
| `repositories[].unverified` | `integer` | yes | minimum 0. |
| `repositories[].lastCheckedAt` | `integer \| null` | yes |  |
| `repositories[].runUrl` | `string \| null` | yes |  |
| `repositories[].controls` | `string[]` | yes |  |
| `repositories[].badge` | `boolean` | yes | True when its README badge is on. |
| `repositories[].scannedAt` | `integer \| null` | yes |  |
| `diagrams` | `EvidenceDiagram[]` | yes |  |
| `diagrams[].repository` | `string` | yes |  |
| `diagrams[].name` | `string` | yes |  |
| `diagrams[].out` | `string` | yes | The diagram's path in the repository. |
| `diagrams[].format` | `string \| null` | yes | The importer it is drawn with, as the run reported or as its name says, or null. |
| `diagrams[].status` | `"current" \| "drifted" \| "stale" \| "unknown"` | yes | current, drifted, stale or unknown, by the checks on the default branch (docs/architecture/compliance-evidence.md, section 2). |
| `diagrams[].lastKnown` | `"current" \| "drifted" \| null` | yes | For a stale diagram, what its latest conclusive check found. |
| `diagrams[].lastCheckFailed` | `boolean` | yes | True when the latest check could not make the diagram; the status is the one before it. |
| `diagrams[].driftedSince` | `integer \| null` | yes | For a drifted diagram, when its drift began. |
| `diagrams[].added` | `integer` | yes | minimum 0. |
| `diagrams[].removed` | `integer` | yes | minimum 0. |
| `diagrams[].changed` | `integer` | yes | minimum 0. |
| `diagrams[].lastCheckedAt` | `integer \| null` | yes |  |
| `diagrams[].lastSha` | `string \| null` | yes |  |
| `diagrams[].runUrl` | `string \| null` | yes |  |
| `diagrams[].pullRequestUrl` | `string \| null` | yes |  |
| `diagrams[].controls` | `string[]` | yes | The controls it serves as evidence for, suggested or set. |
| `diagrams[].suggested` | `string[]` | yes | The controls its format suggests. |
| `findings` | `EvidenceFinding[]` | yes |  |
| `findings[].id` | `string` | yes |  |
| `findings[].repository` | `string` | yes |  |
| `findings[].path` | `string` | yes |  |
| `findings[].line` | `integer` | yes |  |
| `findings[].mermaidType` | `string \| null` | yes |  |
| `findings[].kind` | `string \| null` | yes |  |
| `findings[].nodes` | `integer` | yes | minimum 0. |
| `findings[].matched` | `integer` | yes | minimum 0. |
| `findings[].source` | `object \| null` | yes | The detected source that shares the most names with it. |
| `findings[].source.name` | `string` | yes |  |
| `findings[].source.format` | `string` | yes |  |
| `findings[].mentionsMissing` | `string[]` | yes | Hints: names it draws that no source declares. Hints, not verification. |
| `findings[].codeMissing` | `string[]` | yes | Hints: names the matching source declares that it does not draw. |
| `findings[].pullRequestNumber` | `integer \| null` | yes |  |
| `findings[].superseded` | `boolean` | yes | True once the source its pull request added has a check. |
| `findings[].controls` | `string[]` | yes |  |
| `findings[].suggested` | `string[]` | yes |  |
| `findings[].scannedAt` | `integer` | yes |  |
| `trend` | `object \| null` | yes | The 90-day trend, from the stored checks. Null on a plan without compliance evidence. |
| `trend.days` | `string[]` | yes | The last 90 UTC dates, oldest first. |
| `trend.overall` | `(number \| null)[]` | yes | The share of diagrams drawn from code that were current at the end of each day, 0 to 1, or null before any. |
| `trend.frameworks` | `object` | yes | The same share over the diagrams mapped to each framework's controls. |
| `trend.frameworks.pci-dss` | `(number \| null)[]` | no |  |
| `trend.frameworks.soc2` | `(number \| null)[]` | no |  |
| `trend.frameworks.iso27001` | `(number \| null)[]` | no |  |
| `trend.frameworks.nist-800-53` | `(number \| null)[]` | no |  |
| `truncated` | `boolean` | yes |  |

## See also

| Doc | Why |
|---|---|
| [API reference](https://docs.plotwork.dev/api/reference.md) | Every endpoint, and the error envelope |
| [Schemas](https://docs.plotwork.dev/api/schemas.md) | Every request and response type |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |