---
title: "List confirmations"
method: GET
path: "/api/v1/confirmations"
tags: ["Confirmations"]
---

# List confirmations

`GET /api/v1/confirmations`

## Request

- Base URL: `https://api.proof.holdings`
- URL: `https://api.proof.holdings/api/v1/confirmations`
- Auth: HTTP bearer

List confirmation requests for the current tenant. Supports filtering by status and hitl_id.

## Query parameters

- `page` integer
- `limit` integer
- `status` 'pending' | 'approved' | 'denied' | 'expired': Status filter for listing confirmations. `pending`, `approved` and `denied` match the stored status (so `denied` includes timeouts). `expired` is not a status: it selects the confirmations that timed out — `denied` with `response.channel` `system` and `response.text` `timeout`, or still `pending` past `timeout_at`. A system denial for another reason (`key_rotated`, `config_archived`) is not included.
- `hitl_id` string: MongoDB ObjectId
- `start_date` string, nullable: Filter confirmations created on or after this date
- `end_date` string, nullable: Filter confirmations created on or before this date

## Response `200`

Paginated list of confirmations

- ConfirmationListResponse: Paginated list of confirmations
  - `data` Confirmation[], required
    - `id` string, required: MongoDB ObjectId
    - `hitl_id` string, required: HITL configuration used for this confirmation
    - `message` string, required: The stored ciphertext envelope, echoed back verbatim. The server never sees the plaintext, so this is never the human sentence — the approver decrypts it in their browser.
    - `status` 'pending' | 'approved' | 'denied', required: Status of a confirmation request. A confirmation that times out is `denied`, with `response.channel` `system` and `response.text` `timeout`.
    - `response` object, nullable: Approver response details (null while pending)
      - `action` 'approve' | 'deny', required
      - `text` string, nullable: The approver's optional comment, encrypted in the browser by the approval page: a ciphertext envelope (JSON), not plaintext. When `channel` is `system` no approver acted — the confirmation was denied by a timeout, a key rotation or an archived config — and this is that plaintext reason (`timeout`, `key_rotated`, `config_archived`). Null otherwise.
      - `channel` string, nullable
      - `at` string, date-time, required
      - `authorization_id` string, nullable: The enrolled approver's Authorization that resolved this confirmation, verified server-side; null when the decision is not attributable to one approver
    - `timeout_at` string, date-time, nullable: When this confirmation will time out
    - `proof_token` string, nullable: Signed proof of an approver's decision, approval or denial alike; null while pending and for a system denial (`response.channel` is `system`)
    - `resolved_at` string, date-time, nullable
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `pagination` object, required
    - `page` integer, required
    - `limit` integer, required
    - `total` integer, required
    - `total_pages` integer, required

## Other responses

- `401`: Unauthorized

---

[API](https://skmtc.dev/proof/apis/proof-holdings-api.md) · [All operations](https://skmtc.dev/proof/apis/proof-holdings-api/llms.txt) · [OpenAPI document](https://skmtc.dev/proof/apis/proof-holdings-api/revisions/6b8d61ee354f?raw)