> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Evidence

> Collect, review, and approve evidence for governance controls — automated and manual, with gap analysis.

Evidence is what turns "we have policies" into "we can prove it". Observatory collects evidence automatically where it can (runs, evaluations, alerts) and lets reviewers attach manual artefacts where it can't (sign-offs, screenshots, external reports).

***

## Types of evidence

| Source                             | What it captures                                                      | Collection |
| ---------------------------------- | --------------------------------------------------------------------- | ---------- |
| **Automated — runs**               | A successful or violating run that satisfies (or breaches) a control. | Automatic. |
| **Automated — policy evaluations** | An evaluation result tied to a policy and run.                        | Automatic. |
| **Automated — alert events**       | An alert and its resolution.                                          | Automatic. |
| **Manual — document**              | Uploaded PDFs, screenshots, sign-off forms.                           | Manual.    |
| **Manual — text attestation**      | A reviewer's typed statement.                                         | Manual.    |

***

## Workflow

```mermaid theme={"system"}
flowchart LR
    Source["Source: run, evaluation,<br/>alert, or upload"] --> Draft[Evidence: draft]
    Draft --> Review{Reviewer}
    Review -->|Approve| Approved[Approved]
    Review -->|Reject| Rejected[Rejected with reason]
    Approved --> Mapped[Mapped to controls]
    Rejected --> Discard[Discarded / retried]
```

Every piece of evidence goes through review unless the control is explicitly configured to auto-approve automated sources.

***

## Reviewing evidence

<Steps>
  <Step title="Open Evidence">
    The default view shows everything in the **Draft** state ordered by oldest first.
  </Step>

  <Step title="Inspect the artefact">
    For automated evidence, the run, evaluation, or alert is linked. For manual evidence, the upload is rendered inline.
  </Step>

  <Step title="Pick a control">
    Map the evidence to one or more controls (e.g. an EU AI Act requirement). One artefact can support multiple controls.
  </Step>

  <Step title="Approve or reject">
    Approving moves the artefact into the audit-ready set. Rejecting requires a reason — useful for training the team on what's acceptable.
  </Step>
</Steps>

***

## Gap analysis

The **Gaps** card flags controls that have no approved evidence. Use it to prioritise:

* Sort by framework (EU AI Act, NIST, ISO 42001)
* Sort by severity of the underlying control
* See last-approved-evidence age — anything older than a quarter shows as stale

```http theme={"system"}
GET /api/evidence/gaps?framework=eu-ai-act
```

Returns the controls that lack approved evidence and the time since the last approval.

***

## API

| Endpoint                          | Use                                            |
| --------------------------------- | ---------------------------------------------- |
| `GET /api/evidence`               | List with filters (state, control, framework). |
| `POST /api/evidence`              | Submit manual evidence.                        |
| `POST /api/evidence/{id}/approve` | Approve.                                       |
| `POST /api/evidence/{id}/reject`  | Reject with reason.                            |
| `POST /api/evidence/collect`      | Trigger an automated collection run.           |
| `GET /api/evidence/gaps`          | Gap analysis.                                  |

<Warning>
  Static routes (`/collect`, `/gaps`) are defined before `/{org_id}` in the router. Maintain that order on forks.
</Warning>

***

## Related resources

<CardGroup cols={2}>
  <Card title="Policies" icon="file-shield" href="./policies">
    Many evidence sources are policy evaluations.
  </Card>

  <Card title="Compliance" icon="circle-check" href="../compliance/overview">
    Where mapped evidence shows up in the heatmap.
  </Card>
</CardGroup>