Escrow API

Endpoints for managing the escrow queue. When Sentinel holds an action (because a CHAM policy fires or confidence is below threshold), the action enters escrow. A human operator must then release (approve) or kill (reject) the action before the countdown expires.

Endpoints

Method	Path	Description
GET	`/escrow`	List escrow items
GET	`/escrow/:id`	Get escrow item details
POST	`/escrow/:id/release`	Release (approve) a held action
POST	`/escrow/:id/kill`	Kill (reject) a held action

Escrow Statuses

Status	Description
`HELD`	Action is waiting for human review. Countdown is active.
`RELEASED`	Action was approved and executed.
`KILLED`	Action was rejected by a human operator.
`TIMED_OUT`	Countdown expired with no decision. Action was NOT executed (fail-closed).

TIP

TheWARDN is fail-closed by design. If an escrow item times out without a decision, the action is killed automatically. Silence never equals approval.

GET /escrow

List escrow items with optional filtering.

Query Parameters

Parameter	Type	Default	Description
`status`	`string`	—	Filter by status: `HELD`, `RELEASED`, `KILLED`, `TIMED_OUT`
`agent`	`string`	—	Filter by agent ID
`page`	`integer`	`1`	Page number
`limit`	`integer`	`50`	Results per page

Example Request

bash

curl -X GET "https://api.thewardn.ai/escrow?status=HELD" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "escrow_items": [
    {
      "id": "esc_7a2b3c4d",
      "status": "HELD",
      "agent_id": "agent_sales_bot",
      "action": {
        "type": "WRITE",
        "target": "customer_records",
        "environment": "production",
        "payload_summary": "Update 847 customer records with new pricing tier"
      },
      "confidence": 0.72,
      "policies_fired": [
        {
          "policy_id": "pol_8f3a2b1c",
          "policy_name": "Production Confidence Floor",
          "policy_type": "confidence_floor",
          "reason": "Confidence 0.72 is below threshold 0.85"
        }
      ],
      "countdown": {
        "started_at": "2026-04-10T14:00:00Z",
        "expires_at": "2026-04-10T14:30:00Z",
        "ttl_seconds": 1800,
        "remaining_seconds": 1247
      },
      "reasoning": "Agent requested bulk pricing update based on Q2 pricing sheet. Confidence reduced due to large batch size.",
      "created_at": "2026-04-10T14:00:00Z"
    },
    {
      "id": "esc_1e5f6g7h",
      "status": "HELD",
      "agent_id": "agent_deploy_bot",
      "action": {
        "type": "EXECUTE",
        "target": "deployment_pipeline",
        "environment": "production",
        "payload_summary": "Deploy v2.4.1 to production cluster"
      },
      "confidence": 0.88,
      "policies_fired": [
        {
          "policy_id": "pol_a9c2e4f6",
          "policy_name": "Require Approval for Deploys",
          "policy_type": "action_type_block",
          "reason": "EXECUTE actions in production require explicit approval"
        }
      ],
      "countdown": {
        "started_at": "2026-04-10T14:10:00Z",
        "expires_at": "2026-04-10T14:40:00Z",
        "ttl_seconds": 1800,
        "remaining_seconds": 1650
      },
      "reasoning": "All tests passed. Deploying feature branch merged via PR #312.",
      "created_at": "2026-04-10T14:10:00Z"
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 50
}

GET /escrow/:id

Get full details for a specific escrow item.

Path Parameters

Parameter	Type	Description
`id`	`string`	Escrow item ID

Example Request

bash

curl -X GET https://api.thewardn.ai/escrow/esc_7a2b3c4d \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

json

{
  "id": "esc_7a2b3c4d",
  "status": "HELD",
  "agent_id": "agent_sales_bot",
  "action": {
    "type": "WRITE",
    "target": "customer_records",
    "environment": "production",
    "payload_summary": "Update 847 customer records with new pricing tier",
    "full_payload": {
      "table": "customers",
      "operation": "UPDATE",
      "where": "pricing_tier = 'legacy'",
      "set": { "pricing_tier": "standard_v2", "updated_by": "agent_sales_bot" },
      "affected_rows": 847
    }
  },
  "confidence": 0.72,
  "policies_fired": [
    {
      "policy_id": "pol_8f3a2b1c",
      "policy_name": "Production Confidence Floor",
      "policy_type": "confidence_floor",
      "reason": "Confidence 0.72 is below threshold 0.85"
    },
    {
      "policy_id": "pol_d4f6a8c0",
      "policy_name": "Bulk Write Gate",
      "policy_type": "rate_limit",
      "reason": "Batch size 847 exceeds single-action limit of 100"
    }
  ],
  "countdown": {
    "started_at": "2026-04-10T14:00:00Z",
    "expires_at": "2026-04-10T14:30:00Z",
    "ttl_seconds": 1800,
    "remaining_seconds": 1247
  },
  "reasoning": "Agent requested bulk pricing update based on Q2 pricing sheet. Confidence reduced due to large batch size.",
  "audit_seq": 10847,
  "created_at": "2026-04-10T14:00:00Z"
}

POST /escrow/:id/release

Release (approve) a held action. The action will execute immediately upon release.

Path Parameters

Parameter	Type	Description
`id`	`string`	Escrow item ID

Request Body

Field	Type	Required	Description
`acknowledged`	`boolean`	Yes	Must be `true` to confirm the operator reviewed the action
`reason`	`string`	No	Reason for approval (recorded in audit trail)

WARNING

The acknowledged field must be explicitly set to true. This is a decision acknowledgment gate — it ensures the operator has consciously reviewed the held action before releasing it.

Example Request

bash

curl -X POST https://api.thewardn.ai/escrow/esc_7a2b3c4d/release \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "acknowledged": true,
    "reason": "Reviewed and approved. Pricing update aligns with Q2 pricing sheet from finance team."
  }'

Example Response

json

{
  "id": "esc_7a2b3c4d",
  "status": "RELEASED",
  "released_by": "user_greg@thewardn.ai",
  "released_at": "2026-04-10T14:18:33Z",
  "reason": "Reviewed and approved. Pricing update aligns with Q2 pricing sheet from finance team.",
  "action_result": {
    "executed": true,
    "execution_time_ms": 234,
    "affected_rows": 847
  },
  "audit_seq": 10848
}

POST /escrow/:id/kill

Kill (reject) a held action. The action will not execute.

Path Parameters

Parameter	Type	Description
`id`	`string`	Escrow item ID

Request Body

Field	Type	Required	Description
`reason`	`string`	Yes	Reason for rejection (recorded in audit trail)

Example Request

bash

curl -X POST https://api.thewardn.ai/escrow/esc_1e5f6g7h/kill \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Action not authorized. Deployment window is Saturday 2am-6am only."
  }'

Example Response

json

{
  "id": "esc_1e5f6g7h",
  "status": "KILLED",
  "killed_by": "user_greg@thewardn.ai",
  "killed_at": "2026-04-10T14:20:15Z",
  "reason": "Action not authorized. Deployment window is Saturday 2am-6am only.",
  "audit_seq": 10849
}

Timed-Out Escrow Item

When an escrow item expires without a decision, it is automatically killed (fail-closed).

Example — Timed Out Record

json

{
  "id": "esc_9x8y7z6w",
  "status": "TIMED_OUT",
  "agent_id": "agent_etl_runner",
  "action": {
    "type": "DELETE",
    "target": "staging_tmp_tables",
    "environment": "staging",
    "payload_summary": "Drop 12 temporary tables from staging"
  },
  "confidence": 0.65,
  "policies_fired": [
    {
      "policy_id": "pol_4d7e9f0a",
      "policy_name": "Block DELETE Actions",
      "policy_type": "action_type_block",
      "reason": "DELETE actions require explicit human approval"
    }
  ],
  "countdown": {
    "started_at": "2026-04-10T02:00:00Z",
    "expires_at": "2026-04-10T02:30:00Z",
    "ttl_seconds": 1800,
    "remaining_seconds": 0
  },
  "reasoning": "Routine cleanup of temporary ETL tables from overnight batch.",
  "timed_out_at": "2026-04-10T02:30:00Z",
  "audit_seq": 10822
}

TIP

To prevent legitimate actions from timing out, configure appropriate TTL values in your policies and ensure operator coverage during automated action windows.

Escrow API ​

Endpoints ​

Escrow Statuses ​

GET /escrow ​

Query Parameters ​

Example Request ​

Example Response ​

GET /escrow/:id ​

Path Parameters ​

Example Request ​

Example Response ​

POST /escrow/:id/release ​

Path Parameters ​

Request Body ​

Example Request ​

Example Response ​

POST /escrow/:id/kill ​

Path Parameters ​

Request Body ​

Example Request ​

Example Response ​

Timed-Out Escrow Item ​

Example — Timed Out Record ​

Escrow API

Endpoints

Escrow Statuses

GET /escrow

Query Parameters

Example Request

Example Response

GET /escrow/:id

Path Parameters

Example Request

Example Response

POST /escrow/:id/release

Path Parameters

Request Body

Example Request

Example Response

POST /escrow/:id/kill

Path Parameters

Request Body

Example Request

Example Response

Timed-Out Escrow Item

Example — Timed Out Record