# Correct a stay

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

Correct one stay of a possession.

What you leave out keeps its value, and what you send as null is cleared. Only this stay changes: the stays before and after it are not moved. Correcting the location of the open stay changes where the possession is now. The change is written to the account log.

A past stay without a day it left answers 422 on left_on ("Enter the day it left."), as does a day it left before the day it arrived ("This is before the day it arrived."). The open stay cannot be given a day it left ("Move the possession to close the current stay.").

## 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.
- `stay` (uuid, required): The id of the stay. A stay of another possession answers 404.
- `location_id` (uuid, optional): The id of a location of the account.
- `arrived_on` (date, optional): The day it arrived, as YYYY-MM-DD, or null when unknown.
- `left_on` (date, optional): The day it left, as YYYY-MM-DD. Only for a past stay.
- `reason` (string, optional): Why it was there, up to 255 characters.
- `note` (string, optional): Anything worth knowing about the stay, up to 5,000 characters.

## Returns

The stay object, as it now stands. A stay of another possession or of another account answers 404.

- `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/3b9e4f27-8d61-4c0a-a5f3-1e7c2d9b6a48 \
  -X PUT \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "reason": "After the harvest"
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/vaults/schrute-farms/possessions/5e1b7c93-4a28-4d6f-9b02-7c3e8a1f4d60/location-stays/3b9e4f27-8d61-4c0a-a5f3-1e7c2d9b6a48', {
  method: 'PUT',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    reason: 'After the harvest',
  }),
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->put('https://my.monicahq.com/api/v1/vaults/schrute-farms/possessions/5e1b7c93-4a28-4d6f-9b02-7c3e8a1f4d60/location-stays/3b9e4f27-8d61-4c0a-a5f3-1e7c2d9b6a48', [
    'reason' => 'After the harvest',
]);
```

## Response

`200`

```json
{
    "data": {
        "type": "possession_location_stay",
        "id": "3b9e4f27-8d61-4c0a-a5f3-1e7c2d9b6a48",
        "attributes": {
            "location_id": "9c4a1e7f-2b58-4d36-8e09-5f3b7a1c6d24",
            "location_name": "Barn",
            "arrived_on": "2019-11-08",
            "left_on": "2024-06-04",
            "is_current": false,
            "reason": "After the harvest",
            "note": null,
            "created_at": 1773446400
        },
        "links": {
            "self": "https://my.monicahq.com/api/v1/vaults/schrute-farms/possessions/5e1b7c93-4a28-4d6f-9b02-7c3e8a1f4d60/location-stays/3b9e4f27-8d61-4c0a-a5f3-1e7c2d9b6a48",
            "web": "https://my.monicahq.com/vaults/schrute-farms/possessions/5e1b7c93-4a28-4d6f-9b02-7c3e8a1f4d60/locations"
        }
    }
}
```
