Skip to main content
POST https://api.craftkit.dev/v1/renders/:id/events
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

​
Authorization
string
required
Bearer ck_live_… — a project API key.

​
Path parameters

​
id
string
required
The render id. Must belong to this key’s project.

​
Body

​
eventType
string
required
One of viewed, downloaded, printed. The other engagement types (email_*, share_*) are recorded by the system, not this route.
​
metadata
object
Optional free-form key/value bag (string keys, any JSON values) stored verbatim with the event.
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.

​
Response

200 with whether the event was written.
​
recorded
boolean
true if the event was inserted, false if it was deduped within the 5-minute window.

​
Errors

StatuscodeMeaning
400invalid_jsonBody is not valid JSON.
400invalid_requestBody failed schema validation (issues included).
401unauthorizedMissing, invalid, or revoked key.
403forbiddenKey’s project no longer exists.
404not_foundNo render with that id in this key’s project.
cURL
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" }
  }'
200
{
  "recorded": true
}