Capture an event

Captures one event.

Authorize with the x-secret-key header from a server, or a publishable token in the body from an app or web page. Answers 202 with how many events were stored.

Guide: Event capture

Header parameters

x-secret-key?string

A project secret key, vh_sk_..., for requests from your servers. Leave it out when the body has a publishable token.

Request body

application/json

TypeScript definitions

Use the request body type in TypeScript.

uuid*string

The event's id: a UUID you generate once and send unchanged on every retry, so the event is stored once.

Length1 <= length

event*string

The event's name, such as paywall_viewed.

Length1 <= length

context*

Facts about the app and device that sent it, such as platform and app_version.

properties*

The event's properties, as JSON values. $set and $set_once hold traits to set on the person.

distinct_id*string

The distinct id of the person it happened to.

Length1 <= length

session_id?|

The session it belongs to, when the sender tracks sessions.

timestamp*string

When it happened on the device, as an ISO 8601 timestamp. Voidhash corrects it by how far the device's clock is off, measured with sent_at.

sent_at*string

When the request was sent, as an ISO 8601 timestamp. Voidhash compares it with when the request arrived to correct the events' times.

token?|

The project's publishable key, vh_pk_..., for clients that cannot hold a secret. Send it or the x-secret-key header; a secret key here is refused.

Examples

curl -X POST "https://api.voidhash.com/i/v1/capture" \  -H "x-secret-key: vh_sk_..." \  -H "Content-Type: application/json" \  -d '{    "uuid": "018f6d2e-4c3a-7b1d-9e5f-2a8c1b0d4e6f",    "event": "paywall_viewed",    "context": {      "platform": "ios",      "app_version": "2.4.0"    },    "properties": {      "location": "onboarding-end",      "paywall": "annual-upsell"    },    "distinct_id": "user_8231",    "timestamp": "2026-03-14T09:25:40.000Z",    "sent_at": "2026-03-14T09:25:41.000Z"  }'

{  "accepted": 1,  "rejected": 0}

{  "_tag": "CaptureInvalidRequestError",  "error": "string",  "code": "invalid_request"}

{  "_tag": "CaptureUnauthorizedError",  "error": "string",  "code": "unauthorized"}

{  "_tag": "CapturePayloadTooLargeError",  "error": "string",  "code": "payload_too_large"}

{  "_tag": "CaptureRateLimitedError",  "error": "string",  "code": "rate_limited",  "retry_after_ms": -9007199254740991}

{  "_tag": "CaptureInternalServerError",  "error": "string",  "code": "internal_error"}

{  "_tag": "CaptureDependencyUnavailableError",  "error": "string",  "code": "dependency_unavailable"}

Response body

`application/json`

Header parameters

x-secret-key?string

A project secret key, vh_sk_..., for requests from your servers. Leave it out when the body has a publishable token.

Request body

application/json

TypeScript definitions

Use the request body type in TypeScript.

uuid*string

The event's id: a UUID you generate once and send unchanged on every retry, so the event is stored once.

Length1 <= length

event*string

The event's name, such as paywall_viewed.

Length1 <= length

context*

Facts about the app and device that sent it, such as platform and app_version.

properties*

The event's properties, as JSON values. $set and $set_once hold traits to set on the person.

distinct_id*string

The distinct id of the person it happened to.

Length1 <= length

session_id?|

The session it belongs to, when the sender tracks sessions.

timestamp*string

When it happened on the device, as an ISO 8601 timestamp. Voidhash corrects it by how far the device's clock is off, measured with sent_at.

sent_at*string

When the request was sent, as an ISO 8601 timestamp. Voidhash compares it with when the request arrived to correct the events' times.

token?|

The project's publishable key, vh_pk_..., for clients that cannot hold a secret. Send it or the x-secret-key header; a secret key here is refused.

Examples

curl -X POST "https://api.voidhash.com/i/v1/capture" \  -H "x-secret-key: vh_sk_..." \  -H "Content-Type: application/json" \  -d '{    "uuid": "018f6d2e-4c3a-7b1d-9e5f-2a8c1b0d4e6f",    "event": "paywall_viewed",    "context": {      "platform": "ios",      "app_version": "2.4.0"    },    "properties": {      "location": "onboarding-end",      "paywall": "annual-upsell"    },    "distinct_id": "user_8231",    "timestamp": "2026-03-14T09:25:40.000Z",    "sent_at": "2026-03-14T09:25:41.000Z"  }'

{  "accepted": 1,  "rejected": 0}

{  "_tag": "CaptureInvalidRequestError",  "error": "string",  "code": "invalid_request"}

{  "_tag": "CaptureUnauthorizedError",  "error": "string",  "code": "unauthorized"}

{  "_tag": "CapturePayloadTooLargeError",  "error": "string",  "code": "payload_too_large"}

{  "_tag": "CaptureRateLimitedError",  "error": "string",  "code": "rate_limited",  "retry_after_ms": -9007199254740991}

{  "_tag": "CaptureInternalServerError",  "error": "string",  "code": "internal_error"}

{  "_tag": "CaptureDependencyUnavailableError",  "error": "string",  "code": "dependency_unavailable"}

Capture an event

Header parameters

Request body

Examples

Response body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

More in Event capture

Capture an event

Header parameters

Request body

Examples

Response body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

More in Event capture

Capture an event

202application/json

400application/json

401application/json

413application/json

429application/json

500application/json

503application/json

Capture an event

202application/json

400application/json

401application/json

413application/json

429application/json

500application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`