# Add a possession

`POST /api/v1/vaults/{vault}/possessions`

Record something kept in a vault. Write the values of its fields afterwards.

How it was acquired is not written here: record it as a transaction of the possession. Sending acquisition, acquired_from_id or acquired_on answers 422.

Left out, a possession is owned, counts one and is not featured.

A type or a location of another account answers 422 on type_id or location_id. The change is written to the account log.

## Parameters

- `vault` (string, required): The vault the possession is kept in, named either by the readable name it reports as slug or by its id. A vault of another account answers 404.
- `type_id` (uuid, required): The possession type of the thing. A type of another account is refused. The type cannot be changed later.
- `name` (string, required): What the thing is called. Up to 255 characters. Markup and surrounding blank space are stripped, and a name left with nothing in it is refused with “Write a name for this possession.”
- `description` (string, optional): Free text about the thing, up to 2,000 characters. Null or blank, there is none.
- `location_id` (uuid, optional): The location the thing is kept in. Null, there is none. A location of another account is refused.
- `identifier` (string, optional): A serial number, a licence plate or any other reference, up to 255 characters. Null or blank, there is none.
- `status` (string, optional, defaults to owned): One of owned, ordered, sold, given_away, lost, stolen or thrown_away.
- `quantity` (integer, optional, defaults to 1): How many there are, between 1 and 1,000,000.
- `is_featured` (boolean, optional, defaults to false): Whether the thing is featured. A possession becoming featured is placed last among the featured possessions of the vault.
- `declared_value` (number, optional): What it would cost to replace today, from 0 to 9999999999.99, kept with two decimals.
- `declared_value_currency` (string, optional): The currency of the declared value: usd, eur, gbp, cad, aud, chf, jpy, brl, inr or cny. Required with a value, and dropped without one.
- `tags` (array, optional): The names of the tags the thing carries, each up to 50 characters. A name matching a tag of the account, ignoring case, uses that tag; any other name creates a tag in the account.

## Returns

The possession object that was added, holding no value yet.

- `data` (object): The possession.
- `data.type` (string): Always possession. 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.name` (string): What the thing is called, such as World’s Best Boss mug.
- `data.attributes.description` (string): Free text about the thing, or null.
- `data.attributes.identifier` (string): A serial number, a licence plate or any other reference written on the thing, or null.
- `data.attributes.status` (string): Where the thing stands: owned, ordered, sold, given_away, lost, stolen or thrown_away.
- `data.attributes.quantity` (integer): How many of the thing there are, at least 1.
- `data.attributes.is_featured` (boolean): Whether the thing is featured, which places it in the order shown first in the vault.
- `data.attributes.position` (integer): Its place among the featured possessions of the vault, counting from 1, or null when it is not featured.
- `data.attributes.possession_type` (object): The kind of thing it is. It is chosen when the possession is added and never changes.
- `data.attributes.possession_type.id` (uuid): The id of the possession type.
- `data.attributes.possession_type.name` (string): What the type is called.
- `data.attributes.possession_type.colour` (string): The colour of the type, as a hexadecimal value.
- `data.attributes.possession_type.icon` (string): The icon of the type, one of the glyphs of the catalogue, or null.
- `data.attributes.location` (object): Where the thing is kept now, or null when nobody said.
- `data.attributes.location.id` (uuid): The id of the location.
- `data.attributes.location.name` (string): What the location is called.
- `data.attributes.values` (array): What the thing holds for the fields of its type, an empty list for a new possession.
- `data.attributes.acquisition` (object): How the thing was acquired, read from its acquisition transaction: the earliest purchase, exchange, gift received or inheritance. Each part is null without one. Change it through the transactions, since none of it can be written here.
- `data.attributes.acquisition.way` (string): The type of the acquisition transaction: purchase, exchange, gift_received or inheritance, or null.
- `data.attributes.acquisition.acquired_from` (object): Who it came from, or null when the transaction names nobody.
- `data.attributes.acquisition.acquired_on` (string): The day of the acquisition transaction, written as 2005-03-24, or null.
- `data.attributes.acquisition.transaction_id` (uuid): The id of the acquisition transaction, or null.
- `data.attributes.acquisition.declared_value` (object): What it would cost to replace today, or null.
- `data.attributes.acquisition.declared_value.amount` (string): The amount, a decimal with two digits after the point, such as 12.99.
- `data.attributes.acquisition.declared_value.currency` (string): The currency: usd, eur, gbp, cad, aud, chf, jpy, brl, inr or cny.
- `data.attributes.current_value` (object): What the thing is worth now: its latest valuation, else its declared value, else null. Read from its valuations, so it cannot be written here.
- `data.attributes.current_value.amount` (string): The amount, a decimal with two digits after the point, such as 15.00.
- `data.attributes.current_value.currency` (string): The currency of the amount, in lower case. Nothing is ever converted.
- `data.attributes.current_value.source` (string): Where the amount comes from: valuation or declared_value.
- `data.attributes.tags` (array): The tags the thing carries, sorted by name.
- `data.attributes.tags[]` (object): One tag.
- `data.attributes.tags[].id` (uuid): The id of the tag.
- `data.attributes.tags[].name` (string): What the tag reads.
- `data.attributes.tags[].colour` (string): The colour of the tag, as a hexadecimal value.
- `data.attributes.created_at` (timestamp): When the possession was added, as a count of seconds since 1970.
- `data.attributes.updated_at` (timestamp): When it last changed, as a count of seconds.
- `data.links` (object): Where to find this record.
- `data.links.self` (string): The absolute address this record is read from.

## 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/dunder-mifflin/possessions \
  -X POST \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "type_id": "9c1d4e7a-3b52-4f86-a0d9-2e7b6c418f35",
      "name": "World\u2019s Best Boss mug",
      "description": "Bought by Michael for Michael, from Spencer Gifts.",
      "location_id": "5b7e2c90-4d18-4a3f-9e61-0c8d2f7a1b43",
      "identifier": "WBB-0001",
      "status": "owned",
      "quantity": 1,
      "is_featured": true,
      "declared_value": 12.99,
      "declared_value_currency": "usd",
      "tags": [
          "insured"
      ]
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type_id: '9c1d4e7a-3b52-4f86-a0d9-2e7b6c418f35',
    name: 'World’s Best Boss mug',
    description: 'Bought by Michael for Michael, from Spencer Gifts.',
    location_id: '5b7e2c90-4d18-4a3f-9e61-0c8d2f7a1b43',
    identifier: 'WBB-0001',
    status: 'owned',
    quantity: 1,
    is_featured: true,
    declared_value: 12.99,
    declared_value_currency: 'usd',
    tags: ["insured"],
  }),
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->post('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions', [
    'type_id' => '9c1d4e7a-3b52-4f86-a0d9-2e7b6c418f35',
    'name' => 'World’s Best Boss mug',
    'description' => 'Bought by Michael for Michael, from Spencer Gifts.',
    'location_id' => '5b7e2c90-4d18-4a3f-9e61-0c8d2f7a1b43',
    'identifier' => 'WBB-0001',
    'status' => 'owned',
    'quantity' => 1,
    'is_featured' => true,
    'declared_value' => 12.99,
    'declared_value_currency' => 'usd',
    'tags' => ['insured'],
]);
```

## Response

`201`

```json
{
    "data": {
        "type": "possession",
        "id": "6e2b9d41-8c37-4f15-a0d6-3b7e1c9f2a84",
        "attributes": {
            "name": "World’s Best Boss mug",
            "description": "Bought by Michael for Michael, from Spencer Gifts.",
            "identifier": "WBB-0001",
            "status": "owned",
            "quantity": 1,
            "is_featured": true,
            "position": 1,
            "possession_type": {
                "id": "9c1d4e7a-3b52-4f86-a0d9-2e7b6c418f35",
                "name": "Office equipment",
                "colour": "#2f7f86",
                "icon": "briefcase"
            },
            "location": {
                "id": "5b7e2c90-4d18-4a3f-9e61-0c8d2f7a1b43",
                "name": "Dunder Mifflin Scranton"
            },
            "values": [],
            "acquisition": {
                "way": null,
                "acquired_from": null,
                "acquired_on": null,
                "transaction_id": null,
                "declared_value": {
                    "amount": "12.99",
                    "currency": "usd"
                }
            },
            "current_value": {
                "amount": "12.99",
                "currency": "usd",
                "source": "declared_value"
            },
            "tags": [
                {
                    "id": "1e6b9d47-3c28-4f71-a5e0-9d4c2b8f6a13",
                    "name": "insured",
                    "colour": "#3f5fd0"
                }
            ],
            "created_at": 1761523200,
            "updated_at": 1761523200
        },
        "links": {
            "self": "https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/6e2b9d41-8c37-4f15-a0d6-3b7e1c9f2a84"
        }
    }
}
```
