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

# Proof runs

> Open a proof run in the sandbox, finish it and read its sealed report.

```text theme={null}
POST /v1/sandbox/proof-runs
GET  /v1/sandbox/proof-runs
GET  /v1/sandbox/proof-runs/{id}
POST /v1/sandbox/proof-runs/{id}/finish
```

A proof run is a window in your sandbox; finishing it returns the completeness, integrity and reconciliation report of that window. See [Proof kit](https://docs.wede.pt/concepts/proof-kit.md) for how to run one and how to read the report.

## Authentication

A sandbox API key (`wede_test_`), or a session of a user of your organisation. A production key receives `403 sandbox_key_required`. Opening and finishing need `reconciliation:manage`; reading needs `reconciliation:view`. The wede team never has access.

## Open a proof run

`POST /v1/sandbox/proof-runs`

**name** `string` *required*

1 to 120 characters.

```bash theme={null}
curl -X POST https://api.wede.pt/v1/sandbox/proof-runs \
  -H "x-wede-api-key: wede_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "POS and ATM without network" }'
```

`201 Created`

```json theme={null}
{
  "id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "name": "POS and ATM without network",
  "status": "open",
  "started_at": "2026-10-25T18:05:08.000Z",
  "finished_at": null,
  "window_ends_at": "2026-11-01T18:05:08.000Z",
  "declared": [],
  "report_sha256": null,
  "result": null
}
```

Only one run can be open at a time: another one returns `409 proof_run_open` with `proof_run_id`, the id of the open run.

## Finish a proof run

`POST /v1/sandbox/proof-runs/{id}/finish`

**declared** `array`

Optional. For devices that do not number their operations: up to 200 items of `{ "device": "...", "count": n }`, where `device` is the device id or the identifier the device sends, and `count` how many operations it sent in the window.

```bash theme={null}
curl -X POST https://api.wede.pt/v1/sandbox/proof-runs/7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f/finish \
  -H "x-wede-api-key: wede_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "declared": [{ "device": "ATM-0042", "count": 4 }] }'
```

`200 OK` returns the run with `status: "finished"`, `report_sha256`, `result` and `report`. The window ends when you finish, and never more than 7 days after it opened. A finished run never changes; finishing it again returns `409 proof_run_finished`.

An excerpt of `report`:

```json theme={null}
{
  "format": "wede-proof/1",
  "environment": "sandbox",
  "window": { "from": "2026-10-25T18:05:08.000Z", "to": "2026-10-25T18:05:12.000Z" },
  "overall": {
    "result": "pass",
    "failed": [],
    "not_exercised": [],
    "lost": 0,
    "stored_twice": 0,
    "altered_accepted_without_incident": 0
  },
  "checks": {
    "duplicates": {
      "exercised": true,
      "passed": true,
      "detail": { "duplicates_rejected": 5, "events_stored_twice": 0, "operations_with_more_than_one_line": 0 }
    }
  },
  "sync": { "batches": 4, "items": 15, "accepted": 9, "duplicates": 5, "rejected": 1, "conflicts": 0, "rejected_by_code": { "integrity_check_failed": 1 } },
  "reconciliation": { "operations": { "confirmed": 2, "differs": 1, "waiting": 6 } }
}
```

**report.overall.result** `string`

`pass` when every exercised check passed, `fail` when one failed (named in `failed`), `nothing_exercised` when the window had nothing to measure.

**report.checks** `object`

`offline_capture`, `out_of_order`, `duplicates`, `altered_message`, `completeness` and `own_records`, each with `exercised`, `passed` (`null` when not exercised, and always for `own_records`) and `detail`.

**report\_sha256** `string`

SHA-256 of `report` in canonical JSON (object keys sorted at every level, no spaces). See [The seal](https://docs.wede.pt/concepts/proof-kit.md#the-seal).

## List and read

`GET /v1/sandbox/proof-runs` returns the last 50 runs of your organisation in `data`, without the report. `GET /v1/sandbox/proof-runs/{id}` returns one run with its report once finished.

## Errors

| Status | Code | When |
| - | - | - |
| 400 | `invalid_payload` | A missing or too long name, or `declared` not a list of `{ device, count }` |
| 401 | `unauthorized` | Credential missing, malformed, revoked or expired |
| 403 | `sandbox_key_required` | A production API key |
| 403 | `forbidden` | A role without the permission, or a user outside an organisation |
| 404 | `not_found` | The run does not exist in your organisation |
| 409 | `proof_run_open` | Another run is open (`proof_run_id`) |
| 409 | `proof_run_finished` | The run is already finished |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.