Register or fetch a vault by client_id (idempotent)

POST

/vaults/register

curl --request POST \
  --url https://api.engram.page/vaults/register \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "client_id": "obsidian-9f1b2c3d4e5f", "name": "My Vault" }'

• Production

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.

Authorizations

• bearerAuth

Request Body^required

Name + client_id

Media typeapplication/json

RegisterVaultRequest

object

client_id

required

Client-generated stable vault id.

string

name

required

string

Example

{
  "client_id": "obsidian-9f1b2c3d4e5f",
  "name": "My Vault"
}

Responses

200

Existing vault

Media typeapplication/json

RegisterVaultResponse

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

status

string

Allowed values: created existing

Example

{
  "status": "created"
}

201

Newly created vault

Media typeapplication/json

RegisterVaultResponse

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

status

string

Allowed values: created existing

Example

{
  "status": "created"
}

400

Name and client_id are required

Media typeapplication/json

MessageError

object

error

required

string

Example

{
  "error": "not found"
}

402

Vault cap reached

Media typeapplication/json

LimitError

object

current

integer

nullable

error

required

string

limit

One of:

integer

integer

boolean

boolean

limit_key

string

nullable

reason

required

string

tier

string

nullable

upgrade_url

string

nullable

Example

{
  "error": "limit_exceeded",
  "limit_key": "vaults_cap",
  "reason": "vaults_cap_exceeded",
  "tier": "free"
}

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)

Media typeapplication/json

MessageError

object

error

required

string

Example

{
  "error": "not found"
}

422

Validation error

Media typeapplication/json

Error

object

errors

One of:

string

string

object

object

Example ^generated

{
  "errors": {}
}