## Create a provenance event

`POST https://getkollek.com/api/copies/{copy}/provenance-events`

Record a moment in the story of a copy.

No amounts live here. Prices, taxes, fees and shipping belong to the transaction and are never duplicated onto the event, so an event that came from an exchange sets `transaction_id` and you read the money from the transaction itself.

A transaction is one exchange, so it can be the source of at most one event. Deleting a linked transaction unlinks the event rather than deleting it: the moment in the object story outlives the record of what was paid for it.

Provenance dates are frequently uncertain, so every date is paired with `occurred_at_precision`. A precision of unknown stores no date at all, and `formatted_date` is the read only rendering of the date at its precision, which is what you should show rather than formatting `occurred_at` yourself.

**Permissions:** Owners and editors. Viewers get a 404 response.

### Path parameters

- `copy` (integer, required): The ID of the copy the provenance event belongs to.

### Body parameters

- `type` (string, required): What kind of moment this records. One of acquisition, sale, gift, inheritance, ownership_transfer, custody_transfer, loan, return, exhibition, authentication, appraisal, significant_restoration, origin, discovery or other.
- `title` (string, required): A short summary of the moment, shown in the timeline.
- `description` (string, optional): The detail behind the title.
- `occurred_at` (string, optional): When it happened, in YYYY-MM-DD format. Ignored when the precision is unknown, in which case no date is stored at all.
- `occurred_at_precision` (string, optional): How much of the date is actually known. One of exact, month, year, approximate or unknown. Default: `exact`.
- `location` (string, optional): Where it happened.
- `from_party` (string, optional): Who the object came from.
- `to_party` (string, optional): Who the object went to.
- `reference_number` (string, optional): An auction lot, a certificate number or an archive reference.
- `source_url` (string, optional): A link to where the event can be checked.
- `is_verified` (boolean, optional): Whether evidence backs this event. Default: `false`.
- `verification_note` (string, optional): How it was verified. Dropped when is_verified is false, since a note about how something was verified means nothing when it was not.
- `transaction_id` (integer, optional): The transaction this event came from. It must belong to the same copy and must not already carry another event, otherwise the request returns 404.

**Returns:** The created provenance event object.

### Example request

```bash
curl https://getkollek.com/api/copies/1/provenance-events \
  -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "acquisition",
    "title": "Bought at the Central Perk estate sale",
    "description": "Sold as part of the Gunther estate, lot 42.",
    "occurred_at": "1987-06-15",
    "occurred_at_precision": "year",
    "location": "New York",
    "from_party": "Central Perk Collectibles",
    "to_party": "Ross Geller",
    "reference_number": "LOT-1994",
    "source_url": "https://example.com/lots/1994",
    "is_verified": "true",
    "verification_note": "Certificate held on file.",
    "transaction_id": "1"
}'
```

### Example response

`Status: 201`

```json
{
    "data": {
        "type": "provenance_event",
        "id": "1",
        "attributes": {
            "copy_id": "1",
            "transaction_id": null,
            "type": "origin",
            "title": "Printed in New York",
            "description": null,
            "occurred_at": 550972800,
            "occurred_at_precision": "year",
            "formatted_date": "1987",
            "location": "New York",
            "from_party": "Central Perk Collectibles",
            "to_party": "Ross Geller",
            "reference_number": null,
            "source_url": null,
            "is_verified": false,
            "verification_note": null,
            "created_at": 1752537600,
            "updated_at": 1752537600
        },
        "links": {
            "self": "https://getkollek.com/api/copies/1/provenance-events/1"
        }
    }
}
```