# Get a possession

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

Retrieve one possession with its type, its location and its values.

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

## Returns

A possession object. 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`.

## Request

```sh
curl https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/6e2b9d41-8c37-4f15-a0d6-3b7e1c9f2a84 \
  -H "Authorization: Bearer $MONICA_TOKEN"
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/6e2b9d41-8c37-4f15-a0d6-3b7e1c9f2a84', {
  headers: { Authorization: `Bearer ${token}` },
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->get('https://my.monicahq.com/api/v1/vaults/dunder-mifflin/possessions/6e2b9d41-8c37-4f15-a0d6-3b7e1c9f2a84');
```

## Response

`200`

```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": [
                {
                    "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"
        }
    }
}
```
