# Model Context Protocol (MCP)

Connect your AI assistant to Monica to find contacts, add people, and manage favourites through conversation.

Monica’s MCP server gives compatible assistants access to tools that work with your account.

Server address: `https://my.monicahq.com/mcp`

## Set up Monica MCP

An assistant connects in one of two ways. If it supports OAuth, give it the server address and it sends you to Monica to sign in. Monica shows the name the assistant gives itself and the address it sends you back to, and connects it only when you choose **Allow**. No key is needed.

Otherwise, create an API key in **Settings → Security and access → API keys**. Under **What will use this key**, choose **AI Assistant** and give the key a recognisable name. Copy the key when it appears. Use a separate key for each assistant so you can revoke its access independently.

### Claude Code

Set the `MONICA_API_KEY` environment variable to your Monica API key before starting Claude Code.

Add this configuration to your project’s `.mcp.json`. If the file already contains servers, add `monica` to the existing `mcpServers` object.

```json
{
  "mcpServers": {
    "monica": {
      "type": "http",
      "url": "https://my.monicahq.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MONICA_API_KEY}"
      }
    }
  }
}
```

Start Claude Code from that environment, approve the project’s MCP configuration when prompted, and use `/mcp` to check the connection.

### Cursor

Make `MONICA_API_KEY` available in Cursor’s environment, then add this configuration to `~/.cursor/mcp.json`.

```json
{
  "mcpServers": {
    "monica": {
      "url": "https://my.monicahq.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MONICA_API_KEY}"
      }
    }
  }
}
```

Cursor reads the variable as `${env:MONICA_API_KEY}`, with the `env:` prefix. Restart Cursor after changing its environment, then check that Monica appears in its MCP settings.

### Codex

Set `MONICA_API_KEY` in the environment where you run Codex, then run:

```bash
codex mcp add monica \
  --url https://my.monicahq.com/mcp \
  --bearer-token-env-var MONICA_API_KEY
```

Or add the server to `~/.codex/config.toml`:

```toml
[mcp_servers.monica]
url = "https://my.monicahq.com/mcp"
bearer_token_env_var = "MONICA_API_KEY"
```

Restart Codex after configuration. If you use the desktop app, make sure the variable is available to the app’s process, not only to a terminal.

### VS Code

Run **MCP: Open User Configuration** from the Command Palette and add:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "monica-api-key",
      "description": "Monica API key",
      "password": true
    }
  ],
  "servers": {
    "monica": {
      "type": "http",
      "url": "https://my.monicahq.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:monica-api-key}"
      }
    }
  }
}
```

Start the server and enter your API key when prompted. VS Code stores it securely.

**Not available in Agent Host.** VS Code does not forward a server that asks for input to Agent Host sessions, so this configuration does not reach them.

### Claude Desktop

Add a custom connector with the server address below. Claude opens Monica in your browser: sign in if you are asked to, check the name and the address on the screen, and choose **Allow**. No API key is needed.

```text
https://my.monicahq.com/mcp
```

### ChatGPT

Add a custom connector with the server address below and choose OAuth as its authentication. ChatGPT opens Monica in your browser: sign in if you are asked to, check the name and the address on the screen, and choose **Allow**. Whether custom connectors are offered depends on your ChatGPT plan and settings.

```text
https://my.monicahq.com/mcp
```

### Other

Use a client that supports remote HTTP MCP servers. If it supports OAuth, give it the server address alone and allow it when Monica asks. Otherwise, send an API key in a header:

```text
Server URL: https://my.monicahq.com/mcp
Header: Authorization: Bearer YOUR_API_KEY
```

## Check your connection

Ask your assistant:

- “List my Monica vaults.” Confirm that the returned vaults belong to your account.
- “Find Alice in my Personal vault.” An empty result is fine. What matters is that the call succeeds against the right account.

## Manage access

Your assistant acts as you, through its API key or its OAuth connection. Changes made through MCP are recorded in **Settings → Logs**, under the assistant’s name.

To disconnect an assistant connected through OAuth, choose **Disconnect** beside it in **Settings → Security and access → Connected assistants**. To disconnect one using a key, revoke its key in **Settings → Security and access → API keys**. Either takes effect at once.

**Your assistant can access all your vaults.** Your assistant can use every tool in every vault in your account, whether it connects with a key or through OAuth. Choosing “AI Assistant” when creating an API key only labels the key—it does not limit what your assistant can access or change.

## Available tools

### Vaults

#### `list-vaults`

List the vaults of the account, the compartments its contacts are filed in, a page at a time.

- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many vaults a page holds: 25 unless asked, 100 at most.

### Search

#### `search-records`

Search the people, entities and life events of a vault, or of every vault, for every word given, typing mistakes tolerated. The results come back in result groups, one per kind of record.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `query` (string, required): The words to find, at least two characters.
- `scope` (string, optional): vault to search that vault, account to search every vault of the account. vault when left out. One of: `vault`, `account`.
- `group` (string, optional): One result group only, by the key an earlier answer of search-records gave it.
- `page` (integer, optional): The page of each result group to read, starting at 1.
- `per_page` (integer, optional): How many results a result group holds per page: 25 unless asked, 100 at most.

### Contacts

#### `list-contacts`

List the contacts of one vault, a page at a time, optionally narrowed by a search, a grouping or contact categories. Each contact comes with the columns the vault shows in its list.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `query` (string, optional): Words to search the contacts of the vault for.
- `filter` (string, optional): Only the contacts of one grouping. One of: `all`, `favourites`, `names-only`.
- `sort` (string, optional): What the list is ordered by. One of: `name`, `nickname`, `last-spoke`, `added`.
- `direction` (string, optional): The direction of the order. One of: `asc`, `desc`.
- `categories` (array, optional): The ids of contact categories, as list-contact-categories gives them; only the people holding any of them.
- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many contacts a page holds: 25 unless asked, 100 at most.

#### `list-contact-categories`

List the contact categories held by the contacts of a vault, with how many contacts hold each. The id of a category is what list-contacts takes in categories.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `filter` (string, optional): Count only the contacts of one grouping, as list-contacts narrows them. Every contact when left out. One of: `all`, `favourites`, `names-only`.

#### `get-contact` (changes data)

Look one contact up in a vault.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `contact` (string, required): The id of the contact, as list-contacts gives it.

#### `get-contact-markdown` (changes data)

Return everything recorded about one contact as a single Markdown document: names, fields, relationships, life events, groups, reminders and loans. The values of sensitive fields are given only to a key holding the sensitive fields scope. The export is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `contact` (string, required): The id of the contact, as list-contacts gives it.

#### `get-me-contact`

Look up the contact that stands for the account holder in a vault.

- `vault` (string, required): The id of the vault, as list-vaults gives it.

#### `list-contact-name-representations`

List every way the name of a contact is written: in its own script, transliterated, or as it is pronounced, and which one it is shown under.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `contact` (string, required): The id of the contact, as list-contacts gives it.

#### `create-contact` (changes data)

Record a new contact in a vault. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `first_name` (string, required): Their given name, the one part a contact cannot go without.
- `prefix` (string, optional): What comes before the name, such as Dr.
- `middle_name` (string, optional): Their middle name.
- `last_name` (string, optional): Their family name.
- `suffix` (string, optional): What comes after the name, such as Jr.
- `maiden_name` (string, optional): Their name before marriage.
- `nickname` (string, optional): What they are actually called.
- `name_order` (string, optional): Which part of the name reads first. Left out, the reader decides. One of: `given_first`, `family_first`.
- `is_partial` (boolean, optional): True for somebody you know of rather than somebody you have written down. A partial contact is off every list until they are more than a first name. False when left out.
- `is_favourite` (boolean, optional): True to put the contact at the top of the list. False when left out.
- `structure_version_id` (integer, optional): The id of the published version of one of your active contact templates, as list-template-versions gives it, which says what the page of the contact holds. Left out, the contact starts from the template the vault uses for new contacts.

#### `update-contact-name` (changes data)

Correct the name of a contact. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `contact` (string, required): The id of the contact, as list-contacts gives it.
- `prefix` (string, optional): What comes before the name, such as Dr.
- `first_name` (string, optional): Their given name.
- `middle_name` (string, optional): Their middle name.
- `last_name` (string, optional): Their family name.
- `suffix` (string, optional): What comes after the name, such as Jr.
- `maiden_name` (string, optional): Their name before marriage.
- `nickname` (string, optional): What they are actually called.
- `name_order` (string, optional): Which part of the name reads first. One of: `given_first`, `family_first`.

#### `update-contact-name-representations` (changes data)

Replace every way the name of a contact is written, and choose the one it is shown under. A way left out of the list is deleted. Nothing is transliterated for you. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `contact` (string, required): The id of the contact, as list-contacts gives it.
- `name_representations` (array, optional): Every way the name is written, in order. Each: id (to keep an existing one, as list-contact-name-representations gives it), kind (written, transliteration or phonetic), language (a BCP 47 tag such as ko), script (an ISO 15924 code such as Hang or Latn), phonetic_system (required for phonetic, such as ipa or piny), formatted_name, prefix, given_name, additional_name, family_name, suffix, name_order (given_first or family_first). Each needs a formatted_name or at least one part. A phonetic one holds parts only, never a formatted_name, and cannot be the one displayed.
- `display` (integer, optional): The position in name_representations, from 0, of the way the contact is shown under. Required with name_representations, unless that list is empty.
- `nickname` (string, optional): What they are actually called.
- `maiden_name` (string, optional): Their name before marriage.

#### `set-contact-favourite` (changes data)

Mark a contact as a favourite, or stop marking them one.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `contact` (string, required): The id of the contact, as list-contacts gives it.
- `favourite` (boolean, required): True to mark them a favourite, false to stop.

### Reminders

#### `list-vault-reminders`

List every reminder of a vault, about its contacts and its groups, whatever its date: what it says, whom it is about, how often it comes back and its next date. Use it to answer "what are my reminders". To know what falls in the coming days instead, use list-vault-reminder-occurrences.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `about` (string, optional): Only the reminders about contacts, or only those about groups. Both when left out. One of: `contact`, `group`.
- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many reminders a page holds: 25 unless asked, 100 at most.

#### `list-vault-reminder-occurrences`

List the dates of a whole vault that fall in a window: what is overdue, what falls today and what comes in the next 7 days unless days asks for more (up to 365), for every contact, group and record of the vault, as the vault dashboard shows them. An empty list means nothing falls in that window, not that the vault has no reminders: list-vault-reminders lists every reminder whatever its date. Ask kind=birthdays to know whose birthday it is today or soon: it also lists the birthdays nobody asked to be reminded of, with the age being reached when the year of birth is known.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `category` (string, optional): Only one kind of date: overdue, today, upcoming or history. Overdue, today and upcoming together when left out. One of: `upcoming`, `today`, `overdue`, `history`.
- `kind` (string, optional): all for every reminder, birthdays for birthdays only. all when left out. One of: `all`, `birthdays`.
- `days` (integer, optional): How many days ahead upcoming reaches, from 1 to 365. 7 when left out, as on the vault dashboard.
- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many dates a page holds: 25 unless asked, 100 at most.

#### `list-contact-reminders`

List the reminders about one contact: those written by hand with a date of their own, and those reading a date on the contact, such as a birthday.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `contact` (string, required): The id of the contact, as list-contacts gives it.
- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many reminders a page holds: 25 unless asked, 100 at most.

#### `get-contact-reminder`

Read one reminder about a contact: what it says, where its date comes from, how often it comes back and its next date.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `contact` (string, required): The id of the contact, as list-contacts gives it.
- `reminder` (string, required): The id of the reminder, as list-contact-reminders gives it.

#### `list-contact-reminder-occurrences`

List the dates the reminders about a contact produced, with what the user answered for each: remembered, forgotten, or no answer. A missing answer never means forgotten, and a notification sent or read never means remembered.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `contact` (string, required): The id of the contact, as list-contacts gives it.
- `category` (string, optional): Only one kind of date: overdue, today, upcoming or history. Every date, newest first, when left out. One of: `upcoming`, `today`, `overdue`, `history`.
- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many dates a page holds: 25 unless asked, 100 at most.

#### `create-contact-reminder` (changes data)

Write a reminder about a contact with a date of its own. It is notified on its day, once on each channel the account switched on, and never ahead of it. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `contact` (string, required): The id of the contact, as list-contacts gives it.
- `name` (string, required): What the reminder says.
- `starts_on` (string, required): The first date, as YYYY-MM-DD. It cannot be before today.
- `cadence` (string, required): How often the reminder comes back. One of: `once`, `weekly`, `monthly`, `yearly`.
- `interval` (integer, optional): The number of cadence units between two dates, from 1 to 99: cadence weekly with interval 2 means every two weeks.
- `time` (string, required): The local time the reminder is notified at, as HH:MM.
- `timezone` (string, optional): The time zone the time is read in. The user's own when left out.

#### `update-contact-reminder` (changes data)

Change what a reminder about a contact says and when it comes back. Dates after today that nobody answered are replaced. Answers already given never change. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `contact` (string, required): The id of the contact, as list-contacts gives it.
- `reminder` (string, required): The id of the reminder, as list-contact-reminders gives it.
- `name` (string, optional): What the reminder says.
- `starts_on` (string, optional): A new first date, as YYYY-MM-DD, for a reminder written by hand only.
- `cadence` (string, optional): How often the reminder comes back. One of: `once`, `weekly`, `monthly`, `yearly`.
- `interval` (integer, optional): The number of cadence units between two dates, from 1 to 99: cadence weekly with interval 2 means every two weeks.
- `time` (string, optional): The local time the reminder is notified at, as HH:MM.
- `timezone` (string, optional): The time zone the time is read in.

#### `delete-contact-reminder` (changes data)

Stop a reminder about a contact for good. There is no pause. Dates still waiting for an answer are dropped. Answers already given are kept. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `contact` (string, required): The id of the contact, as list-contacts gives it.
- `reminder` (string, required): The id of the reminder, as list-contact-reminders gives it.

#### `answer-reminder-occurrence` (changes data)

Record, on the user's word, whether they remembered one reminder date or forgot it. remembered is accepted from the date's day, forgotten from the day after. The answer is final and cannot be changed. Only record what the user said. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `contact` (string, required): The id of the contact, as list-contacts gives it.
- `occurrence` (string, required): The id of the date, as list-contact-reminder-occurrences gives it.
- `answer` (string, required): Whether the user remembered the date or forgot it. One of: `remembered`, `forgotten`.

### Relationships

#### `list-contact-relationships`

List the relationships of one contact, from either side, a page at a time: the type, both people with the role each holds, whether it is current or ended, and its dates.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `contact` (string, required): The id of the contact, as list-contacts gives it.
- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many relationships a page holds: 25 unless asked, 100 at most.

#### `get-contact-relationship`

Read one relationship of a contact: the type, both people with the role each holds, whether it is current or ended, and its dates.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `contact` (string, required): The id of either person in the relationship, as list-contacts gives it.
- `relationship` (string, required): The id of the relationship, as list-contact-relationships gives it.

#### `create-contact-relationship` (changes data)

Add a partner, a family member or any other relative to a contact, with or without a record of their own, by linking them with a relationship type. The other person is an existing contact, a new person named here, or somebody whose name is unknown. One relationship holds both sides, so there is no reverse to add. The change is written to the account log.

- `vault` (string, required): The id of the vault holding both people, as list-vaults gives it.
- `contact` (string, required): The id of the contact the relationship is recorded from, as list-contacts gives it.
- `relationship_type` (string, required): The id of the relationship type, as list-relationship-types gives it. A type names a role for each side: role_a and role_b. A type that is symmetric gives both sides the same role, as partners do.
- `other_contact` (string, optional): The id of the other person, an existing contact of the same vault, as list-contacts gives it. Leave other_contact out to name a new person with first_name, or to record somebody whose name is unknown.
- `first_name` (string, optional): The first name of the other person when they are not a contact yet. Not allowed with other_contact.
- `last_name` (string, optional): The last name of the other person. Needs first_name.
- `creates_record` (boolean, optional): True to give the person named here a full record of their own in the vault. False when left out: they then exist only through this relationship.
- `holds_role_a` (boolean, optional): Whether the contact holds role_a of the type and the other person role_b. For parent and child, where role_a is parent, true says the contact is the parent. True when left out. Ignored for a symmetric type.

#### `update-contact-relationship` (changes data)

Change a relationship of a contact: its type, whether it is current or ended, its dates, which side holds which role, or the name of somebody who exists only through it. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `contact` (string, required): The id of either person in the relationship, as list-contacts gives it. holds_role_a is read from the side of this person.
- `relationship` (string, required): The id of the relationship, as list-contact-relationships gives it.
- `relationship_type` (string, optional): The id of a new relationship type, as list-relationship-types gives it.
- `status` (string, optional): Whether the relationship is current or ended. Setting it back to current clears the end date. One of: `current`, `ended`.
- `started_on` (string, optional): When it started, as YYYY-MM-DD.
- `ended_on` (string, optional): When it ended, as YYYY-MM-DD, for an ended relationship. The end cannot fall before the start.
- `holds_role_a` (boolean, optional): Whether the contact holds role_a of the type and the other person role_b. For parent and child, where role_a is parent, true says the contact is the parent. Ignored for a symmetric type.
- `first_name` (string, optional): A first name for the other person, only when they exist through this relationship alone.
- `last_name` (string, optional): The last name of the other person. Needs first_name.
- `creates_record` (boolean, optional): True to give the other person, who exists through this relationship alone, a full record of their own.

#### `delete-contact-relationship` (changes data)

Delete a relationship. It leaves both contacts at once. Neither person is deleted, including somebody who existed only through it. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `contact` (string, required): The id of either person in the relationship, as list-contacts gives it.
- `relationship` (string, required): The id of the relationship, as list-contact-relationships gives it.

### Life events

#### `list-life-events`

List the life events of one vault, the most recent first, a page at a time, optionally only those one contact took part in. The values of sensitive fields are given only to a key holding the sensitive fields scope.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `contact` (string, optional): The id of a contact, as list-contacts gives it. Only the life events this contact took part in are listed.
- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many life events a page holds: 25 unless asked, 100 at most.

#### `get-life-event`

Look one life event up in a vault: its type, its date, what was written about it, who was there and the values of its custom fields, with the field ids update-life-event takes. The values of sensitive fields are given only to a key holding the sensitive fields scope.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `life_event` (string, required): The id of the life event, as list-life-events gives it.

#### `create-life-event` (changes data)

Write down something that happened, on a date, with the people who were there. It goes on the timeline of every one of them, the first being the person it is recorded for. Read the custom fields of the type with get-life-event-type-fields first: values are keyed by field id. A file field cannot be written. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `life_event_type` (string, required): The id of its type, as list-life-event-types gives it. A type switched off cannot be chosen.
- `happened_on` (string, required): The day it happened, as YYYY-MM-DD.
- `participants` (array, required): The ids of the contacts who were there, in order, as list-contacts gives them. The first is the person it is recorded for.
- `title` (string, optional): A title. Without one it is called by the name of its type.
- `narrative` (string, optional): What happened.
- `location` (string, optional): Where it happened.
- `duration_in_minutes` (integer, optional): How long it lasted, in minutes.
- `fields` (object, optional): The values of the custom fields, keyed by the field id get-life-event-type-fields gives. A select field takes the id of its choice.

#### `update-life-event` (changes data)

Change a life event. The fields given replace its custom values, except sensitive fields, which keep their value unless given. The first participant has to stay the person it is recorded for. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `life_event` (string, required): The id of the life event, as list-life-events gives it.
- `life_event_type` (string, optional): The id of another type, as list-life-event-types gives it. Choosing one moves the life event to the custom fields of that type and lets the old values go.
- `happened_on` (string, optional): The day it happened, as YYYY-MM-DD.
- `participants` (array, optional): The ids of the contacts who were there, in order, as list-contacts gives them. The list replaces the one recorded. The first has to stay the person it is recorded for.
- `title` (string, optional): A title.
- `narrative` (string, optional): What happened.
- `location` (string, optional): Where it happened.
- `duration_in_minutes` (integer, optional): How long it lasted, in minutes.
- `fields` (object, optional): Custom field values, keyed by the field id get-life-event gives. A repeating group takes a list of repetitions, each as {id, values}: the id is the row get-life-event gives, and the values are keyed by the ids of the fields inside the group.

#### `delete-life-event` (changes data)

Take a life event off the timeline of everybody who was there. restore-life-event puts it back. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `life_event` (string, required): The id of the life event, as list-life-events gives it.

#### `restore-life-event` (changes data)

Put a deleted life event back on the timeline of everybody who was there. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `life_event` (string, required): The id of the deleted life event, as list-life-events gave it.

### Templates

#### `list-templates`

List the templates of the account, the structures its records are described by.

- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many templates a page holds: 25 unless asked, 100 at most.

#### `get-template`

Read one template of the account: its name, what it describes, whether it is active and which version is published.

- `template` (string, required): The id of the template, as list-templates gives it.

#### `list-template-versions`

List the versions of one template, so a caller can tell a draft from what is published.

- `template` (string, required): The id of the template, as list-templates gives it.
- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many versions a page holds: 25 unless asked, 100 at most.

#### `get-template-version`

Read one version of a template with its pages, the sections on each page and the fields of each section. The section and field ids the other template tools take come from here.

- `template` (string, required): The id of the template, as list-templates gives it.
- `version` (integer, required): The version number, as list-template-versions gives it.

#### `list-value-lists`

List the value lists of the account, the named sets of choices a template field can offer, such as genders or phone labels, each with its choices in order. The id of a list is what create-template-field and update-template-field take as value_list_id.

- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many lists a page holds: 25 unless asked, 100 at most.

#### `create-template` (changes data)

Create a template for contacts, for a kind of entity or for life events. It starts with a first draft. The change is written to the account log.

- `name` (string, required): The name of the template.
- `applies_to` (string, required): What the template describes. One of: `contact`, `entity`, `life_event`.
- `description` (string, optional): A sentence saying what the template is for.
- `entity_type_id` (string, optional): The id of the kind of entity the template describes, as list-entity-types gives it. Required when applies_to is entity.

#### `update-template` (changes data)

Rename a template or change its description. The change is written to the account log.

- `template` (string, required): The id of the template, as list-templates gives it.
- `name` (string, optional): The new name.
- `description` (string, optional): The new description.

#### `duplicate-template` (changes data)

Copy a template into a new one, as a starting point. The change is written to the account log.

- `template` (string, required): The id of the template, as list-templates gives it.
- `name` (string, optional): The name of the copy. Made from the name of the original when left out.
- `slug` (string, optional): The short name of the copy. Made from the name of the copy when left out.

#### `set-template-activation` (changes data)

Switch a template on, so it is offered for new records, or off. The change is written to the account log.

- `template` (string, required): The id of the template, as list-templates gives it.
- `is_active` (boolean, required): True to switch the template on, false to switch it off.

#### `set-template-position` (changes data)

Move a template to another place in the list of templates. The change is written to the account log.

- `template` (string, required): The id of the template, as list-templates gives it.
- `position` (integer, required): Where the template goes in the list, counting from 1.

#### `delete-template` (changes data)

Delete a template and all its versions. A template still describing records is refused. The change is written to the account log.

- `template` (string, required): The id of the template, as list-templates gives it.

#### `create-template-draft` (changes data)

Open a draft of a template, the only kind of version whose sections and fields can change. When a draft is already open, it is returned instead of a second one.

- `template` (string, required): The id of the template, as list-templates gives it.

#### `publish-template-version` (changes data)

Publish a draft of a template, so the records it describes start using it. The change is written to the account log.

- `template` (string, required): The id of the template, as list-templates gives it.
- `version` (integer, required): The number of the draft to publish, as list-template-versions gives it.
- `change_note` (string, optional): What changed. Required from the second published version on.

#### `delete-template-draft` (changes data)

Delete a draft of a template and every change made in it. A published version cannot be deleted. The change is written to the account log.

- `template` (string, required): The id of the template, as list-templates gives it.
- `version` (integer, required): The number of the draft to delete, as list-template-versions gives it.

#### `add-template-section` (changes data)

Add a section to a draft of a template: give name to create a new section, or section_id to place one the account already has. The change is written to the account log.

- `template` (string, required): The id of the template, as list-templates gives it.
- `version` (integer, required): The number of the draft, as create-template-draft gives it.
- `name` (string, optional): The name of a new section to create. Leave it out when giving section_id.
- `icon` (string, optional): The icon of a new section. Only with name. One of: `profile`, `people`, `note`, `relationship`, `family`, `timeline`, `calendar`, `reminder`, `tasks`, `memory`, `journal`, `file`, `mail`, `phone`, `place`, `home`, `briefcase`, `organization`, `graduation`, `health`, `activity`, `ball`, `food`, `gift`, `pet`, `plane`, `globe`, `book`, `music`, `coin`, `car`, `target`, `tag`, `heart`, `star`, `lock`, `layers`.
- `colour` (string, optional): The colour of a new section. Only with name. One of: `#3f5fd0`, `#4f8a49`, `#9a6a24`, `#9a3f2b`, `#6b4fa8`, `#2f7f86`, `#a8447a`, `#4a4a52`.
- `section_id` (string, optional): The id of a section the account already has, as get-template-version shows it on another template. Leave it out when giving name.
- `section_version_number` (integer, optional): Which version of the section named by section_id to place. Only with section_id. The published one when left out.
- `page_id` (string, optional): The id of the page to place the section on, as get-template-version gives it. The first page when left out.
- `title_override` (string, optional): What to head the section with in this template. Its own name when left out.
- `is_collapsed_by_default` (boolean, optional): Whether the section starts folded shut.

#### `update-template-section` (changes data)

Change what a section is headed in a draft of a template and whether it starts folded shut. The change is written to the account log.

- `template` (string, required): The id of the template, as list-templates gives it.
- `version` (integer, required): The number of the draft, as create-template-draft gives it.
- `section` (string, required): The id of the section in that version, as get-template-version gives it.
- `title_override` (string, optional): What to head the section with in this template. Null goes back to the name of the section.
- `is_collapsed_by_default` (boolean, optional): Whether the section starts folded shut.

#### `remove-template-section` (changes data)

Remove a section from a draft of a template. The section itself stays in the account for the other templates using it. The change is written to the account log.

- `template` (string, required): The id of the template, as list-templates gives it.
- `version` (integer, required): The number of the draft, as create-template-draft gives it.
- `section` (string, required): The id of the section in that version, as get-template-version gives it.

#### `set-template-section-position` (changes data)

Move a section to another place on its page, in a draft of a template. The change is written to the account log.

- `template` (string, required): The id of the template, as list-templates gives it.
- `version` (integer, required): The number of the draft, as create-template-draft gives it.
- `section` (string, required): The id of the section in that version, as get-template-version gives it.
- `position` (integer, required): Where the section goes on its page, counting from 1.

#### `create-template-field` (changes data)

Add a field to a section of a draft of a template. A section shared with other templates is drafted first, so its fields may come back with new ids. The change is written to the account log.

- `template` (string, required): The id of the template, as list-templates gives it.
- `version` (integer, required): The number of the draft, as create-template-draft gives it.
- `section` (string, required): The id of the section in that version, as get-template-version gives it.
- `type` (string, required): The kind of field. One of: `text`, `textarea`, `number`, `boolean`, `url`, `email`, `phone`, `select`, `multiselect`, `radio`, `date`, `recurring_date`, `duration`, `relation`, `file`, `image`, `avatar`, `address`, `repeater`, `divider`, `heading`, `help`.
- `label` (string, required): What the field is called on screen.
- `key` (string, optional): A stable machine name for the field. Made from the label when left out.
- `value_list_id` (integer, optional): The id of the value list a field offering choices takes them from, as list-value-lists gives it.
- `relation_target` (string, optional): What a relation field points at. One of: `contact`, `entity`.
- `relation_entity_type_id` (string, optional): The id of the kind of entity a relation field points at, as list-entity-types gives it.
- `parent_id` (integer, optional): The id of the repeater field to put this field inside, as get-template-version gives it.

#### `update-template-field` (changes data)

Change a field of a section in a draft of a template. The field may come back with a new id: use the returned one afterwards. The change is written to the account log.

- `template` (string, required): The id of the template, as list-templates gives it.
- `version` (integer, required): The number of the draft, as create-template-draft gives it.
- `section` (string, required): The id of the section in that version, as get-template-version gives it.
- `field` (string, required): The id of the field, as get-template-version gives it.
- `label` (string, optional): What the field is called on screen.
- `help_text` (string, optional): A line explaining the field, shown under it.
- `placeholder` (string, optional): The example shown in the empty field.
- `is_required` (boolean, optional): Whether a record cannot be saved without a value in this field.
- `is_sensitive` (boolean, optional): Whether the value is hidden until asked for.
- `is_highlighted` (boolean, optional): Whether the field is shown at the top of the record.
- `is_unique` (boolean, optional): Whether two records may not share a value.
- `is_identifying` (boolean, optional): Whether the field helps tell records apart.
- `value_list_id` (integer, optional): The id of the value list a field offering choices takes them from, as list-value-lists gives it.
- `default_value` (object, optional): The value a new record starts with.
- `options` (object, optional): Settings of the field type, such as the kinds of file accepted.
- `validation` (object, optional): Limits on the value, such as a minimum or a maximum.
- `repeat_min` (integer, optional): The fewest values a repeatable field holds.
- `repeat_max` (integer, optional): The most values a repeatable field holds.
- `repetition_order` (string, optional): How repeated values are ordered. One of: `newest_last`, `newest_first`.

#### `delete-template-field` (changes data)

Delete a field from a section of a draft of a template. The change is written to the account log.

- `template` (string, required): The id of the template, as list-templates gives it.
- `version` (integer, required): The number of the draft, as create-template-draft gives it.
- `section` (string, required): The id of the section in that version, as get-template-version gives it.
- `field` (string, required): The id of the field, as get-template-version gives it.

#### `set-template-field-position` (changes data)

Move a field to another place in its section, in a draft of a template. The field may come back with a new id: use the returned one afterwards. The change is written to the account log.

- `template` (string, required): The id of the template, as list-templates gives it.
- `version` (integer, required): The number of the draft, as create-template-draft gives it.
- `section` (string, required): The id of the section in that version, as get-template-version gives it.
- `field` (string, required): The id of the field, as get-template-version gives it.
- `position` (integer, required): Where the field goes in its section, counting from 1.

### Entity types

#### `list-entity-types`

List the kinds of record the account has defined, beyond contacts, a page at a time.

- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many entity types a page holds: 25 unless asked, 100 at most.

#### `get-entity-type`

Read one kind of record the account keeps besides contacts: its names, slug, icon, colour, position, whether new records can be added and how many exist.

- `entity_type` (string, required): The id of the entity type, as list-entity-types gives it.

#### `create-entity-type` (changes data)

Create a kind of record the account keeps besides contacts, such as Animal or Wine bottle. The change is written to the account log.

- `name_singular` (string, required): The name of one record, such as Wine bottle.
- `name_plural` (string, required): The name of several records, such as Wine bottles.
- `description` (string, optional): A sentence saying what these records are for.
- `icon` (string, optional): The icon shown next to these records. One of: `profile`, `logs`, `security`, `preferences`, `key`, `device`, `info`, `activity`, `mail`, `sun`, `moon`, `check`, `pet`.
- `colour` (string, optional): The colour of these records. One of: `#3f5fd0`, `#4f8a49`, `#9a6a24`, `#9a3f2b`, `#5d5f96`, `#1d1d20`.
- `is_active` (boolean, optional): Whether new records can be added. True when left out.
- `slug` (string, optional): The part of the URL naming these records, in lowercase letters, numbers and dashes. Derived from the singular name when left out, and fixed once created.

#### `update-entity-type` (changes data)

Rename a kind of record or change its description, icon or colour. The slug never changes. The change is written to the account log.

- `entity_type` (string, required): The id of the entity type, as list-entity-types gives it.
- `name_singular` (string, optional): The new name of one record.
- `name_plural` (string, optional): The new name of several records.
- `description` (string, optional): The new description.
- `icon` (string, optional): The icon shown next to these records. One of: `profile`, `logs`, `security`, `preferences`, `key`, `device`, `info`, `activity`, `mail`, `sun`, `moon`, `check`, `pet`.
- `colour` (string, optional): The colour of these records. One of: `#3f5fd0`, `#4f8a49`, `#9a6a24`, `#9a3f2b`, `#5d5f96`, `#1d1d20`.

#### `set-entity-type-activation` (changes data)

Switch a kind of record on, so new records of it can be added, or off. Existing records stay. The change is written to the account log.

- `entity_type` (string, required): The id of the entity type, as list-entity-types gives it.
- `is_active` (boolean, required): True to switch the entity type on, false to switch it off.

#### `set-entity-type-position` (changes data)

Move a kind of record to another place in the list. The change is written to the account log.

- `entity_type` (string, required): The id of the entity type, as list-entity-types gives it.
- `position` (integer, required): Where the entity type goes in the list, counting from 1.

#### `delete-entity-type` (changes data)

Delete a kind of record. A type still holding records is refused; switch it off instead. The change is written to the account log.

- `entity_type` (string, required): The id of the entity type, as list-entity-types gives it.

### Entities

#### `list-entities`

List the records of one entity type in one vault, such as the animals, a page at a time, by name, each with its values.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `entity_type` (string, required): The id of the entity type, as list-entity-types gives it.
- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many records a page holds: 25 unless asked, 100 at most.

#### `get-entity`

Look one record of an entity type up in a vault, such as an animal, with every value its template holds.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `entity` (string, required): The id of the record, as list-entities gives it.

#### `create-entity` (changes data)

Write down a new record of an entity type in a vault, such as an animal, on the template the vault uses for that type unless another template of the type is named. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `entity_type` (string, required): The id of the entity type, as list-entity-types gives it.
- `name` (string, required): What the record is called.
- `structure_version_id` (integer, optional): The id of the published version of one of your active templates for this entity type, as list-template-versions gives it, which says what the record holds. Left out, the record starts from the template the vault uses for that type.
- `fields` (object, optional): Values keyed by the field id get-template-version gives for the template the record starts from. A repeating group takes a list of repetitions, each as {values}, keyed by the ids of the fields inside the group. A field left out starts with its default.

#### `update-entity` (changes data)

Correct a record of an entity type, such as an animal: its name and the values of its template. The record stays on the template version it uses. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `entity` (string, required): The id of the record, as list-entities gives it.
- `name` (string, optional): What the record is called.
- `fields` (object, optional): Values keyed by the field id get-entity gives. A repeating group takes a list of repetitions, each as {id, values}: the id is the row get-entity gives, and the values are keyed by the ids of the fields inside the group.

### Relationship vocabulary

#### `list-relationship-types`

List the kinds of relationship the account has defined, such as parent or colleague.

- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many relationship types a page holds: 25 unless asked, 100 at most.

#### `get-relationship-type`

Read one kind of relationship: its name, the role of each contact, its category, whether it reads the same both ways, whether it is offered, whether it came with the account and how many relationships use it.

- `relationship_type` (string, required): The id of the relationship type, as list-relationship-types gives it.

#### `list-relationship-categories`

List the categories the account files its kinds of relationship under.

- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many categories a page holds: 25 unless asked, 100 at most.

#### `get-relationship-category`

Read one category of relationship types: its name, position, whether it is offered, whether it came with the account and how many types it holds.

- `relationship_category` (string, required): The id of the category, as list-relationship-categories gives it.

#### `list-relationship-category-types`

List the kinds of relationship filed under one category, in the order they are offered.

- `relationship_category` (string, required): The id of the category, as list-relationship-categories gives it.
- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many relationship types a page holds: 25 unless asked, 100 at most.

#### `create-relationship-type` (changes data)

Create a kind of relationship two contacts can be linked by, such as godparent and godchild, in one of the account’s categories. The change is written to the account log.

- `relationship_category_id` (string, required): The id of the category, as list-relationship-categories gives it.
- `name` (string, required): The name of the kind of relationship, such as Godparent.
- `role_a` (string, required): The role of the first contact, such as godparent.
- `role_b` (string, optional): The role of the other contact, such as godchild. Required when is_symmetric is false.
- `is_symmetric` (boolean, optional): True when both contacts hold the same role, as with siblings. True when left out.
- `is_active` (boolean, optional): Whether it is offered when contacts are linked. True when left out.

#### `update-relationship-type` (changes data)

Rename a kind of relationship, change its roles or whether it reads the same both ways, or move it to another category. Whether it is offered changes with set-relationship-type-activation. The change is written to the account log.

- `relationship_type` (string, required): The id of the relationship type, as list-relationship-types gives it.
- `relationship_category_id` (string, optional): The id of the category to move it to, as list-relationship-categories gives it.
- `name` (string, optional): The new name.
- `role_a` (string, optional): The new role of the first contact.
- `role_b` (string, optional): The new role of the other contact. It cannot be null when is_symmetric is false.
- `is_symmetric` (boolean, optional): True when both contacts hold the same role. A type that came with the account, or that relationships use, keeps its direction.

#### `set-relationship-type-activation` (changes data)

Offer a kind of relationship when contacts are linked, or stop offering it. Relationships already written with it stay. The change is written to the account log.

- `relationship_type` (string, required): The id of the relationship type, as list-relationship-types gives it.
- `is_active` (boolean, required): True to offer it, false to stop offering it.

#### `set-relationship-type-position` (changes data)

Move a kind of relationship to another place within its category. The change is written to the account log.

- `relationship_type` (string, required): The id of the relationship type, as list-relationship-types gives it.
- `position` (integer, required): Where it goes within its category, counting from 1.

#### `delete-relationship-type` (changes data)

Delete a kind of relationship the account created. One that came with the account, or that relationships use, is refused; stop offering it instead. The change is written to the account log.

- `relationship_type` (string, required): The id of the relationship type, as list-relationship-types gives it.

#### `create-relationship-category` (changes data)

Create a category to file kinds of relationship under, such as Sports. It is added at the end of the list. The change is written to the account log.

- `name` (string, required): The name of the category, such as Sports.

#### `update-relationship-category` (changes data)

Rename a category the account created. One that came with the account keeps its name. The change is written to the account log.

- `relationship_category` (string, required): The id of the category, as list-relationship-categories gives it.
- `name` (string, optional): The new name.

#### `set-relationship-category-activation` (changes data)

Offer a category of relationship types when contacts are linked, or stop offering it. Relationships already written stay. The change is written to the account log.

- `relationship_category` (string, required): The id of the category, as list-relationship-categories gives it.
- `is_active` (boolean, required): True to offer it, false to stop offering it.

#### `set-relationship-category-position` (changes data)

Move a category of relationship types to another place in the list. The change is written to the account log.

- `relationship_category` (string, required): The id of the category, as list-relationship-categories gives it.
- `position` (integer, required): Where it goes in the list of categories, counting from 1.

#### `delete-relationship-category` (changes data)

Delete a category the account created. One that came with the account, or that still holds types, is refused; move its types to another category first. The change is written to the account log.

- `relationship_category` (string, required): The id of the category, as list-relationship-categories gives it.

### Life event vocabulary

#### `list-life-event-categories`

List the categories the account files its kinds of life event under.

- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many categories a page holds: 25 unless asked, 100 at most.

#### `get-life-event-category`

Read one category of life event types: its name, position, whether it is offered, whether it came with the account and how many types it holds.

- `life_event_category` (string, required): The id of the category, as list-life-event-categories gives it.

#### `list-life-event-category-types`

List the kinds of life event filed under one category, in the order they are offered.

- `life_event_category` (string, required): The id of the category, as list-life-event-categories gives it.
- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many life event types a page holds: 25 unless asked, 100 at most.

#### `list-life-event-types`

List the kinds of life event the account can record, such as Moved house or Started a job, sorted by category.

- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many life event types a page holds: 25 unless asked, 100 at most.

#### `get-life-event-type`

Read one kind of life event: its name, description, icon, colour, category, position, whether it is offered and whether it came with the account.

- `life_event_type` (string, required): The id of the life event type, as list-life-event-types gives it.

#### `get-life-event-type-fields`

Read the fields a kind of life event asks for, in their groups, with the key that identifies each field. The fields nobody grouped come first.

- `life_event_type` (string, required): The id of the life event type, as list-life-event-types gives it.

#### `create-life-event-type` (changes data)

Create a kind of life event, such as Ran a marathon, in one of the account’s categories. Give it fields of its own with replace-life-event-type-fields. The change is written to the account log.

- `life_event_category_id` (string, required): The id of the category, as list-life-event-categories gives it.
- `name` (string, required): The name of the kind of life event, such as Ran a marathon.
- `description` (string, optional): A sentence saying what it is for.
- `icon` (string, optional): The icon shown next to it. One of: `profile`, `people`, `note`, `relationship`, `family`, `timeline`, `calendar`, `reminder`, `tasks`, `memory`, `journal`, `file`, `mail`, `phone`, `place`, `home`, `briefcase`, `organization`, `graduation`, `health`, `activity`, `ball`, `food`, `gift`, `pet`, `plane`, `globe`, `book`, `music`, `coin`, `car`, `target`, `tag`, `heart`, `star`, `lock`, `layers`.
- `colour` (string, optional): The colour it is drawn in. One of: `#3f5fd0`, `#4f8a49`, `#9a6a24`, `#9a3f2b`, `#6b4fa8`, `#2f7f86`, `#a8447a`, `#4a4a52`.
- `updates_last_in_touch` (boolean, optional): Whether its life events set Last in touch on the contacts they are recorded with. Defaults to true.

#### `update-life-event-type` (changes data)

Rename a kind of life event, change its description, icon or colour, or move it to another category. Whether it is offered changes with set-life-event-type-activation. The change is written to the account log.

- `life_event_type` (string, required): The id of the life event type, as list-life-event-types gives it.
- `life_event_category_id` (string, optional): The id of the category to move it to, as list-life-event-categories gives it.
- `name` (string, optional): The new name.
- `description` (string, optional): A sentence saying what it is for.
- `icon` (string, optional): The icon shown next to it. One of: `profile`, `people`, `note`, `relationship`, `family`, `timeline`, `calendar`, `reminder`, `tasks`, `memory`, `journal`, `file`, `mail`, `phone`, `place`, `home`, `briefcase`, `organization`, `graduation`, `health`, `activity`, `ball`, `food`, `gift`, `pet`, `plane`, `globe`, `book`, `music`, `coin`, `car`, `target`, `tag`, `heart`, `star`, `lock`, `layers`.
- `colour` (string, optional): The colour it is drawn in. One of: `#3f5fd0`, `#4f8a49`, `#9a6a24`, `#9a3f2b`, `#6b4fa8`, `#2f7f86`, `#a8447a`, `#4a4a52`.
- `updates_last_in_touch` (boolean, optional): Whether its life events set Last in touch on the contacts they are recorded with. Changing it works the date out again for everybody who took part in one.

#### `set-life-event-type-activation` (changes data)

Offer a kind of life event when somebody records one, or stop offering it. Life events already recorded with it stay. The change is written to the account log.

- `life_event_type` (string, required): The id of the life event type, as list-life-event-types gives it.
- `is_active` (boolean, required): True to offer it, false to stop offering it.

#### `set-life-event-type-position` (changes data)

Move a kind of life event to another place within its category. The change is written to the account log.

- `life_event_type` (string, required): The id of the life event type, as list-life-event-types gives it.
- `position` (integer, required): Where it goes within its category, counting from 1.

#### `replace-life-event-type-fields` (changes data)

Replace the groups of fields, the fields nobody grouped, or both, that a kind of life event asks for. Each of groups and fields that is sent replaces what was there, and each that is left out keeps what it holds. A field sent with its key keeps its identity, and a field missing from a list that is sent is no longer asked for. Life events already recorded keep what they were written with. The change is written to the account log.

- `life_event_type` (string, required): The id of the life event type, as list-life-event-types gives it.
- `groups` (array, optional): Groups of fields, each drawn under its name. Each group: placement_id (the id get-life-event-type-fields gives, to keep an existing group), name, and fields. Each field: key (the key get-life-event-type-fields gives, to keep an existing field; leave it out for a new one), label, type (one of: text, textarea, number, boolean, url, email, phone, select, multiselect, radio, date, recurring_date, duration, relation, file, image, avatar, address, repeater, divider, heading, help), is_required, help_text, settings (an object of strings; max_length, min, max, decimals, max_choices, repeat_min and repeat_max are whole numbers) and choices (a list of strings).
- `fields` (array, optional): Fields nobody grouped, shown first. Each field: key (the key get-life-event-type-fields gives, to keep an existing field; leave it out for a new one), label, type (one of: text, textarea, number, boolean, url, email, phone, select, multiselect, radio, date, recurring_date, duration, relation, file, image, avatar, address, repeater, divider, heading, help), is_required, help_text, settings (an object of strings; max_length, min, max, decimals, max_choices, repeat_min and repeat_max are whole numbers) and choices (a list of strings).

#### `delete-life-event-type` (changes data)

Delete a kind of life event the account created. One that came with the account, or that life events were recorded with, is refused; stop offering it instead. The change is written to the account log.

- `life_event_type` (string, required): The id of the life event type, as list-life-event-types gives it.

#### `create-life-event-category` (changes data)

Create a category to file kinds of life event under, such as Sport. It is added at the end of the list. The change is written to the account log.

- `name` (string, required): The name of the category, such as Sport.

#### `update-life-event-category` (changes data)

Rename a category of life event types. The change is written to the account log.

- `life_event_category` (string, required): The id of the category, as list-life-event-categories gives it.
- `name` (string, optional): The new name.

#### `set-life-event-category-activation` (changes data)

Offer a category of life event types when somebody records a life event, or stop offering it. Life events already recorded stay. The change is written to the account log.

- `life_event_category` (string, required): The id of the category, as list-life-event-categories gives it.
- `is_active` (boolean, required): True to offer it, false to stop offering it.

#### `set-life-event-category-position` (changes data)

Move a category of life event types to another place in the list. The change is written to the account log.

- `life_event_category` (string, required): The id of the category, as list-life-event-categories gives it.
- `position` (integer, required): Where it goes in the list of categories, counting from 1.

#### `delete-life-event-category` (changes data)

Delete a category the account created. One that came with the account, or that still holds types, is refused; move its types to another category first. The change is written to the account log.

- `life_event_category` (string, required): The id of the category, as list-life-event-categories gives it.

### Locations

#### `list-locations`

List the places of the account, such as a house, a room or a shelf, one page at a time. Each one comes before the places inside it, and carries its full path, the address it falls back on and how many places it holds.

- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many places a page holds: 25 unless asked, 100 at most.

#### `get-location`

Read one place of the account: its name, the place it sits inside, its emoji, its address, its full path, the address it falls back on and how many places it holds.

- `location` (string, required): The id of the place, as list-locations gives it.

#### `create-location` (changes data)

Add a place to the account, such as a house, a room, a shelf or a box, at the top level or inside another place. Find the place it sits inside with list-locations first. The change is written to the account log.

- `name` (string, required): What the place is called, such as Garage.
- `parent_id` (string, optional): The id of the place it sits inside, as list-locations gives it. Left out, it sits at the top level.
- `emoji` (string, optional): One emoji shown in place of the default icon, such as 🏠.
- `address` (string, optional): The address, as free text over several lines. Left out, the place uses the address of the nearest place around it that has one.

#### `update-location` (changes data)

Rename a place of the account, move it inside another place or to the top level, or change its emoji or address. Everything inside it moves with it. The change is written to the account log.

- `location` (string, required): The id of the place, as list-locations gives it.
- `name` (string, optional): The name, such as Garage.
- `parent_id` (string, optional): The id of the place to move it inside, as list-locations gives it. Null moves it to the top level.
- `emoji` (string, optional): One emoji shown in place of the default icon. Null shows the default icon again.
- `address` (string, optional): The address as free text. Null makes the place use the address of the nearest place around it that has one.

#### `delete-location` (changes data)

Delete a place of the account that holds no other place. One that holds others is refused until they are moved. The change is written to the account log.

- `location` (string, required): The id of the place, as list-locations gives it.

### Possession types

#### `list-possession-types`

List the possession types of the account, the kinds of things it owns such as office equipment or a vehicle, sorted by name, one page at a time. Each carries its colour, its icon, its groups and its fields in order.

- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many possession types a page holds: 25 unless asked, 100 at most.

#### `get-possession-type`

Read one possession type: its name, its colour, its icon, its groups and its fields in order, each field with its kind and, for a choice field, its choices.

- `possession_type` (string, required): The id of the possession type, as list-possession-types gives it.

#### `export-possession-type`

Write a possession type out as a file: its name, its colour, its icon, its groups and its fields, in order. The file can be imported again with import-possession-type.

- `possession_type` (string, required): The id of the possession type, as list-possession-types gives it.

#### `create-possession-type` (changes data)

Add a possession type to the account: a kind of thing it owns, such as office equipment or a vehicle. Add its fields afterwards with create-possession-field. The change is written to the account log.

- `name` (string, required): What the kind of thing is called.
- `colour` (string, optional): One of the vault colours, as a hexadecimal value. Blue when left out. One of: `#3f5fd0`, `#4f8a49`, `#9a6a24`, `#9a3f2b`, `#6b4fa8`, `#2f7f86`, `#a8447a`, `#4a4a52`.
- `icon` (string, optional): One of the glyphs of the catalogue. None when left out. One of: `profile`, `people`, `note`, `relationship`, `family`, `timeline`, `calendar`, `reminder`, `tasks`, `memory`, `journal`, `file`, `mail`, `phone`, `place`, `home`, `briefcase`, `organization`, `graduation`, `health`, `activity`, `ball`, `food`, `gift`, `pet`, `plane`, `globe`, `book`, `music`, `coin`, `car`, `target`, `tag`, `heart`, `star`, `lock`, `layers`.

#### `update-possession-type` (changes data)

Rename a possession type, give it another vault colour, or set, change or remove its icon. The change is written to the account log.

- `possession_type` (string, required): The id of the possession type, as list-possession-types gives it.
- `name` (string, optional): The new name.
- `colour` (string, optional): One of the vault colours, as a hexadecimal value. One of: `#3f5fd0`, `#4f8a49`, `#9a6a24`, `#9a3f2b`, `#6b4fa8`, `#2f7f86`, `#a8447a`, `#4a4a52`.
- `icon` (string, optional): One of the glyphs of the catalogue. One of: `profile`, `people`, `note`, `relationship`, `family`, `timeline`, `calendar`, `reminder`, `tasks`, `memory`, `journal`, `file`, `mail`, `phone`, `place`, `home`, `briefcase`, `organization`, `graduation`, `health`, `activity`, `ball`, `food`, `gift`, `pet`, `plane`, `globe`, `book`, `music`, `coin`, `car`, `target`, `tag`, `heart`, `star`, `lock`, `layers`.

#### `delete-possession-type` (changes data)

Delete a possession type with its groups, its fields, and every possession of that type with the details it held. This cannot be undone. The change is written to the account log.

- `possession_type` (string, required): The id of the possession type, as list-possession-types gives it.

#### `import-possession-type` (changes data)

Create a new possession type from a file written by export-possession-type. Nothing already in the account changes. A file with any problem creates nothing, and every problem is listed. The change is written to the account log.

- `file` (string, required): The whole file, as JSON text.

#### `create-possession-field-group` (changes data)

Add a named group of fields to a possession type, such as Purchase or Technical details, placed after the other groups. The change is written to the account log.

- `possession_type` (string, required): The id of the possession type, as list-possession-types gives it.
- `name` (string, required): What the group is called.

#### `update-possession-field-group` (changes data)

Rename a group of fields of a possession type. The change is written to the account log.

- `possession_type` (string, required): The id of the possession type, as list-possession-types gives it.
- `group` (string, required): The id of the group, as get-possession-type gives it.
- `name` (string, optional): The new name.

#### `delete-possession-field-group` (changes data)

Remove a group from a possession type. Its fields are kept and become standalone fields of the type, after the ones already there. The change is written to the account log.

- `possession_type` (string, required): The id of the possession type, as list-possession-types gives it.
- `group` (string, required): The id of the group, as get-possession-type gives it.

#### `set-possession-field-group-position` (changes data)

Move a group of fields to another place among the groups of its possession type. The change is written to the account log.

- `possession_type` (string, required): The id of the possession type, as list-possession-types gives it.
- `group` (string, required): The id of the group, as get-possession-type gives it.
- `position` (integer, required): Where it goes among the groups, counting from 1.

#### `create-possession-field` (changes data)

Add a field to a possession type, in one of its groups or standing alone, placed last. A choice field takes its choices in order. The change is written to the account log.

- `possession_type` (string, required): The id of the possession type, as list-possession-types gives it.
- `group_id` (string, optional): The id of the group the field goes in, as get-possession-type gives it. Left out, the field stands alone.
- `name` (string, required): What the field is called, such as Serial number.
- `kind` (string, required): What the field holds. One of: `text`, `number`, `date`, `boolean`, `select`, `rating`.
- `options` (array, optional): The choices of a choice field, in order. Ignored for every other kind.

#### `update-possession-field` (changes data)

Rename a field of a possession type, change its kind, or set its choices. A field that stops being a choice field loses its choices. A choice you remove is also removed from every possession that held it, and cannot be recovered. The change is written to the account log.

- `possession_type` (string, required): The id of the possession type, as list-possession-types gives it.
- `field` (string, required): The id of the field, as get-possession-type gives it.
- `name` (string, optional): The new name.
- `kind` (string, optional): What the field holds. One of: `text`, `number`, `date`, `boolean`, `select`, `rating`.
- `options` (array, optional): The choices of a choice field, in order, replacing the ones it has.

#### `delete-possession-field` (changes data)

Remove a field from a possession type. This cannot be undone. The change is written to the account log.

- `possession_type` (string, required): The id of the possession type, as list-possession-types gives it.
- `field` (string, required): The id of the field, as get-possession-type gives it.

#### `set-possession-field-position` (changes data)

Move a field to another place among the fields of its group, or among the standalone fields of its possession type. The change is written to the account log.

- `possession_type` (string, required): The id of the possession type, as list-possession-types gives it.
- `field` (string, required): The id of the field, as get-possession-type gives it.
- `position` (integer, required): Where it goes among the fields beside it, counting from 1.

### Possessions

#### `list-possessions`

List the possessions of one vault, a page at a time, by name. The list can be narrowed by type, status, location or whether they are featured. Each possession carries its type, its location, the values of its fields and its current value. In compact form it carries only its name, status, type, location and current value.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `type` (string, optional): Only possessions of this possession type, by the id list-possession-types gives.
- `status` (string, optional): Only possessions with this status. One of: `owned`, `ordered`, `sold`, `given_away`, `lost`, `stolen`, `thrown_away`.
- `featured` (boolean, optional): True for only the featured possessions, false for only the others.
- `location` (string, optional): Only possessions at this location or at a location inside it, by the id list-locations gives.
- `sort` (string, optional): name, the default, sorts by name. position puts the featured possessions first, in their order. One of: `name`, `position`.
- `compact` (boolean, optional): When true, each possession carries only its name, status, type, location and current value. Use it to go through everything quickly, then get-possession for the full record.
- `page` (integer, optional): The page to read, from 1.
- `per_page` (integer, optional): How many possessions on a page.

#### `get-possession`

Get one possession of a vault, with its type, its location and the values of its fields.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.

#### `list-possession-transactions`

List the transactions of a possession, oldest first, undated ones before the others: money and ownership changing hands, with their figures, their total and which one is the acquisition.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.

#### `get-possession-transaction`

Read one transaction of a possession: what happened, when, with whom, its figures, its total and whether it is the acquisition.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `transaction` (string, required): The id of the transaction, as list-possession-transactions gives it.

#### `list-possession-insurance-records`

List the insurance records of a possession, one per policy period, active first, then pending, expired and cancelled, the latest start first within each: the insurer, the insured value, the period and which record is the current one.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.

#### `get-possession-insurance-record`

Read one insurance record of a possession: the insurer, the status, the insured value and the excess, the period, who to call at the insurer and whether it is the current record.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `insurance_record` (string, required): The id of the insurance record, as list-possession-insurance-records gives it.

#### `list-possession-maintenance-records`

List the maintenance records of a possession, the latest job first: the type, the title, who did it and when, the cost, the condition before and after, the next due date and whether it is overdue. Only the latest record can be overdue.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.

#### `get-possession-maintenance-record`

Read one maintenance record of a possession: the type, the title, who did it and when, the cost, the condition before and after, the next due date and whether it is overdue.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `maintenance_record` (string, required): The id of the maintenance record, as list-possession-maintenance-records gives it.

#### `list-possession-valuations`

List the valuations of a possession, the latest by date first: the type, the date, the amount in its currency, the valuer, the confidence and which valuation gives the current value.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.

#### `get-possession-valuation`

Read one valuation of a possession: the type, the date, the amount in its currency, the confidence, the valuer, the method, the reference, the source link, the note, its documents and whether it gives the current value.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `valuation` (string, required): The id of the valuation, as list-possession-valuations gives it.

#### `list-possession-provenance-events`

List the provenance events of a possession, oldest first and those with an unknown date last: where it was made, who owned or held it, and what authenticated it, with how precise each date is and whether the event is verified.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.

#### `get-possession-provenance-event`

Get one provenance event of a possession: what happened, when and how precisely that is known, who it passed from and to, where, how it is known, and the transaction recording what it cost, if any.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `event` (string, required): The id of the event, as list-possession-provenance-events gives it.

#### `list-possession-location-stays`

List the stays of a possession: each location it was kept at, the day it arrived and left, and why. The stays with an unknown arrival day come first. The others follow by arrival day, oldest first. The stay with no day it left is where it is now.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.

#### `get-possession-location-stay`

Get one stay of a possession: the location it was kept at, the day it arrived and left, whether it is there now, and why.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `stay` (string, required): The id of the stay, as list-possession-location-stays gives it.

#### `create-possession` (changes data)

Record an object somebody owns in a vault. It has one possession type, and optionally a location, what it would cost to replace and tags. Unless given, its status is owned, its quantity is 1 and it is not featured. Record how it was acquired with create-possession-transaction. Write the values of its fields with set-possession-values. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `type_id` (string, required): The id of its possession type, as list-possession-types gives it. The type never changes afterwards.
- `name` (string, required): What it is called, like “Michael’s Chrysler Sebring”.
- `description` (string, optional): A free description, up to 2,000 characters.
- `location_id` (string, optional): The id of the location where it is now, as list-locations gives it.
- `identifier` (string, optional): A serial number, a vehicle identification number or a frame number.
- `status` (string, optional): Its status. Owned when not given. One of: `owned`, `ordered`, `sold`, `given_away`, `lost`, `stolen`, `thrown_away`.
- `quantity` (integer, optional): How many, from 1 to 1,000,000. 1 when not given.
- `is_featured` (boolean, optional): Whether it is shown among the main possessions of the vault. A featured possession is placed last among them.
- `declared_value` (number, optional): What it would cost to replace today, 0 or more, with two decimals.
- `declared_value_currency` (string, optional): The currency of the declared value. Required when declared_value is given. One of: `usd`, `eur`, `gbp`, `cad`, `aud`, `chf`, `jpy`, `brl`, `inr`, `cny`.
- `tags` (array, optional): The names of its tags. A name matching a tag of the account, ignoring case, reuses that tag. Any other name creates a tag.

#### `update-possession` (changes data)

Change what is known of a possession: its name, description, location, identifier, status, quantity, whether it is featured, what it would cost to replace, or its tags. How it was acquired is a transaction, changed with update-possession-transaction. Its type never changes. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `name` (string, optional): The new name.
- `description` (string, optional): A free description, up to 2,000 characters.
- `location_id` (string, optional): The id of the location where it is now, as list-locations gives it.
- `identifier` (string, optional): A serial number or another identifier.
- `status` (string, optional): The new status. One of: `owned`, `ordered`, `sold`, `given_away`, `lost`, `stolen`, `thrown_away`.
- `quantity` (integer, optional): How many, from 1 to 1,000,000.
- `is_featured` (boolean, optional): Whether it is shown among the main possessions. A possession that becomes featured is placed last. A possession that stops being featured leaves the order.
- `declared_value` (number, optional): What it would cost to replace today, 0 or more, with two decimals.
- `declared_value_currency` (string, optional): The currency of the declared value. Required when declared_value is given. One of: `usd`, `eur`, `gbp`, `cad`, `aud`, `chf`, `jpy`, `brl`, `inr`, `cny`.
- `tags` (array, optional): The names of all its tags, replacing the tags it carries. A name matching a tag of the account, ignoring case, reuses that tag. Any other name creates a tag.

#### `delete-possession` (changes data)

Delete a possession and the values of its fields. It is removed from every list and no tool brings it back. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.

#### `set-possession-position` (changes data)

Move a featured possession to another place among the featured possessions of its vault, counted from 1. The others shift. Only a featured possession has a place. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `position` (integer, required): Its new place among the featured possessions, from 1.

#### `set-possession-values` (changes data)

Write the values a possession holds for fields of its type, keyed by the id of the field as get-possession-type gives it. Only the fields named change. Null or an empty string removes a value. Text holds up to 2,000 characters, a number is a number, a date is written YYYY-MM-DD, yes or no is true or false, a choice is one of the field’s own choices, a rating is 1 to 5. Nothing is written unless every value fits. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `values` (object, required): The values to write, keyed by the id of the field.

#### `create-possession-transaction` (changes data)

Record money or ownership changing hands for a possession: a purchase, a sale, an exchange, a gift received or given, an inheritance, a refund, a fee, a tax, shipping or anything else. Every figure is optional and zero or more, and needs the currency it is in. The earliest purchase, exchange, gift received or inheritance gives the possession its acquisition date and price. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `type` (string, required): What happened. One of: `purchase`, `sale`, `exchange`, `gift_received`, `gift_given`, `inheritance`, `refund`, `fee`, `tax`, `shipping`, `other`.
- `occurred_on` (string, optional): The day it happened, as YYYY-MM-DD. Left out when not known.
- `counterparty` (string, optional): Who was on the other side, as text: a shop, a person, an estate.
- `amount` (number, optional): The price or the amount, 0 or more, with two decimals.
- `tax` (number, optional): The tax paid, 0 or more.
- `fees` (number, optional): The fees paid, 0 or more.
- `shipping` (number, optional): The shipping paid, 0 or more.
- `entered_total` (number, optional): The total, when it is not the sum of the amount, the tax, the fees and the shipping.
- `currency` (string, optional): The currency of every figure. Required with any figure. One of: `usd`, `eur`, `gbp`, `cad`, `aud`, `chf`, `jpy`, `brl`, `inr`, `cny`.
- `reference` (string, optional): An invoice, receipt or deed number.
- `source_url` (string, optional): A full web address where the transaction can be checked.
- `note` (string, optional): Anything worth remembering about the transaction.

#### `update-possession-transaction` (changes data)

Change a transaction of a possession. Every figure is zero or more and needs the currency it is in. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `transaction` (string, required): The id of the transaction, as list-possession-transactions gives it.
- `type` (string, optional): What happened. One of: `purchase`, `sale`, `exchange`, `gift_received`, `gift_given`, `inheritance`, `refund`, `fee`, `tax`, `shipping`, `other`.
- `occurred_on` (string, optional): The day it happened, as YYYY-MM-DD, or null when it is not known.
- `counterparty` (string, optional): Who was on the other side, as text: a shop, a person, an estate.
- `amount` (number, optional): The price or the amount, 0 or more, with two decimals.
- `tax` (number, optional): The tax paid, 0 or more.
- `fees` (number, optional): The fees paid, 0 or more.
- `shipping` (number, optional): The shipping paid, 0 or more.
- `entered_total` (number, optional): The total, when it is not the sum of the amount, the tax, the fees and the shipping.
- `currency` (string, optional): The currency of every figure. Required with any figure. One of: `usd`, `eur`, `gbp`, `cad`, `aud`, `chf`, `jpy`, `brl`, `inr`, `cny`.
- `reference` (string, optional): An invoice, receipt or deed number.
- `source_url` (string, optional): A full web address where the transaction can be checked.
- `note` (string, optional): Anything worth remembering about the transaction.

#### `delete-possession-transaction` (changes data)

Delete a transaction of a possession, with the documents attached to it. When it was the acquisition, the next earliest purchase, exchange, gift received or inheritance becomes the acquisition. No tool brings it back. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `transaction` (string, required): The id of the transaction, as list-possession-transactions gives it.

#### `create-possession-insurance-record` (changes data)

Record one policy period covering a possession: the insurer, the status and the insured value in its currency are required. When a policy renews with a new insured value, or the insurer changes, record a new one rather than changing the old one, so the history of the coverage is kept. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `insurer` (string, required): Who insures the possession, as text.
- `status` (string, required): Where the policy stands. One of: `active`, `pending`, `expired`, `cancelled`.
- `policy_number` (string, optional): The number of the policy.
- `coverage` (string, optional): What the policy covers, such as theft, fire and accidental damage.
- `insured_value` (number, required): The value the possession is insured for, 0 or more.
- `excess` (number, optional): What is paid before the insurer pays, 0 or more.
- `currency` (string, required): The currency of the insured value and the excess. One of: `usd`, `eur`, `gbp`, `cad`, `aud`, `chf`, `jpy`, `brl`, `inr`, `cny`.
- `starts_on` (string, optional): The day the policy period starts, as YYYY-MM-DD.
- `ends_on` (string, optional): The day the policy period ends or renews, as YYYY-MM-DD. Left out for a policy with no end date.
- `is_listed_individually` (boolean, optional): Whether the policy names this possession, rather than covering it under the general contents of the home.
- `contact_name` (string, optional): Who to call at the insurer.
- `contact_email` (string, optional): The email of the person to call at the insurer.
- `contact_phone` (string, optional): The phone number of the person to call at the insurer.
- `note` (string, optional): Conditions, exclusions, what the insurer asked for.

#### `update-possession-insurance-record` (changes data)

Change an insurance record of a possession. The other records are not touched. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `insurance_record` (string, required): The id of the insurance record, as list-possession-insurance-records gives it.
- `insurer` (string, optional): Who insures the possession, as text.
- `status` (string, optional): Where the policy stands. One of: `active`, `pending`, `expired`, `cancelled`.
- `policy_number` (string, optional): The number of the policy.
- `coverage` (string, optional): What the policy covers, such as theft, fire and accidental damage.
- `insured_value` (number, optional): The value the possession is insured for, 0 or more.
- `excess` (number, optional): What is paid before the insurer pays, 0 or more.
- `currency` (string, optional): The currency of the insured value and the excess. One of: `usd`, `eur`, `gbp`, `cad`, `aud`, `chf`, `jpy`, `brl`, `inr`, `cny`.
- `starts_on` (string, optional): The day the policy period starts, as YYYY-MM-DD.
- `ends_on` (string, optional): The day the policy period ends or renews, as YYYY-MM-DD, or null for a policy with no end date.
- `is_listed_individually` (boolean, optional): Whether the policy names this possession, rather than covering it under the general contents of the home.
- `contact_name` (string, optional): Who to call at the insurer.
- `contact_email` (string, optional): The email of the person to call at the insurer.
- `contact_phone` (string, optional): The phone number of the person to call at the insurer.
- `note` (string, optional): Conditions, exclusions, what the insurer asked for.

#### `delete-possession-insurance-record` (changes data)

Delete an insurance record of a possession. The history of how the possession was covered loses that policy period. No tool brings it back. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `insurance_record` (string, required): The id of the insurance record, as list-possession-insurance-records gives it.

#### `create-possession-maintenance-record` (changes data)

Record one job done on a possession: the type, a title and the day it was performed are required. Record a new one for every job rather than changing an earlier one, so the history of the work is kept. The conditions are the account's possession conditions, as list-possession-conditions gives them. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `maintenance_type` (string, required): The kind of job. One of: `inspection`, `cleaning`, `servicing`, `repair`, `restoration`, `part_replacement`, `conservation`, `other`.
- `title` (string, required): What was done, such as re-plating or a new gasket.
- `performed_by` (string, optional): Who did the job, a person or a workshop, as text.
- `performed_on` (string, required): The day the job was done, as YYYY-MM-DD, not after today.
- `cost` (number, optional): What the job cost, 0 or more. Needs a currency.
- `currency` (string, optional): The currency of the cost. One of: `usd`, `eur`, `gbp`, `cad`, `aud`, `chf`, `jpy`, `brl`, `inr`, `cny`.
- `condition_before_id` (string, optional): The id of the condition the possession was in before the job, as list-possession-conditions gives it.
- `condition_after_id` (string, optional): The id of the condition the possession was in after the job, as list-possession-conditions gives it.
- `next_due_on` (string, optional): The day the job should be done again, as YYYY-MM-DD, not before the job.
- `description` (string, optional): What was found and what was done.

#### `update-possession-maintenance-record` (changes data)

Change a maintenance record of a possession. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `maintenance_record` (string, required): The id of the maintenance record, as list-possession-maintenance-records gives it.
- `maintenance_type` (string, optional): The kind of job. One of: `inspection`, `cleaning`, `servicing`, `repair`, `restoration`, `part_replacement`, `conservation`, `other`.
- `title` (string, optional): What was done, such as re-plating or a new gasket.
- `performed_by` (string, optional): Who did the job, a person or a workshop, as text.
- `performed_on` (string, optional): The day the job was done, as YYYY-MM-DD, not after today.
- `cost` (number, optional): What the job cost, 0 or more. Needs a currency.
- `currency` (string, optional): The currency of the cost. One of: `usd`, `eur`, `gbp`, `cad`, `aud`, `chf`, `jpy`, `brl`, `inr`, `cny`.
- `condition_before_id` (string, optional): The id of the condition the possession was in before the job, as list-possession-conditions gives it.
- `condition_after_id` (string, optional): The id of the condition the possession was in after the job, as list-possession-conditions gives it.
- `next_due_on` (string, optional): The day the job should be done again, as YYYY-MM-DD, not before the job.
- `description` (string, optional): What was found and what was done.

#### `delete-possession-maintenance-record` (changes data)

Delete a maintenance record of a possession. The history of the work done on it loses that job. No tool brings it back. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `maintenance_record` (string, required): The id of the maintenance record, as list-possession-maintenance-records gives it.

#### `create-possession-valuation` (changes data)

Record what a possession is worth on a date: the type, the date and the amount in its currency are required. A valuation is never changed afterwards. To correct one, record a new valuation. The latest by date becomes the current value of the possession. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `type` (string, required): Where the figure comes from. One of: `own_estimate`, `appraisal`, `insurance_declaration`, `auction_result`, `comparable_listing`, `offer_received`.
- `valued_on` (string, required): The day the estimate applies to, as YYYY-MM-DD.
- `confidence` (string, optional): How sure somebody is of the figure. Unknown when left out. One of: `unknown`, `certain`, `probable`, `uncertain`.
- `amount` (number, required): What the possession is worth, 0 or more.
- `currency` (string, required): The currency of the amount. One of: `usd`, `eur`, `gbp`, `cad`, `aud`, `chf`, `jpy`, `brl`, `inr`, `cny`.
- `valuer` (string, optional): Who estimated it: a jeweller, an auction house, the owner.
- `method` (string, optional): How it was estimated, such as comparable sales.
- `reference_number` (string, optional): The reference of the appraisal, the listing or the offer.
- `source_url` (string, optional): A full web address where the valuation can be checked.
- `note` (string, optional): Anything worth remembering about the valuation.

#### `delete-possession-valuation` (changes data)

Delete a valuation of a possession, with the documents attached to it. When it gave the current value, the latest valuation left gives it instead. To correct a figure, record a new valuation rather than deleting this one. No tool brings it back. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `valuation` (string, required): The id of the valuation, as list-possession-valuations gives it.

#### `create-possession-provenance-event` (changes data)

Record one moment in the provenance of a possession: where it was made, a change of owner or of custody, a loss or a recovery, or what authenticated, exhibited or published it. Only the type is required. The date is written in the shape its precision gives. An event holds no money: point it at the transaction that records what it cost. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `type` (string, required): What happened. One of: `origin`, `acquisition`, `inheritance`, `gift`, `sale`, `custody`, `loss`, `recovery`, `authentication`, `exhibition`, `publication`, `other`.
- `date_precision` (string, optional): How much of the date is known. A day when left out. One of: `day`, `month`, `year`, `circa`, `unknown`.
- `occurred_on` (string, optional): When it happened, in the shape its precision gives: YYYY-MM-DD for a day, YYYY-MM for a month, YYYY for a year or around a year, nothing when unknown.
- `title` (string, optional): What happened, in a few words. The name of the type is shown when left out.
- `from` (string, optional): Who it came from: a person, a shop, an estate.
- `to` (string, optional): Who held it afterwards.
- `location` (string, optional): Where it happened.
- `description` (string, optional): What happened, and how it is known.
- `reference_number` (string, optional): The reference of the record: a lot, a deed, a certificate.
- `source_url` (string, optional): A full web address where the event can be checked.
- `transaction_id` (string, optional): The id of a transaction of the same possession recording what the moment cost, as list-possession-transactions gives it.
- `is_verified` (boolean, optional): Whether a document, a record or an expert confirms the event. Not verified when left out.

#### `update-possession-provenance-event` (changes data)

Change a provenance event of a possession. The date is written in the shape its precision gives. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `event` (string, required): The id of the event, as list-possession-provenance-events gives it.
- `type` (string, optional): What happened. One of: `origin`, `acquisition`, `inheritance`, `gift`, `sale`, `custody`, `loss`, `recovery`, `authentication`, `exhibition`, `publication`, `other`.
- `date_precision` (string, optional): How much of the date is known. One of: `day`, `month`, `year`, `circa`, `unknown`.
- `occurred_on` (string, optional): When it happened, in the shape its precision gives: YYYY-MM-DD for a day, YYYY-MM for a month, YYYY for a year or around a year, null when unknown.
- `title` (string, optional): What happened, in a few words.
- `from` (string, optional): Who it came from: a person, a shop, an estate.
- `to` (string, optional): Who held it afterwards.
- `location` (string, optional): Where it happened.
- `description` (string, optional): What happened, and how it is known.
- `reference_number` (string, optional): The reference of the record: a lot, a deed, a certificate.
- `source_url` (string, optional): A full web address where the event can be checked.
- `transaction_id` (string, optional): The id of a transaction of the same possession recording what the moment cost, as list-possession-transactions gives it.
- `is_verified` (boolean, optional): Whether a document, a record or an expert confirms the event.

#### `delete-possession-provenance-event` (changes data)

Delete a provenance event of a possession. The transaction it points at, if any, stays. No tool brings the event back. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `event` (string, required): The id of the event, as list-possession-provenance-events gives it.

#### `move-possession` (changes data)

Move a possession to another location of the account on a given day. The stay where it is now closes that day, and a new stay at the new location opens the same day. Refused for the location it is already in, and for a day before its current stay began. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `location_id` (string, required): The id of the location it moves to, as list-locations gives it.
- `moved_on` (string, required): The day it moved, as YYYY-MM-DD.
- `reason` (string, optional): Why it moved, up to 255 characters.
- `note` (string, optional): Anything worth knowing about the new stay, up to 5,000 characters.

#### `update-possession-location-stay` (changes data)

Correct one stay of a possession: its location, the day it arrived, the day it left, the reason or the note. The stays before and after it are not moved. A past stay keeps a day it left. The stay where it is now cannot be given a day it left: move the possession instead. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `stay` (string, required): The id of the stay, as list-possession-location-stays gives it.
- `location_id` (string, optional): The id of the location, as list-locations gives it.
- `arrived_on` (string, optional): The day it arrived, as YYYY-MM-DD. Null when unknown.
- `left_on` (string, optional): The day it left, as YYYY-MM-DD. Only for a past stay.
- `reason` (string, optional): Why it was there, up to 255 characters.
- `note` (string, optional): Anything worth knowing about the stay, up to 5,000 characters.

#### `delete-possession-location-stay` (changes data)

Delete one stay of a possession. The other stays are not moved, so its period shows as unrecorded. Deleting the stay where it is now leaves the possession with no current location until it is moved. No tool brings the stay back. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `stay` (string, required): The id of the stay, as list-possession-location-stays gives it.

#### `list-possession-loans`

List the loans of a possession, newest first: each time it was lent to or borrowed from a contact of its vault, when, whether it is planned, active or returned, and whether it is overdue. The active loan says who has it now. A loan never changes the owner.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.

#### `get-possession-loan`

Return one loan of a possession: the contact, the direction, the status, the days it started, is due back and came back, the conditions, the deposit and the purpose.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `loan` (string, required): The id of the loan, as list-possession-loans gives it.

#### `create-possession-loan` (changes data)

Record a possession lent to a contact of its vault, or borrowed from one, without any change of owner. Give an existing contact in contact_id, or a new contact to write down with the loan in new_contact. Only one loan of a possession can be active at a time. A loan in the provenance also records a change of custody when it starts and when it ends. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `direction` (string, required): lent when it leaves your hands, borrowed when it comes into them. One of: `lent`, `borrowed`.
- `status` (string, required): planned, active or returned. One of: `planned`, `active`, `returned`.
- `contact_id` (string, optional): The id of a contact of the vault, as list-contacts gives it.
- `new_contact` (object, optional): A new contact to write down with the loan, when no contact_id is given.
- `started_on` (string, required): The day the loan started, as YYYY-MM-DD.
- `due_on` (string, optional): The day it is due back, as YYYY-MM-DD.
- `returned_on` (string, optional): The day it came back, as YYYY-MM-DD. Required for a returned loan.
- `condition_out_id` (string, optional): The id of the condition it left in, as list-possession-conditions gives it.
- `condition_back_id` (string, optional): The id of the condition it came back in, as list-possession-conditions gives it.
- `deposit_amount` (number, optional): A deposit left against the loan, 0 or more.
- `deposit_currency` (string, optional): The currency of the deposit. One of: `usd`, `eur`, `gbp`, `cad`, `aud`, `chf`, `jpy`, `brl`, `inr`, `cny`.
- `purpose` (string, optional): Why it was lent or borrowed.
- `is_in_provenance` (boolean, optional): Whether the loan records changes of custody in the provenance.

#### `update-possession-loan` (changes data)

Change one loan of a possession, including marking it as returned with the day it came back. A loan that is not returned loses its return day and the condition it came back in. Only one loan of a possession can be active at a time. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `loan` (string, required): The id of the loan, as list-possession-loans gives it.
- `direction` (string, optional): lent when it leaves your hands, borrowed when it comes into them. One of: `lent`, `borrowed`.
- `status` (string, optional): planned, active or returned. One of: `planned`, `active`, `returned`.
- `contact_id` (string, optional): The id of a contact of the vault, as list-contacts gives it.
- `started_on` (string, optional): The day the loan started, as YYYY-MM-DD.
- `due_on` (string, optional): The day it is due back, as YYYY-MM-DD.
- `returned_on` (string, optional): The day it came back, as YYYY-MM-DD. Required for a returned loan.
- `condition_out_id` (string, optional): The id of the condition it left in, as list-possession-conditions gives it.
- `condition_back_id` (string, optional): The id of the condition it came back in, as list-possession-conditions gives it.
- `deposit_amount` (number, optional): A deposit left against the loan, 0 or more.
- `deposit_currency` (string, optional): The currency of the deposit. One of: `usd`, `eur`, `gbp`, `cad`, `aud`, `chf`, `jpy`, `brl`, `inr`, `cny`.
- `purpose` (string, optional): Why it was lent or borrowed.
- `is_in_provenance` (boolean, optional): Whether the loan records changes of custody in the provenance.

#### `delete-possession-loan` (changes data)

Delete one loan of a possession, with the provenance events it wrote. The contact stays. No tool brings the loan back. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `possession` (string, required): The id of the possession, as list-possessions gives it.
- `loan` (string, required): The id of the loan, as list-possession-loans gives it.

### Possession tags

#### `list-possession-tags`

List the possession tags of the account, the words it puts on its possessions such as “insured” or “to sell”, sorted by name, one page at a time. Each carries its colour.

- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many tags a page holds: 25 unless asked, 100 at most.

#### `get-possession-tag`

Read one possession tag: its name and its colour.

- `possession_tag` (string, required): The id of the possession tag, as list-possession-tags gives it.

#### `create-possession-tag` (changes data)

Add a possession tag to the account: a word to put on possessions, such as “insured” or “to sell”. Its name is unique in the account ignoring case. The change is written to the account log.

- `name` (string, required): What the tag reads, up to 50 characters.
- `colour` (string, optional): One of the vault colours, as a hexadecimal value. Blue when left out. One of: `#3f5fd0`, `#4f8a49`, `#9a6a24`, `#9a3f2b`, `#6b4fa8`, `#2f7f86`, `#a8447a`, `#4a4a52`.

#### `update-possession-tag` (changes data)

Rename a possession tag or give it another vault colour. The change is written to the account log.

- `possession_tag` (string, required): The id of the possession tag, as list-possession-tags gives it.
- `name` (string, optional): The new name, up to 50 characters.
- `colour` (string, optional): One of the vault colours, as a hexadecimal value. One of: `#3f5fd0`, `#4f8a49`, `#9a6a24`, `#9a3f2b`, `#6b4fa8`, `#2f7f86`, `#a8447a`, `#4a4a52`.

#### `delete-possession-tag` (changes data)

Delete a possession tag. This cannot be undone. The change is written to the account log.

- `possession_tag` (string, required): The id of the possession tag, as list-possession-tags gives it.

### Possession conditions

#### `list-possession-conditions`

List the possession conditions of the account, the states its possessions can be in such as “new” or “broken”, in the order the account keeps them, from best to worst, one page at a time. Each carries its colour, its icon or none, and its position.

- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many conditions a page holds: 25 unless asked, 100 at most.

#### `get-possession-condition`

Read one possession condition: its name, its colour, its icon or none, and its position.

- `possession_condition` (string, required): The id of the possession condition, as list-possession-conditions gives it.

#### `create-possession-condition` (changes data)

Add a possession condition to the account: a state its possessions can be in, such as “mint” or “needs repair”. It goes last in the order, and its name is unique in the account ignoring case. The change is written to the account log.

- `name` (string, required): What the condition reads, up to 50 characters.
- `colour` (string, optional): One of the vault colours, as a hexadecimal value. Blue when left out. One of: `#3f5fd0`, `#4f8a49`, `#9a6a24`, `#9a3f2b`, `#6b4fa8`, `#2f7f86`, `#a8447a`, `#4a4a52`.
- `icon` (string, optional): One of the glyphs of the catalogue. None when left out. One of: `profile`, `people`, `note`, `relationship`, `family`, `timeline`, `calendar`, `reminder`, `tasks`, `memory`, `journal`, `file`, `mail`, `phone`, `place`, `home`, `briefcase`, `organization`, `graduation`, `health`, `activity`, `ball`, `food`, `gift`, `pet`, `plane`, `globe`, `book`, `music`, `coin`, `car`, `target`, `tag`, `heart`, `star`, `lock`, `layers`.

#### `update-possession-condition` (changes data)

Rename a possession condition, give it another vault colour, or set, change or remove its icon. It keeps its place in the order. The change is written to the account log.

- `possession_condition` (string, required): The id of the possession condition, as list-possession-conditions gives it.
- `name` (string, optional): The new name, up to 50 characters.
- `colour` (string, optional): One of the vault colours, as a hexadecimal value. One of: `#3f5fd0`, `#4f8a49`, `#9a6a24`, `#9a3f2b`, `#6b4fa8`, `#2f7f86`, `#a8447a`, `#4a4a52`.
- `icon` (string, optional): One of the glyphs of the catalogue. One of: `profile`, `people`, `note`, `relationship`, `family`, `timeline`, `calendar`, `reminder`, `tasks`, `memory`, `journal`, `file`, `mail`, `phone`, `place`, `home`, `briefcase`, `organization`, `graduation`, `health`, `activity`, `ball`, `food`, `gift`, `pet`, `plane`, `globe`, `book`, `music`, `coin`, `car`, `target`, `tag`, `heart`, `star`, `lock`, `layers`.

#### `set-possession-condition-position` (changes data)

Move a possession condition to another place in the order, which runs from best to worst. A position past the end puts it last. The change is written to the account log.

- `possession_condition` (string, required): The id of the possession condition, as list-possession-conditions gives it.
- `position` (integer, required): Where it goes in the order, counting from 1.

#### `delete-possession-condition` (changes data)

Delete a possession condition. This cannot be undone. The change is written to the account log.

- `possession_condition` (string, required): The id of the possession condition, as list-possession-conditions gives it.

### Knowledge

#### `list-knowledge`

List the Knowledge of a vault: its folders in their order, each with the ids and titles of its notes and lists. Read a note with get-knowledge-note and a list with get-knowledge-list.

- `vault` (string, required): The id of the vault, as list-vaults gives it.

#### `search-knowledge`

Find the notes and lists of a vault's Knowledge holding every word given, in their title, their text, their description or any cell. Case, accents and a typing mistake are ignored.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `query` (string, required): The words to find, at least two letters or digits.

#### `get-knowledge-note`

Read one note of a vault's Knowledge: its title, its folder, its text in Markdown as written, and its headings.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `note` (string, required): The id of the note, as list-knowledge gives it.

#### `get-knowledge-list`

Read one list of a vault's Knowledge: its title, its description, its columns in order, and its items. Each item holds its texts keyed by the id of their column. A blank cell is left out.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `list` (string, required): The id of the list, as list-knowledge gives it.

#### `create-knowledge-folder` (changes data)

Add a folder to the Knowledge of a vault, after the folders already there. Folders are not nested. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `name` (string, required): The name of the folder, such as Home or Travel.

#### `update-knowledge-folder` (changes data)

Rename a folder of a vault's Knowledge, move it in the order of the folders, or both. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `folder` (string, required): The id of the folder, as list-knowledge gives it.
- `name` (string, optional): The new name of the folder.
- `position` (integer, optional): Where the folder goes in the order, 1 for first. A number past the end puts the folder last.

#### `delete-knowledge-folder` (changes data)

Delete a folder of a vault's Knowledge. Its notes and lists move to the folder given as move_to. Without move_to, they are deleted with the folder, and no tool brings them back. The last folder of a vault cannot be deleted. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `folder` (string, required): The id of the folder to delete, as list-knowledge gives it.
- `move_to` (string, optional): The id of another folder of the vault, as list-knowledge gives it, to move the notes and lists of the deleted folder to. Without it, the notes and lists are deleted too.

#### `create-knowledge-note` (changes data)

Write a note in a vault's Knowledge. The text is Markdown: # for a heading, - for a bullet, - [ ] for a task, > for a quote. Without a folder it goes to the first folder, and a vault without any gets "General". A note links to no contact, possession or other note. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `title` (string, optional): The title of the note. "Untitled note" when left out.
- `body` (string, optional): The text of the note, in Markdown.
- `folder_id` (string, optional): The id of the folder to write the note in, as list-knowledge gives it.

#### `update-knowledge-note` (changes data)

Change a note of a vault's Knowledge: its title, its text, or the folder it sits in. The text replaces the whole text, so read the note with get-knowledge-note first and send it back changed. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `note` (string, required): The id of the note, as list-knowledge gives it.
- `title` (string, optional): The new title. A blank title keeps the title the note has.
- `body` (string, optional): The whole new text, in Markdown. An empty text clears the text of the note.
- `folder_id` (string, optional): The id of the folder to move the note to, as list-knowledge gives it.

#### `delete-knowledge-note` (changes data)

Delete a note of a vault's Knowledge for good. No tool brings it back. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `note` (string, required): The id of the note, as list-knowledge gives it.

#### `create-knowledge-list` (changes data)

Start a list in a vault's Knowledge, with the columns "Name" and "Note". Rename or add columns with update-knowledge-list-column and create-knowledge-list-column, then add items with create-knowledge-list-item. Without a folder it goes to the first folder. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `title` (string, optional): The title of the list. "Untitled list" when left out.
- `description` (string, optional): What the list is for, in Markdown.
- `folder_id` (string, optional): The id of the folder to put the list in, as list-knowledge gives it.

#### `update-knowledge-list` (changes data)

Change a list of a vault's Knowledge: its title, its description, or the folder it sits in. Its columns and items change through their own tools. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `list` (string, required): The id of the list, as list-knowledge gives it.
- `title` (string, optional): The new title. A blank title keeps the title the list has.
- `description` (string, optional): The new description, in Markdown. An empty description clears the description of the list.
- `folder_id` (string, optional): The id of the folder to move the list to, as list-knowledge gives it.

#### `delete-knowledge-list` (changes data)

Delete a list of a vault's Knowledge for good, with its columns and every item in it. No tool brings it back. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `list` (string, required): The id of the list, as list-knowledge gives it.

#### `create-knowledge-list-column` (changes data)

Add a column to a list of a vault's Knowledge, after its other columns. Every column holds text. Answers with the whole list. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `list` (string, required): The id of the list, as list-knowledge gives it.
- `name` (string, required): The name of the column, such as City or Rating.

#### `update-knowledge-list-column` (changes data)

Rename a column of a list of a vault's Knowledge, move it among the columns, or both. Answers with the whole list. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `list` (string, required): The id of the list, as list-knowledge gives it.
- `column` (string, required): The id of the column, as get-knowledge-list gives it.
- `name` (string, optional): The new name of the column.
- `position` (integer, optional): Where the column goes, 1 for first. A number past the end puts the column last.

#### `delete-knowledge-list-column` (changes data)

Remove a column from a list of a vault's Knowledge, with what every item holds in it. No tool brings it back. The last column of a list cannot be removed. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `list` (string, required): The id of the list, as list-knowledge gives it.
- `column` (string, required): The id of the column, as get-knowledge-list gives it.

#### `create-knowledge-list-item` (changes data)

Add an item to a list of a vault's Knowledge, after its other items. Its texts are keyed by the id of their column, as get-knowledge-list gives it, and take Markdown. An item with every text blank is refused. Answers with the whole list. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `list` (string, required): The id of the list, as list-knowledge gives it.
- `cells` (object, required): The texts of the item, keyed by the id of their column.

#### `update-knowledge-list-item` (changes data)

Change the texts of an item of a list of a vault's Knowledge. Only the columns given change, and an empty text empties its cell. An item left with every text blank is refused. Answers with the whole list. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `list` (string, required): The id of the list, as list-knowledge gives it.
- `item` (string, required): The id of the item, as get-knowledge-list gives it.
- `cells` (object, required): The texts to change, keyed by the id of their column.

#### `delete-knowledge-list-item` (changes data)

Delete an item of a list of a vault's Knowledge for good, with everything written in it. No tool brings it back. The change is written to the account log.

- `vault` (string, required): The id of the vault, as list-vaults gives it.
- `list` (string, required): The id of the list, as list-knowledge gives it.
- `item` (string, required): The id of the item, as get-knowledge-list gives it.

### Account logs

#### `list-logs`

List the entries of the account log, newest first, a page at a time: who did what, where it came from and from which IP.

- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many entries a page holds: 25 unless asked, 100 at most.

#### `get-log`

Read one entry of the account log.

- `log` (string, required): The id of the entry, as list-logs gives it.

#### `list-emails-sent`

List the emails sent to the account, newest first, a page at a time, and whether each arrived. The copy of each email is left out; read one to see it.

- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many emails a page holds: 25 unless asked, 100 at most.

#### `get-email-sent`

Read one email sent to the account: its kind, subject, email address, what it said with links and URLs removed, and whether it arrived.

- `email_sent` (string, required): The id of the email, as list-emails-sent gives it.

### Support

#### `list-support-requests`

List the support requests the account has opened, the most recently updated first, a page at a time: number, subject, category and status. A status of waiting_on_user means the support team has replied.

- `status` (string, optional): Only the requests in this status. One of: `to_handle`, `waiting_on_user`, `solved`.
- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many requests a page holds: 25 unless asked, 100 at most.

#### `get-support-request`

Read one support request of the account with its whole thread: what the user wrote, the replies of the support team, and the names and sizes of the files sent. The content of a file is not returned.

- `support_request` (string, required): The id of the support request, as list-support-requests gives it.

#### `create-support-request` (changes data)

Ask the people who run this instance for help. Pick a category, write a subject and a message of at least 10 characters. A person reads it and replies by email and in the request. The user is sent a copy. Files cannot be sent from here.

- `category` (string, required): What it is about: feature, billing, email (emails not received), question, or technical (something broken). One of: `feature`, `billing`, `email`, `question`, `technical`.
- `subject` (string, required): A short summary.
- `body` (string, required): What is going on, as plain text, at least 10 characters.

#### `add-support-message` (changes data)

Write to the support team in a request already opened. The request goes back to the support team, and a solved request is reopened under the same number. Files cannot be sent from here.

- `support_request` (string, required): The id of the support request, as list-support-requests gives it.
- `body` (string, required): What to write, as plain text.

#### `solve-support-request` (changes data)

Tell the support team a request needs nothing more. Writing in it again reopens it.

- `support_request` (string, required): The id of the support request, as list-support-requests gives it.

### Support queue

#### `list-support-queue`

For an administrator of the instance: list the support requests of every account, oldest first, in one view (to_handle by default, waiting_on_user, solved or all), with the count of each view. Filter by text, category, user id or age (day, week, old).

- `view` (string, optional): Which requests to list. One of: `to_handle`, `waiting_on_user`, `solved`, `all`.
- `q` (string, optional): Words found in the subject, a message, the name or the email address of the user, or the request number.
- `category` (string, optional): Only this category. One of: `feature`, `billing`, `email`, `question`, `technical`.
- `user` (integer, optional): Only the requests of this user id.
- `age` (string, optional): Opened in the last day, between one and seven days ago, or longer ago. One of: `day`, `week`, `old`.
- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many requests a page holds: 25 unless asked, 100 at most.

#### `get-support-queue-request`

For an administrator of the instance: read one support request of any account with its whole thread, internal notes included, a few facts about the account, and how its status moved.

- `support_request` (string, required): The id of the support request, as list-support-queue gives it.

#### `send-support-reply` (changes data)

For an administrator of the instance: answer a support request. The reply is emailed to the user, shown in their request and signed with the administrator name, and the request moves to the status given (waiting_on_user by default).

- `support_request` (string, required): The id of the support request, as list-support-queue gives it.
- `body` (string, required): The reply, as plain text.
- `status` (string, optional): Where the request moves after the reply. One of: `to_handle`, `waiting_on_user`, `solved`.

#### `add-support-note` (changes data)

For an administrator of the instance: leave an internal note on a support request for the other administrators. The user never sees it and is never told it exists. The status does not change.

- `support_request` (string, required): The id of the support request, as list-support-queue gives it.
- `body` (string, required): The note, as plain text.

#### `change-support-request-status` (changes data)

For an administrator of the instance: move a support request to another status (to_handle, waiting_on_user or solved). The move is written to its status history. Nobody is emailed.

- `support_request` (string, required): The id of the support request, as list-support-queue gives it.
- `status` (string, required): The status to move the request to. One of: `to_handle`, `waiting_on_user`, `solved`.

### Feedback

#### `submit-feedback` (changes data)

Report a problem with this MCP server to the administrators of this Monica instance: a tool that failed or returned something wrong, a tool that was missing, a description that misled you, or an improvement. Call it at most once per task, and only when a tool got in the way. Never call it to log progress, to test it, or when the task went fine. Paraphrase what the person asked, and use placeholders such as <contact> or <date> instead of names, dates and other details from their vault. Never include secrets.

- `kind` (string, required): bug: a tool failed or returned something wrong; missing_tool: no tool could do it; unclear_description: a description misled you; improvement: a suggestion. One of: `bug`, `missing_tool`, `unclear_description`, `improvement`.
- `severity` (string, required): blocks_task: you could not finish; needs_workaround: you finished another way; minor: you finished, with friction. One of: `blocks_task`, `needs_workaround`, `minor`.
- `title` (string, required): One line naming the problem, at most 200 characters.
- `tool` (string, optional): The tool the report is about, or the name of the tool that is missing.
- `request` (string, optional): What the person asked, paraphrased, without names or details from their vault.
- `steps` (array, optional): The tool calls you tried, in order, at most 20.
- `observed` (string, required): What happened, including any error message.
- `expected` (string, required): What should have happened.
- `proposed_fix` (string, required): The fix you suggest.
- `proposed_code` (string, optional): Code for the fix, if you have some.
- `model` (string, optional): The model you run on.

### Agent feedback queue

#### `list-agent-feedback`

For an administrator of the instance: list the reports AI agents sent with submit-feedback, newest first, in one status (new by default, accepted, fixed, dismissed or all), with the count of each status. Filter by text, kind or severity.

- `status` (string, optional): Which reports to list. One of: `new`, `accepted`, `fixed`, `dismissed`, `all`.
- `q` (string, optional): Words found in the title, the tool, or the name or email address of the user.
- `kind` (string, optional): Only this kind. One of: `bug`, `missing_tool`, `unclear_description`, `improvement`.
- `severity` (string, optional): Only this severity. One of: `blocks_task`, `needs_workaround`, `minor`.
- `page` (integer, optional): The page to read, starting at 1.
- `per_page` (integer, optional): How many reports a page holds: 25 unless asked, 100 at most.

#### `get-agent-feedback`

For an administrator of the instance: read one report an AI agent sent with submit-feedback, with what it tried, what it observed and expected, the fix it suggests, and the notes administrators left.

- `report` (string, required): The id of the report, as list-agent-feedback gives it.

#### `add-agent-feedback-note` (changes data)

For an administrator of the instance: leave a note on an agent feedback report for the other administrators. Nobody else reads it. The status does not change.

- `report` (string, required): The id of the report, as list-agent-feedback gives it.
- `body` (string, required): The note, as plain text.

#### `change-agent-feedback-status` (changes data)

For an administrator of the instance: move an agent feedback report. A new report can be accepted or dismissed, an accepted one fixed or dismissed, and a fixed or dismissed one reopened to new. The move is written to the administrator log.

- `report` (string, required): The id of the report, as list-agent-feedback gives it.
- `status` (string, required): The status to move the report to. One of: `new`, `accepted`, `fixed`, `dismissed`.

## Edit a template

A template changes through a draft. Its sections and fields can only change on a draft version, and nothing reaches the records it describes until the draft is published. Deleting a draft throws its changes away.

A field can come back with a new id when its section had to be drafted first. Use the id the tool returns.

Asked to add a Hobbies section with a text field and a date field, an assistant calls:

1. `list-templates`, to find the template.
2. `create-template-draft`, to open a draft and learn its version number.
3. `add-template-section` with the name **Hobbies**, which returns the id of the new section.
4. `create-template-field` twice: a text field named **Hobby**, then a date field named **Started**.
5. `get-template-version`, to check the draft.
6. `publish-template-version`, with a note saying what changed.

## Troubleshooting

- **The assistant is refused.** With a key, the key is wrong or revoked: create a new one in **Settings → Security and access → API keys** and update your configuration. With OAuth, the assistant was disconnected or its access expired: remove the connector, add it again, and choose **Allow**.
- **The server cannot be reached.** Check that the address ends in `/mcp` and that your instance is reachable from the machine running the assistant.
- **The key is empty.** The assistant cannot see `MONICA_API_KEY`. Set it in the environment the assistant starts from, then restart it. Desktop apps often do not read your terminal’s variables.
- **Too many requests.** The assistant reached the limit of 60 requests a minute for its key or its connection. Wait a minute and ask again.

## See also

- [API reference](https://my.monicahq.com/docs/api)
- [API keys and connected assistants](https://my.monicahq.com/settings/account/security)
- [Logs](https://my.monicahq.com/settings/account/logs)
