API v1
v1
View as Markdown

List possessions

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

List the possessions of a vault, sorted by name, each with its type, its location and its values.

A possession belongs to a vault. Its type and its location belong to the account, so the same type and the same location serve every vault.

Sorted by position, the featured possessions come first in their order, followed by every other possession sorted by name.

To go through everything a vault holds, ask for compact possessions with the largest page.

This endpoint also answers QUERY, with the same parameters sent in the request body. How QUERY works.

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.

type uuid Optional

Only the possessions of this possession type.

status string Optional

Only the possessions with this status: owned, ordered, sold, given_away, lost, stolen or thrown_away.

featured boolean Optional

Only the featured possessions when true, only the others when false.

location uuid Optional

Only the possessions kept at this location or at any location inside it. A location that is not one of the account answers 422.

sort string Optional default: name

Either name or position.

compact boolean Optional default: false

When true, each possession carries only its name, its status, the id and name of its type, its location and its current value, which is about a tenth of the full record. Get one possession for the rest.

page integer Optional default: 1

Which page to answer with.

per_page integer Optional default: 25

How many possessions one page holds, between 1 and 100. A number outside the range is brought back into it.

Returns

A page of possession objects, and how many there are in all. A vault with none answers an empty list, and a vault of another account answers 404.

data array

The possessions on this page. An empty list rather than an error when there are none.

data[] object

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

meta object

Where you are in the collection.

meta.page integer

The page this is, counting from 1.

meta.per_page integer

How many one page holds, which is the size that was asked for once it has been brought into the allowed range.

meta.total integer

How many possessions there are in all, not how many are on this page.

Rate limit

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

GET
curl https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions \
-H "Authorization: Bearer $MONICA_TOKEN"
const response = await fetch('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions', {
headers: { Authorization: `Bearer ${token}` },
})
const data = await response.json()
$response = Http::withToken($token)->get('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions');
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"
}
},
{
"type": "possession",
"id": "c4f81a27-5d93-4e60-b2a8-9e1d7c3b5f06",
"attributes": {
"name": "Chrysler Sebring",
"description": "Bought with the first commission check. Drove into a lake once, following the GPS.",
"identifier": null,
"status": "owned",
"quantity": 1,
"is_featured": false,
"position": null,
"possession_type": {
"id": "3a7f5c19-2e84-4d6b-9f03-8c1b6e4a2d57",
"name": "Vehicle",
"colour": "#3f5fd0",
"icon": "car"
},
"location": {
"id": "f19c3e6a-7b42-4d85-a0e7-2c6d9b1f8a34",
"name": "Scranton parking lot"
},
"values": [],
"acquisition": {
"way": null,
"acquired_from": null,
"acquired_on": null,
"transaction_id": null,
"declared_value": null
},
"current_value": null,
"tags": [],
"created_at": 1761526800,
"updated_at": 1761526800
},
"links": {
"self": "https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/c4f81a27-5d93-4e60-b2a8-9e1d7c3b5f06"
}
}
],
"meta": {
"page": 1,
"per_page": 25,
"total": 2
}
}

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