# Scan a repository for hand-drawn Mermaid

> Page: https://docs.plotwork.dev/api/post-orgs-org-evidence-repositories-repository-id-scan. Index of every page: https://docs.plotwork.dev/llms.txt

Reads the Markdown, Mermaid and detected source files of the default branch in memory, lists each Mermaid diagram as unverified, and compares its names with the code as hints.

`POST /orgs/{org}/evidence/repositories/{repositoryId}/scan`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Scan a repository for hand-drawn Mermaid. |
| What does it take? | `org`, `repositoryId` in the path. |
| What does it return? | Status 200 with a body of type [`EvidenceScan`](https://docs.plotwork.dev/api/schemas.md#evidencescan). |
| What can go wrong? | `401` not signed in; `403` a member or a reader (orgs.forbidden), a plan without compliance evidence (plan.compliance_evidence_not_included), or an origin that may not make changes; `404` no such organisation or repository (github.repository_not_found), or the caller is not a member; `409` the installation is suspended (github.suspended); `422` the repository is empty (github.nothing_to_draw); `429` too many requests, or GitHub asked to wait (github.rate_limited); `502` GitHub did not answer as expected (github.unavailable); `503` the GitHub App or the Engine is not set up here. Every failure uses the one error envelope. |

## What it does

Reads the Markdown, Mermaid and detected source files of the default branch in memory, lists each Mermaid diagram as unverified, and compares its names with the code as hints. Stores paths, lines, names and counts only. The owner and admins, on Enterprise. Audited.

## Path parameters

| Field | Type | Required | Description |
|---|---|---|---|
| `org` | `string` | yes | The organisation's id or its slug. |
| `repositoryId` | `string` | yes | GitHub's id of the repository. |

## Responses

| Status | Meaning | Body |
|---|---|---|
| 200 | The repository's findings. | [`EvidenceScan`](https://docs.plotwork.dev/api/schemas.md#evidencescan) |
| 401 | Not signed in. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 403 | A member or a reader (orgs.forbidden), a plan without compliance evidence (plan.compliance_evidence_not_included), or an origin that may not make changes. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 404 | No such organisation or repository (github.repository_not_found), or the caller is not a member. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 409 | The installation is suspended (github.suspended). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 422 | The repository is empty (github.nothing_to_draw). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 429 | Too many requests, or GitHub asked to wait (github.rate_limited). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 502 | GitHub did not answer as expected (github.unavailable). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 503 | The GitHub App or the Engine is not set up here. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

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

| Field | Type | Required | Description |
|---|---|---|---|
| `repository` | `string` | yes |  |
| `documents` | `integer` | yes | minimum 0. |
| `truncated` | `boolean` | yes |  |
| `archived` | `boolean` | yes |  |
| `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 |  |

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