---
title: "Vault presence and lock state"
method: GET
path: "/v1/vault/status"
tags: ["Vault"]
---

# Vault presence and lock state

`GET /v1/vault/status`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/vault/status`
- Auth: HTTP bearer

Reports whether a vault exists on disk (`vault-keys.json` present) and
whether it is currently unlocked (a VMK loaded). The one vault read
that never answers 423 — it is what tells the web surface to show the
unlock gate. Unlocking itself is native-only (ToolPiper UI); there is
deliberately no unlock/init/change-passphrase route.

## Response `200`

Vault status

- WireVaultStatus: Vault presence and lock state, also carried by the `vault.changed` SSE event's consumers via re-fetch.
  - `hasVault` boolean, required: True once a vault exists on disk (`vault-keys.json` present).
  - `locked` boolean, required: True while no VMK is loaded; content routes then answer 423 vault_locked.
  - `unlockedSince` integer, nullable: Epoch milliseconds when the vault was last unlocked, or null while locked. Advisory only.

## Other responses

- `503`: Vault service unavailable

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)