Skip to content
Engram Docs

List vaults

GET
/vaults
curl --request GET \
  --url https://api.engram.page/vaults \
  --header 'Authorization: Bearer <token>'

Lists the user’s active vaults with their note and attachment counts. Pass deleted=true to list soft-deleted vaults instead, or user_code to also report user_code_valid and a suggested_vault_name for an in-progress device link.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
deleted
string

Pass “true” to list soft-deleted vaults instead of active ones.

user_code
string

Device-link user code; echoes a suggested_vault_name.

Responses

Section titled “Responses”

200

Section titled “200”

Vaults

Media typeapplication/json
VaultsResponse
object
access_levels

True when this server supports per-vault access levels and mcp:read on OAuth grants and API keys. Absent on servers that predate them.

boolean
suggested_device_name

Present only when a user_code query param is supplied. The name the plugin suggested for its device (hostname or platform), for a default connection label. Null when the code is invalid or the plugin sent none.

string
nullable
suggested_vault_name

Present only when a user_code query param is supplied (device-link flow). May be null for a perfectly valid code — check user_code_valid, not this.

string
nullable
user_code_valid

Present only when a user_code query param is supplied. True when the code is real, still pending, unexpired, and claimable by the calling user. This is the validity signal; a null suggested_vault_name is not.

boolean
vaults
required
Array<object>
Vault
object
attachment_count
integer
created_at
string format: date-time
nullable
deleted_at
string format: date-time
nullable
encrypted

Always true — vaults are encrypted at rest.

boolean
id
required
string format: uuid
is_default
boolean
name
required
string
note_count
integer
populated

True once the vault holds a note other than the seeded welcome note (the moment the vault_populated event fires).

boolean
purge_at

When a soft-deleted vault is hard-purged (deleted_at + 30d).

string format: date-time
nullable
slug
string
nullable

Example generated

{
  "access_levels": true,
  "suggested_device_name": "example",
  "suggested_vault_name": "example",
  "user_code_valid": true,
  "vaults": [
    {
      "attachment_count": 1,
      "created_at": "2026-04-15T12:00:00Z",
      "deleted_at": "2026-04-15T12:00:00Z",
      "encrypted": true,
      "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "is_default": true,
      "name": "example",
      "note_count": 1,
      "populated": true,
      "purge_at": "2026-04-15T12:00:00Z",
      "slug": "example"
    }
  ]
}