Skip to main content
POST
Configure an element without serving a user

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.

Body

application/json
element
string
required
Minimum string length: 1
Pattern: \S
control

The counterfactual baseline: the content you would serve without Curious. Singular, never an array; required whenever the call creates an experiment. A changed control supersedes the experiment.

arms

Additional starting points beside the control: one entry or a list, each bare content or {content, hypothesis}. Additive and idempotent: an entry the experiment already has is skipped. Entries that duplicate an earlier entry in the same request are skipped with an arm_invalid warning, and so are entries that violate the format or the requirements, or that would exceed the 50-active-arm cap. Two rules are request errors (400): an entry whose content equals the control's, and more than 10 distinct entries after duplicates are dropped — the limit counts distinct contents, so the list itself is not capped here.

rewards

The rewards the experiment optimizes. Shorthand: a name, an object, or a list of either; a bare name means a binary reward with weight 1 and a one-day window.

Minimum string length: 1
constraints
object[]

Guardrails an arm may not breach. Each (name, type, bound, properties) identity may appear once; threshold, threshold_type and window_seconds are its adjustable fields. Changing constraints never supersedes the experiment.

requirements
object

Phrase rules every arm must satisfy. Changing them supersedes the experiment.

instructions
string
element_type
enum<string> | null

The element's kind. Case-insensitive on input. Null means unset.

Available options:
push_notification,
email_subject,
email_preview,
email_body,
email,
button_cta,
hero,
landing_page,
blog_post,
paywall,
null
format
object

The structural content contract: a single field spec, or an object of named field specs. Omitted on a first call, it is inferred from the control; declared, the control must match it. A changed format supersedes the experiment.

variables
string[]

Names that arm content may reference as {{name|fallback}}, substituted from the user's identifiers and attributes at decision time. Defaults, on creation, to the identifier and attribute keys sent. Updates in place.

Pattern: ^\w+$
parameters
object

Element-content facts fixed for the experiment and reproduced verbatim through {{placeholders}}. Keys match ^\w+$; the namespace is disjoint from variables. Any change supersedes the experiment.

options
object

Serving-policy knobs. assignment, approval and minimum_effect_size update in place; holdout is fixed for the experiment's life and a differing value supersedes it. Every default is resolved when the experiment is created and stored with it, so a later change to a default never alters a live experiment; an omitted key on a later call carries the stored value forward.

Response

The element and its live experiment after the declaration was applied.

element_id
string<uuid>
required
experiment_id
string<uuid>
required
experiment_status
enum<string>
required

initializing until the first model is minted, then exploring; concluded is terminal.

Available options:
initializing,
exploring,
concluded
warnings
object[]
Minimum array length: 1