Capture a batch of events

Captures 1 to 100 events in one request, authorized like a single capture.

One invalid event rejects the whole request. Answers 202 with how many events were stored.

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.

events*array<>

The events, 1 to 100.

Items1 <= items

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/batch" \  -H "x-secret-key: vh_sk_..." \  -H "Content-Type: application/json" \  -d '{    "events": [      {        "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"      },      {        "uuid": "018f6d2e-4c3b-7a2e-8f10-3b9d2c1e5f70",        "event": "level_completed",        "context": {          "platform": "ios",          "app_version": "2.4.0"        },        "properties": {          "level": 4        },        "distinct_id": "user_8231",        "timestamp": "2026-03-14T09:31:02.000Z"      }    ],    "sent_at": "2026-03-14T09:31:05.000Z"  }'

{  "accepted": 2,  "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.

events*array<>

The events, 1 to 100.

Items1 <= items

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/batch" \  -H "x-secret-key: vh_sk_..." \  -H "Content-Type: application/json" \  -d '{    "events": [      {        "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"      },      {        "uuid": "018f6d2e-4c3b-7a2e-8f10-3b9d2c1e5f70",        "event": "level_completed",        "context": {          "platform": "ios",          "app_version": "2.4.0"        },        "properties": {          "level": 4        },        "distinct_id": "user_8231",        "timestamp": "2026-03-14T09:31:02.000Z"      }    ],    "sent_at": "2026-03-14T09:31:05.000Z"  }'

{  "accepted": 2,  "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 a batch of events

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 a batch of events

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 a batch of events

202application/json

400application/json

401application/json

413application/json

429application/json

500application/json

503application/json

Capture a batch of events

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`