Skip to main content
POST

Authorizations

Authorization
string
header
required

A Curious API key: curious_sk_… (secret) or curious_pk_… (publishable), live or test environment (curious_sk_test_…). Publishable keys are serve-only and origin-gated; declare and identify require a secret key. A revoked or unknown key is a 401.

Headers

X-Curious-Client
string

The Curious SDK's self-identification, browser-js/<semver> for the browser SDK. Optional for customer events. Required — together with a publishable key — for the system events $pageview, $click and $form_submit: without it, or under a secret key, those names are rejected as reserved.

Maximum string length: 64
Pattern: ^(?:browser-js|sdk-js)/[0-9]{1,4}\.[0-9]{1,4}\.[0-9]{1,4}(?:-[0-9A-Za-z.-]{1,32})?$

Body

application/json

Unknown fields are ignored, except created_at (system-owned) and the retired as_of, which are a 400. A body with events is the batch form, whatever else it carries.

user_id
string
required
Minimum string length: 1
Pattern: \S
name
string
required

Past tense (purchased, clicked). Names starting with $ are reserved for Curious SDK system events: a customer integration sending one gets a 400 (rename at the source, e.g. $pageview → pageview). The only $ names the schema admits are the browser SDK's own — $pageview, $click and $form_submit — and the endpoint accepts them only under a publishable key with the SDK's client header (SystemEventConstraints bounds their properties).

Minimum string length: 1
Pattern: ^(?:\s*[^\s$]|\$(?:pageview|click|form_submit)$)
events
any

Not on a singular event; its presence selects the batch form.

as_of
any

The wire name until 2026-10-15; rejected rather than ignored, because ignoring it would mean receipt time.

id
string

The caller's id for this event; makes it idempotent per organization and environment.

Minimum string length: 1
value
number | null
default:1

Finite. Null and absent both mean 1.

properties
object

Facts about the event, never about the user.

context
object

Situational facts at event time.

timestamp
string

When the event happened: an ISO-8601 datetime with an explicit timezone (2026-04-30T22:33:42Z, 2026-04-30 22:33:42+00:00, +00 and +0000 offsets included) or a date, read as UTC midnight. A naive datetime is rejected. Must be a real calendar date and at most 5 minutes in the future. Defaults to receipt.

Pattern: ^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|z|[+-]\d{2}(?::?\d{2})?))?$
created_at
any

created_at is the row's write time and system-owned; sending it is a 400. Send the event's time as timestamp.

Response

Success (singular form), or the per-item results (batch form).

status
string
required
Allowed value: "success"
duplicate
boolean

Present when an event with this id already existed.