# Record a provenance event

`POST /api/v1/vaults/{vault}/possessions/{possession}/provenance`

Record one moment in the provenance of a possession.

Only the type is required. The change is written to the account log.

## 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.
- `type` (string, required): What happened: origin, acquisition, inheritance, gift, sale, custody, loss, recovery, authentication, exhibition, publication or other.
- `date_precision` (string, optional, defaults to day): How much of the date is known: day, month, year, circa or unknown.
- `occurred_on` (string, optional): When it happened, in the shape its precision gives: 1980-01-20, 1980-01 or 1980. A date in another shape is refused with “Write the date in the shape its precision asks for.” Ignored when the precision is unknown.
- `title` (string, optional): What happened in a few words, up to 255 characters. Markup is stripped.
- `from` (string, optional): Who it came from, up to 255 characters.
- `to` (string, optional): Who held it afterwards, up to 255 characters.
- `location` (string, optional): Where it happened, up to 255 characters.
- `description` (string, optional): What happened and how it is known, up to 5,000 characters.
- `reference_number` (string, optional): The reference of the record, up to 255 characters.
- `source_url` (string, optional): A full web address where the event can be checked, up to 255 characters.
- `transaction_id` (uuid, optional): The id of a transaction of the same possession that records what the moment cost. A transaction of another possession answers 422.
- `is_verified` (boolean, optional, defaults to false): Whether a document, a record or an expert confirms the event.

## Returns

The provenance event object that was recorded.

- `data` (object): The possession provenance event.
- `data.type` (string): Always possession_provenance_event. 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.type` (string): What happened: origin, acquisition, inheritance, gift, sale, custody, loss, recovery, authentication, exhibition, publication or other.
- `data.attributes.group` (string): The group the type belongs to: ownership, custody or authenticity.
- `data.attributes.title` (string): What happened in a few words, or null, in which case the application shows the name of the type.
- `data.attributes.date_precision` (string): How much of the date is known: day, month, year, circa or unknown.
- `data.attributes.occurred_on` (string): When it happened, in the shape its precision gives: 1980-01-20 for a day, 1980-01 for a month, 1980 for a year or around a year, null when unknown.
- `data.attributes.from` (string): Who it came from, as text, or null.
- `data.attributes.to` (string): Who held it afterwards, as text, or null.
- `data.attributes.location` (string): Where it happened, as text, or null.
- `data.attributes.description` (string): What happened and how it is known, or null.
- `data.attributes.reference_number` (string): The reference of the record (a lot, a deed, a certificate), or null.
- `data.attributes.source_url` (string): Where the event can be checked, or null.
- `data.attributes.is_verified` (boolean): Whether a document, a record or an expert confirms the event.
- `data.attributes.transaction_id` (uuid): The id of the transaction of the same possession that records what the moment cost, or null. An event holds no money of its own.
- `data.attributes.created_at` (timestamp): When the event 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 Provenance 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/provenance \
  -X POST \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "type": "gift",
      "date_precision": "day",
      "occurred_on": "1980-01-20",
      "title": "Given to Dwight for his tenth birthday",
      "from": "Dwight Schrute Sr.",
      "to": "Dwight Schrute",
      "location": "Schrute Farms",
      "reference_number": "Family ledger, page 12",
      "transaction_id": "2f6d8a41-9b37-4c05-a7e2-5d1c3b9f8e64",
      "is_verified": true
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/vaults/schrute-farms/possessions/5e1b7c93-4a28-4d6f-9b02-7c3e8a1f4d60/provenance', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'gift',
    date_precision: 'day',
    occurred_on: '1980-01-20',
    title: 'Given to Dwight for his tenth birthday',
    from: 'Dwight Schrute Sr.',
    to: 'Dwight Schrute',
    location: 'Schrute Farms',
    reference_number: 'Family ledger, page 12',
    transaction_id: '2f6d8a41-9b37-4c05-a7e2-5d1c3b9f8e64',
    is_verified: true,
  }),
})
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/provenance', [
    'type' => 'gift',
    'date_precision' => 'day',
    'occurred_on' => '1980-01-20',
    'title' => 'Given to Dwight for his tenth birthday',
    'from' => 'Dwight Schrute Sr.',
    'to' => 'Dwight Schrute',
    'location' => 'Schrute Farms',
    'reference_number' => 'Family ledger, page 12',
    'transaction_id' => '2f6d8a41-9b37-4c05-a7e2-5d1c3b9f8e64',
    'is_verified' => true,
]);
```

## Response

`201`

```json
{
    "data": {
        "type": "possession_provenance_event",
        "id": "c47e9b20-1d53-4a8f-9e6c-2b8d5f1a3e97",
        "attributes": {
            "type": "gift",
            "group": "ownership",
            "title": "Given to Dwight for his tenth birthday",
            "date_precision": "day",
            "occurred_on": "1980-01-20",
            "from": "Dwight Schrute Sr.",
            "to": "Dwight Schrute",
            "location": "Schrute Farms",
            "description": null,
            "reference_number": "Family ledger, page 12",
            "source_url": null,
            "is_verified": true,
            "transaction_id": "2f6d8a41-9b37-4c05-a7e2-5d1c3b9f8e64",
            "created_at": 1773450000
        },
        "links": {
            "self": "https://my.monicahq.com/api/v1/vaults/schrute-farms/possessions/5e1b7c93-4a28-4d6f-9b02-7c3e8a1f4d60/provenance/c47e9b20-1d53-4a8f-9e6c-2b8d5f1a3e97",
            "web": "https://my.monicahq.com/vaults/schrute-farms/possessions/5e1b7c93-4a28-4d6f-9b02-7c3e8a1f4d60/provenance"
        }
    }
}
```
