API v1
v1
View as Markdown

Change a possession

PUT /api/v1/vaults/{vault}/possessions/{possession}

Change what is known of a possession. Its type never changes, and its values are written separately.

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.

Send only what changes. The name, the status, the quantity and is_featured cannot be null. The description, the location, the identifier and the declared value are cleared by null, and tags sent as null or empty remove every tag. Tags sent replace the tags the thing carries.

A possession becoming featured is placed last among the featured possessions of the vault. One that stops being featured leaves the order, and the others close the gap.

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

Parameters

Sent as JSON. Anything not listed here is ignored.

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.

possession uuid Required

The id of the possession. A possession of another vault or of another account answers 404.

name string Optional

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

One of owned, ordered, sold, given_away, lost, stolen or thrown_away.

quantity integer Optional

How many there are, between 1 and 1,000,000.

is_featured boolean Optional

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 as it now reads. A vault or a possession of another account answers 404.

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, in the order of the fields: the groups first, then the standalone fields. A field holding nothing is left out.

data.attributes.values[] object

One value.

data.attributes.values[].field_id uuid

The id of the field, which is the key to send when writing its value.

data.attributes.values[].name string

What the field is called.

data.attributes.values[].kind string

What the field holds: text, number, date, boolean, select or rating.

data.attributes.values[].group string

The name of the group the field sits in, or null when it stands alone.

data.attributes.values[].value string

The value, as the kind of the field reads it: a string for text, a date written as 2005-03-24 and a choice, a number for a number, an integer from 1 to 5 for a rating, and true or false for a boolean.

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_from.name string

The counterparty of the acquisition transaction, as text.

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.

PUT
curl https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/6e2b9d41-8c37-4f15-a0d6-3b7e1c9f2a84 \
-X PUT \
-H "Authorization: Bearer $MONICA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"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"
]
}'
const response = await fetch('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/6e2b9d41-8c37-4f15-a0d6-3b7e1c9f2a84', {
method: 'PUT',
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
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()
$response = Http::withToken($token)->put('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/6e2b9d41-8c37-4f15-a0d6-3b7e1c9f2a84', [
'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 200
{
"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": [
{
"field_id": "b7e04a93-1c6f-4d28-9a35-6f8e2d1c4b90",
"name": "Payment method",
"kind": "select",
"group": "Purchase",
"value": "Card"
},
{
"field_id": "e5c37a28-9f14-4b6d-a083-7d2e1f9b6c45",
"name": "Condition",
"kind": "select",
"group": null,
"value": "Used"
},
{
"field_id": "2d8b5f1e-6a47-4c93-8e02-1b9f7c3a5d64",
"name": "Serial number",
"kind": "text",
"group": null,
"value": "SG-2005-0324"
}
],
"acquisition": {
"way": "gift_received",
"acquired_from": {
"name": "Jim Halpert"
},
"acquired_on": "2005-03-24",
"transaction_id": "8f3a6c21-4e97-4b05-9d18-7a2c5e0f9b36",
"declared_value": {
"amount": "12.99",
"currency": "usd"
}
},
"current_value": {
"amount": "15.00",
"currency": "usd",
"source": "valuation"
},
"tags": [
{
"id": "1e6b9d47-3c28-4f71-a5e0-9d4c2b8f6a13",
"name": "insured",
"colour": "#3f5fd0"
}
],
"created_at": 1761523200,
"updated_at": 1761526800
},
"links": {
"self": "https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/6e2b9d41-8c37-4f15-a0d6-3b7e1c9f2a84"
}
}
}

Keys act as you, with exactly the access you have. Make one per integration so you can revoke it alone.