> ## Documentation Index
> Fetch the complete documentation index at: https://docs.craftkit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Track an event

> POST /v1/renders/:id/events — record a partner-side engagement event from your own viewer UI.

<Info>**POST** `https://api.craftkit.dev/v1/renders/:id/events`</Info>

Records a partner-side engagement event for a render. Every event written here is stamped
`actorKind: "partner"` — recipient-side `viewed`/`downloaded`/`printed` events are recorded
server-side by the public share page, not through this route.

## Authorization

<ParamField header="Authorization" type="string" required>
  `Bearer ck_live_…` — a project API key.
</ParamField>

## Path parameters

<ParamField path="id" type="string" required>The render id. Must belong to this key's project.</ParamField>

## Body

<ParamField body="eventType" type="string" required>
  One of `viewed`, `downloaded`, `printed`. The other engagement types (`email_*`, `share_*`) are
  recorded by the system, not this route.
</ParamField>

<ParamField body="metadata" type="object">
  Optional free-form key/value bag (string keys, any JSON values) stored verbatim with the event.
</ParamField>

<Info>
  `viewed`, `downloaded`, and `printed` are deduped within a 5-minute window keyed on
  `(shareId, eventType, sourceIp)`. A duplicate inside that window returns `{ "recorded": false }`
  and is not stored.
</Info>

## Response

`200` with whether the event was written.

<ResponseField name="recorded" type="boolean">
  `true` if the event was inserted, `false` if it was deduped within the 5-minute window.
</ResponseField>

## Errors

| Status | code              | Meaning                                            |
| ------ | ----------------- | -------------------------------------------------- |
| 400    | `invalid_json`    | Body is not valid JSON.                            |
| 400    | `invalid_request` | Body failed schema validation (`issues` included). |
| 401    | `unauthorized`    | Missing, invalid, or revoked key.                  |
| 403    | `forbidden`       | Key's project no longer exists.                    |
| 404    | `not_found`       | No render with that id in this key's project.      |

```bash cURL theme={null}
curl -X POST https://api.craftkit.dev/v1/renders/$RENDER_ID/events \
  -H "Authorization: Bearer $CRAFTKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eventType": "downloaded",
    "metadata": { "source": "dashboard" }
  }'
```

```json 200 theme={null}
{
  "recorded": true
}
```