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. |