Skip to content

Vault

The vault as an API key or a connected tool reaches it. Each holds permissions from the catalogue (GET /api/permissions) and a reach: the sections chosen for it, or for an assistant the owner runs on their own machine, the whole vault. Reach is checked on every request, so a record taken out of a section is out of reach at once. Encrypted records are never served.

GET /api/vault

List the records within reach

Auth: ApiKey, Connection

The records a key or tool may read, without values: those in its sections, or for a whole-vault connection the owner's own records. Encrypted records, and answers others sent, are left out. writable says whether this key or tool wrote the record and may change it; writtenByName names whoever wrote one.

Responses

Status Meaning
200 The records.
401 not_authenticated, connection_unauthorized or connection_expired.
403 vault_not_allowed (a key without vault access), connection_vault_not_allowed, connection_vault_polled, or connection_paused.
429 rate_limited: 120 reads a minute by default (RATELIMIT_CONNECTION_VAULT_READS).

Response fields

Field Type Notes
records array of object

POST /api/vault

Write a record

Auth: ApiKey, Connection

Creates a record in a section the key or tool may write to: a tool's own section, or one of a key's sections (section, default the first). Needs vault:write. Send JSON, or multipart/form-data with the bytes in file for a file record. The record is the owner's and is marked as written by this key or tool. Its values and files count against CONNECTION_STORAGE_MB (default 100, 0 for no cap). Audited without the value.

Request body

application/json

Field Type Notes
key string
label string
type string Left out: text, or file with an upload.
format string (default | hidden)
value string
section string

multipart/form-data

Field Type Notes
key string
label string
filename string
section string
file string

Responses

Status Meaning
201 The record, without its value.
400 A field failed validation.
403 vault_section_not_writable.
409 vault_key_taken.
413 vault_storage_exceeded.

GET /api/vault/{id}

Read one record

Auth: ApiKey, Connection

One record within reach with its current value; an alias reads through to its entry. A file record gives filename, mime and size; its bytes are at /api/vault/{id}/file. Each read is in the owner's audit log by key.

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
200 The record and its value.
404 record_not_found: out of reach, encrypted, or missing.

PATCH /api/vault/{id}

Change a record it wrote

Auth: ApiKey, Connection

Changes key, label, non-file type, format, value, filename or the uploaded file of a record this key or tool wrote. A record the owner put in its section is read-only to it.

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
200 The record, without its value.
403 vault_read_only or vault_section_not_writable.
404 record_not_found.

DELETE /api/vault/{id}

Delete a record it wrote

Auth: ApiKey, Connection

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
204 Deleted.
403 vault_read_only or vault_section_not_writable.
404 record_not_found.

GET /api/vault/{id}/file

Download a file record

Auth: ApiKey, Connection

Always an attachment, never sniffed.

Parameters

Name In Required Notes
id path yes

Responses

Status Meaning
200 The file.
404 record_not_found.