SENTINEL REST API

Source of truth

This page mirrors docs/sentinel/rest-api.md in the sipher repo. For the latest, always check the source. Last synced: 2026-06-06.

All endpoints live under /api/sentinel. JWT-based auth via Authorization: Bearer <token>.

• Public routes require verifyJwt only.
• Admin routes require verifyJwt + requireOwner — wallet must appear in AUTHORIZED_WALLETS env var.

Error Envelope

All SENTINEL routes that emit errors return a structured envelope:

{ "error": { "code": "<CODE>", "message": "<human-readable>" } }

| Code | HTTP status | Meaning | |---|---|---| | VALIDATION_FAILED | 400 | Required fields missing or malformed | | NOT_FOUND | 404 | Resource ID does not exist | | FORBIDDEN | 403 | Reserved (auth middleware emits its own legacy shape today) | | UNAVAILABLE | 503 | Server up but a dependency is unconfigured | | INTERNAL | 500 | Unexpected server-side failure |

Note on auth errors: 401/403 responses from verifyJwt and requireOwner middleware still use the legacy {error: "string"} shape. Normalizing those is tracked separately as a future API-wide cleanup.

---

Public Endpoints

POST /api/sentinel/assess

Auth: verifyJwt

Description: Run a one-shot risk assessment for a proposed action. Used by external integrators or internal callers that want a verdict without committing to execution. The SENTINEL assessor (a Pi-SDK LLM agent) evaluates the action context and returns a structured RiskReport.

Request body:

{
  "action": "string (required)",
  "wallet": "string (required)",
  "recipient": "string (optional)",
  "amount": "number (optional)",
  "token": "string (optional)",
  "metadata": "object (optional)"
}

Response 200 — RiskReport:

{
  "risk": "high",
  "score": 100,
  "reasons": [
    "SENTINEL output failed schema validation"
  ],
  "recommendation": "block",
  "blockers": [
    "schema-violation"
  ],
  "decisionId": "01KQP24PG0KZCJVWJDQM8H3JAY",
  "durationMs": 440
}

Note

The captured response above shows the schema-validation fallback path — triggered when the LLM’s output fails JSON schema validation (or when OPENROUTER_API_KEY / SENTINEL_MODEL is unconfigured locally). Production agents with a valid model configured return a fully-evaluated RiskReport with the LLM’s actual risk / score / reasons / recommendation. Both paths use the same response shape; the decisionId is always a ULID and durationMs is always present.

Response 400:

{ "error": { "code": "VALIDATION_FAILED", "message": "action and wallet are required strings" } }

Returned when action or wallet is missing or not a string.

Response 500:

{ "error": { "code": "INTERNAL", "message": "<error message from assessor>" } }

Returned when the assessor throws an unexpected error.

Response 503:

{ "error": { "code": "UNAVAILABLE", "message": "SENTINEL assessor not configured" } }

Only returned when no assessor is registered at startup. Production agents always register one via setSentinelAssessor, so this path is rarely hit in deployed environments.

Example:

curl -X POST http://localhost:5006/api/sentinel/assess \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "vault_refund",
    "wallet": "C1phrE76Wrkmt1GP6Aa9RjCeLDKHZ7p4MPVRuPa8x85N",
    "amount": 1.5
  }'

---

GET /api/sentinel/blacklist

Auth: verifyJwt

Description: List blacklisted addresses. Soft-removed entries (where removed_at is set) are filtered out by default.

Query params:

| Param | Type | Default | Description | |-------|------|---------|-------------| | limit | number | 50 | Maximum entries to return |

Response 200:

{
  "entries": []
}

Note

The captured response shows an empty array — this is a fresh local DB with no blacklist entries. In production the array contains objects with fields: id, address, reason, severity, added_by, added_at, expires_at, source_event_id. Schema detail in the audit log.

Example:

curl -H "Authorization: Bearer $JWT" \
  "http://localhost:5006/api/sentinel/blacklist?limit=50"

---

GET /api/sentinel/pending

Auth: verifyJwt

Description: List queued circuit-breaker pending actions (SQLite-backed). Optionally filter by wallet or status.

Query params:

| Param | Type | Default | Description | |-------|------|---------|-------------| | wallet | string | — | Filter by originating wallet address | | status | string | — | Filter by action status — lifecycle is pending → executing → executed | cancelled |

Response 200:

{
  "actions": []
}

Note

The captured response shows an empty array — fresh local DB. In production the array contains objects with fields: id, tool, args, wallet, status, reason, created_at, resolved_at. Schema detail in the audit log.

Example:

curl -H "Authorization: Bearer $JWT" \
  "http://localhost:5006/api/sentinel/pending?wallet=C1phrE76Wrkmt1GP6Aa9RjCeLDKHZ7p4MPVRuPa8x85N&status=pending"

---

GET /api/sentinel/status

Auth: verifyJwt

Description: SENTINEL runtime status snapshot — current mode, preflight scope, configured model, daily LLM cost accrued, and daily budget ceiling.

Response 200:

{
  "mode": "advisory",
  "preflightScope": "fund-actions",
  "model": "openrouter:anthropic/claude-sonnet-4.6",
  "dailyBudgetUsd": 10,
  "dailyCostUsd": 0,
  "blockOnError": false
}

| Field | Type | Description | |-------|------|-------------| | mode | "yolo" | "advisory" | "off" | Current operating mode | | preflightScope | string | Which tool categories trigger the preflight gate | | model | string | LLM model identifier used for assessments | | dailyBudgetUsd | number | Maximum daily spend allowed for LLM calls | | dailyCostUsd | number | Actual spend accumulated today (UTC) | | blockOnError | boolean | Whether assessment errors cause the action to be blocked |

Example:

curl -H "Authorization: Bearer $JWT" \
  http://localhost:5006/api/sentinel/status

---

Admin Endpoints

Admin routes require both verifyJwt AND requireOwner middleware. The calling wallet must appear in the AUTHORIZED_WALLETS environment variable (comma-separated list).

POST /api/sentinel/blacklist

Auth: verifyJwt + requireOwner

Description: Insert a new blacklist entry. The added_by field is set to admin:<wallet> using the verified wallet from the JWT, or admin if no wallet is present.

Request body:

{
  "address": "string (required)",
  "reason": "string (required)",
  "severity": "string (required)",
  "expiresAt": "string (optional, ISO 8601 timestamp)",
  "sourceEventId": "string (optional)"
}

Response 200:

{
  "success": true,
  "entryId": "01KQP25BM8RVZJ92CTANFDNTMG"
}

entryId is a ULID generated by the SQLite insert.

Response 400:

{ "error": { "code": "VALIDATION_FAILED", "message": "address, reason, severity required" } }

Example:

curl -X POST http://localhost:5006/api/sentinel/blacklist \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "BadActor11111111111111111111111111111111111",
    "reason": "Flagged by SENTINEL risk assessment",
    "severity": "high"
  }'

---

DELETE /api/sentinel/blacklist/:id

Auth: verifyJwt + requireOwner

Description: Soft-remove a blacklist entry. Sets removed_at, removed_by, and removed_reason columns. The row is not deleted from SQLite — it is retained for audit purposes and filtered from GET /blacklist responses.

Path params:

| Param | Type | Description | |-------|------|-------------| | id | string | ULID of the blacklist entry to remove |

Request body (optional):

{ "reason": "string (default: 'manual removal')" }

Response 200:

{
  "success": true
}

Example:

curl -X DELETE http://localhost:5006/api/sentinel/blacklist/01KQP25BM8RVZJ92CTANFDNTMG \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "false positive, cleared by review" }'

---

POST /api/sentinel/circuit-breaker/:id/cancel

Auth: verifyJwt + requireOwner

Description: Cancel a circuit-breaker pending action (SQLite-backed). Calls cancelCircuitBreakerAction in packages/agent/src/sentinel/circuit-breaker.ts. The cancelled_by field is set to user:<wallet> from the JWT, or admin if unavailable.

Path params:

| Param | Type | Description | |-------|------|-------------| | id | string | ULID of the circuit-breaker pending action |

Request body (optional):

{ "reason": "string (default: 'manual cancel')" }

Response 200:

{ "success": true }

Returned when the action ID exists and was cancelled.

Response 404:

{ "error": { "code": "NOT_FOUND", "message": "pending action not found or already resolved" } }

Returned when the action ID does not exist or is already settled. A missing or already-resolved action returns this 404 envelope (not 200 + {success: false}).

Example:

curl -X POST http://localhost:5006/api/sentinel/circuit-breaker/01KQP25BM8RVZJ92CTANFDNTMG/cancel \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "admin override, action no longer needed" }'

---

GET /api/sentinel/decisions

Auth: verifyJwt + requireOwner

Description: List recent SENTINEL decisions — the assessment outcomes recorded each time SENTINEL evaluated an action. Optionally filter by source.

Query params:

| Param | Type | Default | Description | |-------|------|---------|-------------| | limit | number | 50 | Maximum decisions to return | | source | string | — | Filter by source label (e.g., agent, scanner, assess) |

Response 200:

{
  "decisions": []
}

Note

The captured response shows an empty array — fresh local DB. In production each decision object contains: id (ULID), action, wallet, risk, score, recommendation, reasons (JSON array), source, cost_usd, duration_ms, created_at. Schema detail in the audit log.

Example:

curl -H "Authorization: Bearer $JWT" \
  "http://localhost:5006/api/sentinel/decisions?limit=20&source=agent"

---

GET /api/sentinel/config

Auth: verifyJwt + requireOwner

Description: Return the current SENTINEL configuration snapshot — operating mode, preflight scope/thresholds, blacklistAutonomy, rate limits, scan intervals, autoRefundThreshold, model, dailyBudgetUsd, accrued dailyCostUsd, blockOnError, and the fundMovingTools list. See Configuration for what each field controls.

Response 200:

{
  "mode": "advisory",
  "preflightScope": "fund-moving",
  "blacklistAutonomy": true,
  "model": "openrouter:anthropic/claude-sonnet-4.6",
  "dailyBudgetUsd": 10,
  "dailyCostUsd": 0,
  "blockOnError": false,
  "fundMovingTools": ["executeRefund", "addToBlacklist"]
}

Note

Response includes the full config (mode, preflight scope/skip-amount, large-transfer threshold, threat-check flag, cancel window, per-hour rate limits, scan intervals, auto-refund threshold, model, daily budget/cost, block-on-error). The example is abbreviated.

Example:

curl -H "Authorization: Bearer $JWT" \
  http://localhost:5006/api/sentinel/config

---

POST /api/sentinel/promise-gate/:flagId/resolve

Auth: verifyJwt + requireOwner

Description: Resolve a pending in-memory promise-gate flag — the admin approval path when SENTINEL is in advisory mode and has paused an action for human review. Calls resolvePending(flagId) in packages/agent/src/sentinel/pending.ts.

Path params:

| Param | Type | Description | |-------|------|-------------| | flagId | string | ID of the in-memory pending promise-gate flag |

Response 204: No body — flag was found and resolved. The paused agent tool call proceeds.

Response 404:

{ "error": { "code": "NOT_FOUND", "message": "flag not found or expired" } }

Returned when no in-memory flag exists for the given flagId. Flags expire when the waiting agent times out.

Example:

curl -X POST http://localhost:5006/api/sentinel/promise-gate/flag_01KQP24PG0KZCJVWJDQM8H3JAY/resolve \
  -H "Authorization: Bearer $JWT"

---

POST /api/sentinel/promise-gate/:flagId/reject

Auth: verifyJwt + requireOwner

Description: Reject a pending in-memory promise-gate flag — the admin denial path when SENTINEL is in advisory mode and has paused an action. Calls rejectPending(flagId, 'cancelled_by_user') in packages/agent/src/sentinel/pending.ts. The paused tool call receives a rejection and the agent aborts the action.

Path params:

| Param | Type | Description | |-------|------|-------------| | flagId | string | ID of the in-memory pending promise-gate flag |

Response 204: No body — flag was found and rejected. The paused agent tool call receives a rejection error.

Response 404:

{ "error": { "code": "NOT_FOUND", "message": "flag not found or expired" } }

Returned when no in-memory flag exists for the given flagId.

Example:

curl -X POST http://localhost:5006/api/sentinel/promise-gate/flag_01KQP24PG0KZCJVWJDQM8H3JAY/reject \
  -H "Authorization: Bearer $JWT"