# Get a vault

`GET /api/v1/vaults/{vault}`

Retrieve one of your vaults: what it is called, what it is for, and how many contacts it holds.

A vault is a watertight compartment. Contacts, records of the kinds you invented, files and private links belong to exactly one, and nothing reaches across.

What a new contact in the vault starts from is not in here. A vault holds one of those per kind of record, so a single field would answer a narrower question than its name suggests. You can set the contact one when you create or update a vault, and reading them back is an endpoint of its own.

This endpoint also answers QUERY, with the same parameters sent in the request body. [How QUERY works](https://my.monicahq.com/docs/api/query-method).

## Path parameters

- `vault` (string, required): The vault, named either by the readable name it reports as slug or by its id. Both answer, whichever the account builds its own addresses from. A readable name is rebuilt whenever the record is renamed, and the previous one stops answering, so a client that stores a reference stores the id. A name a record has released is never given to another.

## Returns

A vault object. A vault belonging to somebody else answers 404, which is also what a vault that never existed answers, and what a deleted one answers.

- `data` (object): The vault.
- `data.type` (string): Always vault. It names the kind of record, so a caller holding several kinds can tell them apart without looking at where they came from.
- `data.id` (string): The id of this record, as a string even when it reads as a number. It is what every endpoint naming this record takes.
- `data.attributes` (object): Everything the record holds.
- `data.attributes.slug` (string): The readable name the vault is addressed by, built from its name and unique within your account. It is not stable: renaming the vault rebuilds it and the previous one stops answering, which is why a stored reference should be the id. Nothing lets you choose or edit it.
- `data.attributes.name` (string): What the vault is called. Up to 255 characters. Reduced to plain text when it was written down, so no markup survives here.
- `data.attributes.description` (string): What the vault is for, up to 65535 characters, or null when nobody said. Null is the ordinary state of a vault nobody described, not a sign of anything missing.
- `data.attributes.colour` (string): Exactly one of #3f5fd0, #4f8a49, #9a6a24, #9a3f2b, #6b4fa8, #2f7f86, #a8447a or #4a4a52, written in lower case. It is how vaults are told apart at a glance, and it is decoration: nothing depends on it.
- `data.attributes.position` (integer): Where the vault sits in your list, counting from 1. It is the order you arranged, and it is the order the list endpoint answers in.
- `data.attributes.is_default` (boolean): Whether records land here when nothing says which vault. Exactly one of your vaults is true while you hold a vault at all, and none is while you hold none.
- `data.attributes.contact_count` (integer): How many contacts the vault holds, counting the archived and the partial ones. It is a running count kept as contacts are written down and deleted, rather than something counted when you ask.
- `data.attributes.created_at` (timestamp): When the vault was opened, as a count of seconds since 1970 rather than a written date.
- `data.attributes.updated_at` (timestamp): When its wording last changed, as a count of seconds. Equal to created_at until it first changes.
- `data.links` (object): Where to find this record.
- `data.links.self` (string): The absolute address this record is read from.
- `data.links.web` (string): The page of the vault in the application, which opens for somebody signed in rather than for a key. It is the link to give a person.

## Rate limit

Sixty requests per minute, per user, shared by every key and device. Every answer carries the budget left in `X-RateLimit-Remaining`.

## Request

```sh
curl https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31 \
  -H "Authorization: Bearer $MONICA_TOKEN"
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31', {
  headers: { Authorization: `Bearer ${token}` },
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->get('https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31');
```

## Response

`200`

```json
{
    "data": {
        "type": "vault",
        "id": "9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31",
        "attributes": {
            "slug": "dunder-mifflin",
            "name": "Dunder Mifflin",
            "description": "Everybody at the Scranton branch.",
            "colour": "#4f8a49",
            "position": 1,
            "is_default": true,
            "contact_count": 12,
            "created_at": 1756252800,
            "updated_at": 1756339200
        },
        "links": {
            "self": "https://my.monicahq.com/api/v1/vaults/dunder-mifflin",
            "web": "https://my.monicahq.com/vaults/dunder-mifflin"
        }
    }
}
```
