# Move a possession

`POST /api/v1/vaults/{vault}/possessions/{possession}/location-stays`

Move a possession to another location of the account on a given day.

The stay where it is now closes on that day, and a new stay opens at the location on the same day. The possession then reports that location as where it is. The change is written to the account log.

A possession that is sold, given away, thrown away, lost or stolen answers 422 on location_id ("This possession is no longer in your hands, so it cannot be moved."). The location it is already in answers 422 on location_id ("It is already in Barn."). A day before the current stay began answers 422 on moved_on ("The current stay began on 8 November 2019. Date the move after that, or correct the current stay instead.").

## 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.
- `location_id` (uuid, required): The id of a location of the account. A location of another account answers 422.
- `moved_on` (date, required): The day it moved, as YYYY-MM-DD.
- `reason` (string, optional): Why it moved, up to 255 characters. Markup is stripped.
- `note` (string, optional): Anything worth knowing about the new stay, up to 5,000 characters.

## Returns

The new stay object, where the possession is now.

- `data` (object): The possession location stay.
- `data.type` (string): Always possession_location_stay. 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.location_id` (uuid): The id of the location of the account where the possession stayed. Its full path comes from the locations endpoints.
- `data.attributes.location_name` (string): The name of that location, without the locations around it.
- `data.attributes.arrived_on` (date): The day it arrived, as YYYY-MM-DD, or null when the day is unknown.
- `data.attributes.left_on` (date): The day it left, as YYYY-MM-DD, or null on the stay where it is now.
- `data.attributes.is_current` (boolean): Whether it is the open stay, where the possession is now. A possession has at most one.
- `data.attributes.reason` (string): Why it went there, or null.
- `data.attributes.note` (string): Anything worth knowing about the stay, or null.
- `data.attributes.created_at` (timestamp): When the stay was recorded, as a count of seconds since 1970.
- `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 Locations section of the possession 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/schrute-farms/possessions/5e1b7c93-4a28-4d6f-9b02-7c3e8a1f4d60/location-stays \
  -X POST \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "location_id": "6e2f8b31-7c4d-4a95-b1e8-3d9c5a7f2e60",
      "moved_on": "2024-06-04",
      "reason": "Harvest season",
      "note": "Mose carried it down."
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/vaults/schrute-farms/possessions/5e1b7c93-4a28-4d6f-9b02-7c3e8a1f4d60/location-stays', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    location_id: '6e2f8b31-7c4d-4a95-b1e8-3d9c5a7f2e60',
    moved_on: '2024-06-04',
    reason: 'Harvest season',
    note: 'Mose carried it down.',
  }),
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->post('https://my.monicahq.com/api/v1/vaults/schrute-farms/possessions/5e1b7c93-4a28-4d6f-9b02-7c3e8a1f4d60/location-stays', [
    'location_id' => '6e2f8b31-7c4d-4a95-b1e8-3d9c5a7f2e60',
    'moved_on' => '2024-06-04',
    'reason' => 'Harvest season',
    'note' => 'Mose carried it down.',
]);
```

## Response

`201`

```json
{
    "data": {
        "type": "possession_location_stay",
        "id": "f1d72a8c-5e39-4b16-9c04-7a3e6b2d8f15",
        "attributes": {
            "location_id": "6e2f8b31-7c4d-4a95-b1e8-3d9c5a7f2e60",
            "location_name": "Cellar",
            "arrived_on": "2024-06-04",
            "left_on": null,
            "is_current": true,
            "reason": "Harvest season",
            "note": "Mose carried it down.",
            "created_at": 1773450000
        },
        "links": {
            "self": "https://my.monicahq.com/api/v1/vaults/schrute-farms/possessions/5e1b7c93-4a28-4d6f-9b02-7c3e8a1f4d60/location-stays/f1d72a8c-5e39-4b16-9c04-7a3e6b2d8f15",
            "web": "https://my.monicahq.com/vaults/schrute-farms/possessions/5e1b7c93-4a28-4d6f-9b02-7c3e8a1f4d60/locations"
        }
    }
}
```
