---
title: "List HITL configs"
method: GET
path: "/api/v1/hitl"
tags: ["HITL"]
---

# List HITL configs

`GET /api/v1/hitl`

## Request

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

Get paginated list of HITL configurations.

## Query parameters

- `page` integer
- `limit` integer
- `status` 'pending' | 'active' | 'archived': Status of a HITL configuration
- `environment` 'production' | 'test'
- `profile_id` string: Filter configs to one project (public profile). UX narrowing only — always ANDed with the owner; omit to list all projects.

## Response `200`

List of HITL configs

- HitlListResponse: Paginated list of HITL configurations
  - `data` Hitl[], required
    - `id` string, required: MongoDB ObjectId
    - `user_id` string, required: MongoDB ObjectId
    - `name` string, nullable
    - `profile_id` string: MongoDB ObjectId
    - `circle_id` string: MongoDB ObjectId
    - `channels` HitlChannel[], required
      - union: A messaging channel configured for HITL approvals
        - object
          - `type` 'telegram', required
          - `config` object, required: Telegram channel configuration
            - `chat_id` string, required: Telegram chat ID for receiving approval requests
        - object
          - `type` 'whatsapp', required
          - `config` object, required: WhatsApp channel configuration — at least one of phone_number or bsuid is required
            - `phone_number` string: Phone number in E.164 format
            - `bsuid` string: WhatsApp Business-Scoped User ID (e.g. US.abc123...)
    - `timeout_seconds` integer, required
    - `status` 'pending' | 'active' | 'archived', required: Status of a HITL configuration
    - `keypair` object, nullable, required: Encryption keypair metadata (null if not configured)
      - `kid` string, required: Key identifier (SHA-256 of public key DER)
      - `has_encrypted_private_key` boolean, required: Whether encrypted private key is stored
      - `has_wrapped_dek` boolean, required: Whether the keypair carries a master-key-wrapped DEK (v2 envelope)
      - `has_backup_wrapper` boolean, required: Whether the DEK carries a recovery (backup-code) wrapper
    - `environment` 'production' | 'test', required
    - `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
  - `limits` object, required
    - `max_active_configs` integer, nullable, required: The plan's cap on active configs; null when the plan is unlimited
    - `active_configs` integer, required: Active configs on the account across every environment and profile — the count creating a config is checked against, whatever this list is filtered to

## Other responses

- `403`: `profile_mismatch` — a project-bound API key named another sub-account; it acts for its own sub-account only.

---

[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/b15f506de696?raw)