Organisations
Read an organisation's compliance evidence
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}/evidenceTL;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. |
| 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 |
| 401 | Not signed in. | ErrorResponse |
| 404 | No such organisation, or the caller is not a member of it. | ErrorResponse |
| 429 | Too many requests. | ErrorResponse |
| 503 | Organisations are not set up on this server. | ErrorResponse |
Response body
A 200 answer has the type 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 | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
| Tool reference | The operations as callable tools |