---
title: "Register or fetch a vault by client_id (idempotent)"
method: POST
path: "/api/vaults/register"
tags: ["Vaults"]
---

# Register or fetch a vault by client_id (idempotent)

`POST /api/vaults/register`

## Request

- Base URL: `https://api.engram.page`
- URL: `https://api.engram.page/api/vaults/register`
- Auth: HTTP bearer

Used by the plugin on first sync. Returns 201 with `status: created` for a new vault, or 200 with `status: existing` when the client_id already maps to one.

## Request body

- RegisterVaultRequest
  - `client_id` string, required: Client-generated stable vault id.
  - `name` string, required

## Response `200`

Existing vault

- RegisterVaultResponse
  - `attachment_count` integer
  - `created_at` string, date-time, nullable
  - `deleted_at` string, date-time, nullable
  - `encrypted` boolean: Always true — vaults are encrypted at rest.
  - `id` string, uuid, required
  - `is_default` boolean
  - `name` string, required
  - `note_count` integer
  - `populated` boolean: True once the vault holds a note other than the seeded welcome note (the moment the `vault_populated` event fires).
  - `purge_at` string, date-time, nullable: When a soft-deleted vault is hard-purged (deleted_at + 30d).
  - `slug` string, nullable
  - `status` 'created' | 'existing'

## Other responses

- `201`: Newly created vault
- `400`: name and client_id are required
- `402`: Vault cap reached
- `403`: Vault outside the credential's scope, or creation by a credential whose new-vaults policy is not write (a vault-restricted, read-level or `mcp:read` credential)
- `422`: Validation error

---

[API](https://skmtc.dev/engram/apis/engram-api.md) · [All operations](https://skmtc.dev/engram/apis/engram-api/llms.txt) · [OpenAPI document](https://skmtc.dev/engram/apis/engram-api/revisions/8c4c2eec29dc?raw)