Organisations

Read one diagram's evidence

One diagram drawn from code: its currency and controls, its check history on the default branch, and its drift episodes with the pull requests that resolved them.

GET/orgs/{org}/evidence/diagram

TL;DR

Question	Answer
What does it do?	Read one diagram's evidence.
What does it take?	`org` in the path, and `repository`, `name` in the query string.
What does it return?	Status 200 with a body of type `EvidenceDiagramDetail`.
What can go wrong?	`400` the query is not valid; `401` not signed in; `403` a plan without compliance evidence (plan.compliance_evidence_not_included); `404` no such organisation, the caller is not a member of it, or no check of the diagram is kept (evidence.diagram_not_found); `429` too many requests; `503` organisations are not set up on this server. Every failure uses the one error envelope.

What it does

One diagram drawn from code: its currency and controls, its check history on the default branch, and its drift episodes with the pull requests that resolved them. Every member, on Enterprise.

Path parameters

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

Query parameters

Field	Type	Required	Description
`repository`	`string`	yes	The repository, as owner/name.
`name`	`string`	yes	The source's name.

Responses

Status	Meaning	Body
200	The diagram.	`EvidenceDiagramDetail`
400	The query is not valid.	`ErrorResponse`
401	Not signed in.	`ErrorResponse`
403	A plan without compliance evidence (plan.compliance_evidence_not_included).	`ErrorResponse`
404	No such organisation, the caller is not a member of it, or no check of the diagram is kept (evidence.diagram_not_found).	`ErrorResponse`
429	Too many requests.	`ErrorResponse`
503	Organisations are not set up on this server.	`ErrorResponse`

Response body

A 200 answer has the type EvidenceDiagramDetail.

Field	Type	Required	Description
`diagram`	`EvidenceDiagram`	yes
`diagram.repository`	`string`	yes
`diagram.name`	`string`	yes
`diagram.out`	`string`	yes	The diagram's path in the repository.
`diagram.format`	`string \| null`	yes	The importer it is drawn with, as the run reported or as its name says, or null.
`diagram.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).
`diagram.lastKnown`	`"current" \| "drifted" \| null`	yes	For a stale diagram, what its latest conclusive check found.
`diagram.lastCheckFailed`	`boolean`	yes	True when the latest check could not make the diagram; the status is the one before it.
`diagram.driftedSince`	`integer \| null`	yes	For a drifted diagram, when its drift began.
`diagram.added`	`integer`	yes	minimum 0.
`diagram.removed`	`integer`	yes	minimum 0.
`diagram.changed`	`integer`	yes	minimum 0.
`diagram.lastCheckedAt`	`integer \| null`	yes
`diagram.lastSha`	`string \| null`	yes
`diagram.runUrl`	`string \| null`	yes
`diagram.pullRequestUrl`	`string \| null`	yes
`diagram.controls`	`string[]`	yes	The controls it serves as evidence for, suggested or set.
`diagram.suggested`	`string[]`	yes	The controls its format suggests.
`checks`	`EvidenceCheck[]`	yes
`checks[].status`	`"in-step" \| "drifted" \| "written" \| "failed"`	yes
`checks[].checks`	`integer`	yes
`checks[].firstAt`	`integer`	yes
`checks[].lastAt`	`integer`	yes
`checks[].firstSha`	`string \| null`	yes
`checks[].lastSha`	`string \| null`	yes
`checks[].runUrl`	`string \| null`	yes
`checks[].pullRequestUrl`	`string \| null`	yes
`checks[].added`	`integer`	yes	minimum 0.
`checks[].removed`	`integer`	yes	minimum 0.
`checks[].changed`	`integer`	yes	minimum 0.
`truncated`	`boolean`	yes
`episodes`	`EvidenceEpisode[]`	yes
`episodes[].startedAt`	`integer`	yes
`episodes[].resolvedAt`	`integer \| null`	yes
`episodes[].checks`	`integer`	yes	minimum 0.
`episodes[].added`	`integer`	yes	minimum 0.
`episodes[].removed`	`integer`	yes	minimum 0.
`episodes[].changed`	`integer`	yes	minimum 0.
`episodes[].pullRequestUrl`	`string \| null`	yes
`episodes[].resolvedSha`	`string \| null`	yes
`episodes[].resolvedRunUrl`	`string \| null`	yes

Doc	Why
API reference	Every endpoint, and the error envelope
Schemas	Every request and response type
Tool reference	The operations as callable tools